@c Copyright (C) 1996-2019 John W. Eaton
@c
@c This file is part of Octave.
@c
@c Octave is free software: you can redistribute it and/or modify it
@c under the terms of the GNU General Public License as published by
@c the Free Software Foundation, either version 3 of the License, or
@c (at your option) any later version.
@c
@c Octave is distributed in the hope that it will be useful, but
@c WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU General Public License for more details.
@c
@c You should have received a copy of the GNU General Public License
@c along with Octave; see the file COPYING.  If not, see
@c <https://www.gnu.org/licenses/>.

@node Introduction
@chapter A Brief Introduction to Octave
@cindex introduction

GNU Octave is a high-level language primarily intended for numerical
computations.  It is typically used for such problems as solving
linear and nonlinear equations, numerical linear algebra, statistical
analysis, and for performing other numerical experiments.  It may also
be used as a batch-oriented language for automated data processing.

The current version of Octave executes in a graphical user interface
(GUI).  The GUI hosts an Integrated Development Environment (IDE)
which includes a code editor with syntax highlighting, built-in
debugger, documentation browser, as well as the interpreter for the
language itself.  A command-line interface for Octave is also available.

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, @pxref{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 @value{VERSION}.

@menu
* Running Octave::
* Simple Examples::
* Conventions::
@end menu

@node Running Octave
@section Running Octave

On most systems, Octave is started with the shell command @samp{octave}.
This starts the graphical user interface.  The central window in the GUI
is the Octave command-line interface.  In this window Octave displays an
initial message and then a prompt indicating it is ready to accept
input.  If you have chosen the traditional command-line interface then
only the command prompt appears in the same window that was running
a shell.  In either case, you can immediately begin typing Octave
commands.

If you get into trouble, you can usually interrupt Octave by typing
@kbd{Control-C} (written @kbd{C-c} for short).  @kbd{C-c} gets
its name from the fact that you type it by holding down @key{CTRL} and
then pressing @key{c}.  Doing this will normally return you to Octave's
prompt.

@cindex exiting octave
@cindex quitting octave
To exit Octave, type @kbd{quit} or @kbd{exit} at the Octave prompt.

On systems that support job control, you can suspend Octave by sending
it a @code{SIGTSTP} signal, usually by typing @kbd{C-z}.

@node Simple Examples
@section 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, we recommend that you try these examples to
begin learning Octave by using it.  Lines marked like so,
@samp{octave:13>}, are lines you type, ending each with a carriage
return.  Octave will respond with an answer, or by displaying a graph.

@subsection 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, @dots{}).  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.

@noindent
For example, to verify @nospell{Euler's} Identity,
@tex
$$e^{\imath\pi} = -1$$
@end tex
@ifnottex
@display

 i*pi
e     = -1
@end display
@end ifnottex

@noindent
type the following which will evaluate to @code{-1} within the
tolerance of the calculation.

@example
octave:1> exp (i*pi)
@end example

@subsection 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

@example
octave:1> A = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ]
@end example

@noindent
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,

@example
octave:2> B = rand (3, 2);
@end example

@noindent
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 @code{B}, type the command

@example
octave:3> B
@end example

@subsection Matrix Arithmetic

Octave uses standard mathematical notation with the advantage over
low-level languages that operators may act on scalars, vector, matrices,
or N-dimensional arrays.  For example, to multiply the matrix @code{A}
by a scalar value, type the command

@example
octave:4> 2 * A
@end example

@noindent
To multiply the two matrices @code{A} and @code{B}, type the command

@example
octave:5> A * B
@end example

@noindent
and to form the matrix product
@tex
$@code{A}^T@code{A}$,
@end tex
@ifnottex
@code{transpose (A) * A},
@end ifnottex
type the command

@example
octave:6> A' * A
@end example

@subsection Solving Systems of Linear Equations

Systems of linear equations are ubiquitous in numerical analysis.
To solve the set of linear equations @code{A@var{x} = b},
use the left division operator, @samp{\}:

@example
@var{x} = A \ b
@end example

@noindent
This is conceptually equivalent to
@tex
$@code{A}^{-1}@code{b}$,
@end tex
@ifnottex
@code{inv (A) * b},
@end ifnottex
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.
@tex
$$ {\rm H_{2}} + {\rm O_{2}} \rightarrow {\rm H_{2}O} $$
@end tex
@ifnottex

@example
H2 + O2 --> H2O
@end example

@end ifnottex
@noindent
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:
@tex
\vbox{
$$ x_{1}{\rm H_{2}} + x_{2}{\rm O_{2}} \rightarrow {\rm H_{2}O} $$
$$ {\rm H:}\quad 2x_{1} + 0x_{2} \rightarrow 2 $$
$$ {\rm O:}\quad 0x_{1} + 2x_{2} \rightarrow 1 $$
}
@end tex
@ifnottex

@example
@group
x1*H2 + x2*O2 --> H2O
H: 2*x1 + 0*x2 --> 2
O: 0*x1 + 2*x2 --> 1
@end group
@end example

@end ifnottex
@noindent
The solution in Octave is found in just three steps.

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

@subsection Integrating Differential Equations

Octave has built-in functions for solving nonlinear differential
equations of the form
@tex
$$
 {dx \over dt} = f(x,t), \qquad x(t=t_0) = x_0
$$
@end tex
@ifnottex

@example
@group
dx
-- = f (x, t)
dt
@end group
@end example

@noindent
with the initial condition

@example
x(t = t0) = x0
@end example

@end ifnottex
@noindent
For Octave to integrate equations of this form, you must first provide a
definition of the function
@tex
$f (x, t)$.
@end tex
@ifnottex
@code{f(x,t)}.
@end ifnottex
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.

@example
@group
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
@end group
@end example

@noindent
Given the initial condition

@example
octave:2> x0 = [1; 2];
@end example

@noindent
and the set of output times as a column vector (note that the first
output time corresponds to the initial condition given above)

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

@noindent
it is easy to integrate the set of differential equations:

@example
octave:4> x = lsode ("f", x0, t);
@end example

@noindent
The function @code{lsode} uses the Livermore Solver for Ordinary
Differential Equations, described in @nospell{A. C. Hindmarsh},
@cite{ODEPACK, a Systematized Collection of ODE Solvers}, in: Scientific
Computing, @nospell{R. S. Stepleman} et al. (Eds.), North-Holland, Amsterdam,
1983, pages 55--64.

@subsection Producing Graphical Output

To display the solution of the previous example graphically, use the
command

@example
octave:1> plot (t, x)
@end example

@noindent
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,

@example
print foo.pdf
@end example

@noindent
will create a file called @file{foo.pdf} that contains a rendering of
the current plot in Portable Document Format.  The command

@example
help print
@end example

@noindent
explains more options for the @code{print} command and provides a list
of additional output file formats.

@subsection 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.  The name of this function may not always be
obvious, but a good place to start is to type @code{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 @code{lookfor}
function (described in @ref{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,

@example
help plot
@end example

@noindent
will display the help text for the @code{plot} function.

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, @pxref{Getting Help}.

@subsection 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 @kbd{Control-p} (written @kbd{C-p} for
short).  Doing this will normally bring back the previous line of input.
@kbd{C-n} will bring up the next line of input, @kbd{C-b} will move
the cursor backward on the line, @kbd{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, @pxref{Command Line Editing}.

@node Conventions
@section Conventions

This section explains the notation 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::
@end menu

@node Fonts
@subsection Fonts
@cindex documentation fonts

Examples of Octave code appear in this font or form: @w{@code{svd (a)}}.
Names that represent variables or function arguments appear in this font
or form: @var{first-number}.  Commands that you type at the shell prompt
appear in this font or form: @w{@samp{octave --no-init-file}}.  Commands
that you type at the Octave prompt sometimes appear in this font or
form: @w{@kbd{foo --bar --baz}}.  Specific keys on your keyboard appear
in this font or form: @key{RET}.

@node Evaluation Notation
@subsection Evaluation Notation
@cindex evaluation notation
@cindex documentation notation

In the examples in this manual, results from expressions that you
evaluate are indicated with @samp{@result{}}.  For example:

@example
@group
sqrt (2)
     @result{} 1.4142
@end group
@end example

@noindent
You can read this as ``@code{sqrt (2)} evaluates to 1.4142''.

In some cases, matrix values that are returned by expressions are
displayed like this

@example
@group
[1, 2; 3, 4] == [1, 3; 2, 4]
     @result{} [ 1, 0; 0, 1 ]
@end group
@end example

@noindent
and in other cases, they are displayed like this

@example
@group
eye (3)
     @result{}  1  0  0
         0  1  0
         0  0  1
@end group
@end example

@noindent
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 @samp{@equiv{}}.  For example:

@example
@group
rot90 ([1, 2; 3, 4], -1)
@equiv{}
rot90 ([1, 2; 3, 4], 3)
@equiv{}
rot90 ([1, 2; 3, 4], 7)
@end group
@end example

@node Printing Notation
@subsection Printing Notation
@cindex 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 @samp{@print{}}.  The value that is returned by evaluating the
expression is displayed with @samp{@result{}} (@code{1} in the next
example) and follows on a separate line.

@example
@group
printf ("foo %s\n", "bar")
     @print{} foo bar
     @result{} 1
@end group
@end example

@node Error Messages
@subsection Error Messages
@cindex error message notation

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

@example
@group
fieldnames ([1, 2; 3, 4])
error: fieldnames: Invalid input argument
@end group
@end example

@node Format of Descriptions
@subsection Format of Descriptions
@cindex description format

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.  If there are multiple ways to invoke the
function then each allowable form is listed.

The description follows on succeeding lines, sometimes with examples.

@menu
* A Sample Function Description::
* A Sample Command Description::
@end menu

@node A Sample Function Description
@subsubsection A Sample Function Description
@cindex function descriptions

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.

After all of the calling forms have been enumerated, the next line is a
concise one-sentence summary of the function.

After the summary there may be documentation on the inputs and outputs,
examples of function usage, notes about the algorithm used, and references
to related functions.

Here is a description of an imaginary function @code{foo}:

@need 4000
@deftypefn  {} {} foo (@var{x})
@deftypefnx {} {} foo (@var{x}, @var{y})
@deftypefnx {} {} foo (@var{x}, @var{y}, @dots{})
Subtract @var{x} from @var{y}, then add any remaining arguments to the
result.

The input @var{x} must be a numeric scalar, vector, or array.

The optional input @var{y} defaults to 19 if it is not supplied.

Example:

@example
@group
foo (1, [3, 5], 3, 9)
     @result{} [ 14, 16 ]
foo (5)
     @result{} 14
@end group
@end example

More generally,

@example
@group
foo (@var{w}, @var{x}, @var{y}, @dots{})
@equiv{}
@var{x} - @var{w} + @var{y} + @dots{}
@end group
@end example

@b{See also:} bar
@end deftypefn

Any parameter whose name contains the name of a type (e.g.,
@var{integer} or @var{matrix}) is expected to be of that
type.  Parameters named @var{object} may be of any type.  Parameters
with other sorts of names (e.g., @var{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.

@node A Sample Command Description
@subsubsection A Sample Command Description
@cindex command descriptions

Commands are functions that may be called without surrounding their arguments
in parentheses.  Command descriptions have a format similar to function
descriptions.  For example, here is the description for Octave's @code{diary}
command:

@need 4000
@deftypefn  {} {} diary
@deftypefnx {} {} diary on
@deftypefnx {} {} diary off
@deftypefnx {} {} diary @var{filename}
@deftypefnx {} {[@var{status}, @var{diaryfile}] =} diary
Record a list of all commands @emph{and} the output they produce, mixed
together just as they appear on the terminal.

Valid options are:

@table @asis
@item on
Start recording a session in a file called @file{diary} in the current working
directory.

@item off
Stop recording the session in the diary file.

@item @var{filename}
Record the session in the file named @var{filename}.
@end table

With no input or output arguments, @code{diary} toggles the current diary
state.

If output arguments are requested, @code{diary} ignores inputs and returns
the current status.  The boolean @var{status} indicates whether recording is on
or off, and @var{diaryfile} is the name of the file where the session is
stored.
@seealso{history, evalc}
@end deftypefn