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

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.

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

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  (The #! mechanism works on Unix systems derived from Berkeley Unix, System V Release 4, and some System V Release 3 systems.) (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  (The line beginning with #! lists the full file name of an interpreter to be run, and an optional initial command line argument to pass to that interpreter.  The operating system then runs the interpreter with the given argument and the full argument list of the executed program.  The first argument in the list is the full file name of the Octave program. The rest of the argument list will either be options to Octave, or data files, or both.  The -qf option is usually specified in stand-alone Octave programs to prevent them from printing the normal startup message, and to keep them from behaving differently depending on the contents of a particular user's ~/.octaverc file. See Invoking Octave.) 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.

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

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.