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

GNU Octave is a high-level language, primarily intended for numerical computations.  It provides a convenient interactive 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 for data processing.

GNU Octave is 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, see Copying.

This manual provides comprehensive documentation on how to install, run, use, and extend GNU Octave.  Additional chapters describe how to report bugs and help contribute code.

This document corresponds to Octave version VERSION.

Running Octave
==============

On most systems, Octave is started 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 (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.

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 like so, octave:13>, are lines you type, ending each with a carriage return.  Octave will respond with an answer, or by displaying a graph.

Elementary Calculations
-----------------------

Octave can easily be used for basic numerical calculations.  Octave knows about arithmetic operations (+,-,*,/), exponentiation (^), natural logarithms/exponents (log, exp), and the trigonometric functions (sin, cos, ...).  Moreover, Octave calculations work on real or imaginary numbers (i,j).  In addition, some mathematical constants such as the base of the natural logarithm (e) and the ratio of a circle's circumference to its diameter (pi) are pre-defined.

For example, to verify Euler's Identity,

      i*pi
     e     = -1

type the following which will evaluate to -1 within the tolerance of the calculation.

     octave:1> exp (i*pi)

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

Vectors and matrices are the basic building blocks for numerical analysis. To create a new matrix and store it in a variable so that 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. Octave uses a comma or space to separate entries in a row, and a semicolon or carriage return to separate one row from the next. Ending a command with a semicolon tells Octave not to print the result of the 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 a variable, simply type the name of the variable at the prompt.  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

and to form the matrix product transpose (A) * A, type the command

     octave:6> A' * A

Solving Systems of Linear Equations
-----------------------------------

Systems of linear equations are ubiquitous in numerical analysis. To solve the set of linear equations AX = b, use the left division operator, \:

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

A simple example comes from chemistry and the need to obtain balanced chemical equations.  Consider the burning of hydrogen and oxygen to produce water.

     H2 + O2 --> H2O

The equation above is not accurate.  The Law of Conservation of Mass requires that the number of molecules of each type balance on the left- and right-hand sides of the equation.  Writing the variable overall reaction with individual equations for hydrogen and oxygen one finds:

     x1*H2 + x2*O2 --> H2O
     H: 2*x1 + 0*x2 --> 2
     O: 0*x1 + 2*x2 --> 1

The solution in Octave is found in just three steps.

     octave:1> A = [ 2, 0; 0, 2 ];
     octave:2> b = [ 2; 1 ];
     octave:3> x = A \ b

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

     octave:2> 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)

     octave:3> t = linspace (0, 50, 200)';

it is easy to integrate the set of differential equations:

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

     octave:1> plot (t, x)

If you are using a graphical user interface, Octave will automatically create a separate window to display the plot.

To save a plot once it has been displayed on the screen, use the print command.  For example,

     print -deps foo.eps

will create a file called foo.eps that contains a rendering of the current plot in Encapsulated PostScript format.  The command

     help print

explains more options for the print command and provides a list of additional output file formats.

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, press Control-p (written C-p for short).  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, see 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 type help --list. This will show you all the operators, keywords, built-in functions, and loadable functions available in the current session of Octave.  An alternative is to search the documentation using the lookfor function.  This function is described in Getting Help.

Once you know the name of the function you wish to use, you can get more help on the function 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, see Getting Help.

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.

Fonts
-----

Examples of Octave code appear in this font or form: svd (a). Names that represent variables or function arguments appear in this font or form: FIRST-NUMBER.  Commands that you type at the shell prompt 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.

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)

Printing Notation
-----------------

Many of the examples in this manual print text when they are evaluated.  In this manual the printed text resulting from an example is indicated by -|.  The value that is returned by evaluating the expression is displayed with => (1 in the next example) and follows on a separate line.

     printf ("foo %s\n", "bar")
          -| foo bar
          => 1

Error Messages
--------------

Some examples signal errors.  This normally displays an error message on your terminal.  Error messages are shown on a line beginning with error:.

     fieldnames ([1, 2; 3, 4])
     error: fieldnames: wrong type argument 'matrix'

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

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

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 File: foo (X)
 -- Function File: foo (X, Y)
 -- Function File: 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 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 category name for functions may include another name that indicates the way that the function is defined.  These additional tags include

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

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.  See External Code Interface.

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

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