1@c Copyright (C) 1996-2019 John W. Eaton 2@c 3@c This file is part of Octave. 4@c 5@c Octave is free software: you can redistribute it and/or modify it 6@c under the terms of the GNU General Public License as published by 7@c the Free Software Foundation, either version 3 of the License, or 8@c (at your option) any later version. 9@c 10@c Octave is distributed in the hope that it will be useful, but 11@c WITHOUT ANY WARRANTY; without even the implied warranty of 12@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the 13@c GNU General Public License for more details. 14@c 15@c You should have received a copy of the GNU General Public License 16@c along with Octave; see the file COPYING. If not, see 17@c <https://www.gnu.org/licenses/>. 18 19@node Introduction 20@chapter A Brief Introduction to Octave 21@cindex introduction 22 23GNU Octave is a high-level language primarily intended for numerical 24computations. It is typically used for such problems as solving 25linear and nonlinear equations, numerical linear algebra, statistical 26analysis, and for performing other numerical experiments. It may also 27be used as a batch-oriented language for automated data processing. 28 29The current version of Octave executes in a graphical user interface 30(GUI). The GUI hosts an Integrated Development Environment (IDE) 31which includes a code editor with syntax highlighting, built-in 32debugger, documentation browser, as well as the interpreter for the 33language itself. A command-line interface for Octave is also available. 34 35GNU Octave is freely redistributable software. You may redistribute 36it and/or modify it under the terms of the GNU General Public License 37as published by the Free Software Foundation. The GPL is included in 38this manual, @pxref{Copying}. 39 40This manual provides comprehensive documentation on how to install, 41run, use, and extend GNU Octave. Additional chapters describe how 42to report bugs and help contribute code. 43 44This document corresponds to Octave version @value{VERSION}. 45 46@menu 47* Running Octave:: 48* Simple Examples:: 49* Conventions:: 50@end menu 51 52@node Running Octave 53@section Running Octave 54 55On most systems, Octave is started with the shell command @samp{octave}. 56This starts the graphical user interface. The central window in the GUI 57is the Octave command-line interface. In this window Octave displays an 58initial message and then a prompt indicating it is ready to accept 59input. If you have chosen the traditional command-line interface then 60only the command prompt appears in the same window that was running 61a shell. In either case, you can immediately begin typing Octave 62commands. 63 64If you get into trouble, you can usually interrupt Octave by typing 65@kbd{Control-C} (written @kbd{C-c} for short). @kbd{C-c} gets 66its name from the fact that you type it by holding down @key{CTRL} and 67then pressing @key{c}. Doing this will normally return you to Octave's 68prompt. 69 70@cindex exiting octave 71@cindex quitting octave 72To exit Octave, type @kbd{quit} or @kbd{exit} at the Octave prompt. 73 74On systems that support job control, you can suspend Octave by sending 75it a @code{SIGTSTP} signal, usually by typing @kbd{C-z}. 76 77@node Simple Examples 78@section Simple Examples 79 80The following chapters describe all of Octave's features in detail, but 81before doing that, it might be helpful to give a sampling of some of its 82capabilities. 83 84If you are new to Octave, we recommend that you try these examples to 85begin learning Octave by using it. Lines marked like so, 86@samp{octave:13>}, are lines you type, ending each with a carriage 87return. Octave will respond with an answer, or by displaying a graph. 88 89@subsection Elementary Calculations 90 91Octave can easily be used for basic numerical calculations. Octave 92knows about arithmetic operations (+,-,*,/), exponentiation (^), 93natural logarithms/exponents (log, exp), and the trigonometric 94functions (sin, cos, @dots{}). Moreover, Octave calculations work 95on real or imaginary numbers (i,j). In addition, some mathematical 96constants such as the base of the natural logarithm (e) and the ratio 97of a circle's circumference to its diameter (pi) are pre-defined. 98 99@noindent 100For example, to verify @nospell{Euler's} Identity, 101@tex 102$$e^{\imath\pi} = -1$$ 103@end tex 104@ifnottex 105@display 106 107 i*pi 108e = -1 109@end display 110@end ifnottex 111 112@noindent 113type the following which will evaluate to @code{-1} within the 114tolerance of the calculation. 115 116@example 117octave:1> exp (i*pi) 118@end example 119 120@subsection Creating a Matrix 121 122Vectors and matrices are the basic building blocks for numerical 123analysis. To create a new matrix and store it in a variable so that you 124can refer to it later, type the command 125 126@example 127octave:1> A = [ 1, 1, 2; 3, 5, 8; 13, 21, 34 ] 128@end example 129 130@noindent 131Octave will respond by printing the matrix in neatly aligned columns. 132Octave uses a comma or space to separate entries in a row, and a 133semicolon or carriage return to separate one row from the next. 134Ending a command with a semicolon tells Octave not to print the result 135of the command. For example, 136 137@example 138octave:2> B = rand (3, 2); 139@end example 140 141@noindent 142will create a 3 row, 2 column matrix with each element set to a random 143value between zero and one. 144 145To display the value of a variable, simply type the name of the 146variable at the prompt. For example, to display the value stored in the 147matrix @code{B}, type the command 148 149@example 150octave:3> B 151@end example 152 153@subsection Matrix Arithmetic 154 155Octave uses standard mathematical notation with the advantage over 156low-level languages that operators may act on scalars, vector, matrices, 157or N-dimensional arrays. For example, to multiply the matrix @code{A} 158by a scalar value, type the command 159 160@example 161octave:4> 2 * A 162@end example 163 164@noindent 165To multiply the two matrices @code{A} and @code{B}, type the command 166 167@example 168octave:5> A * B 169@end example 170 171@noindent 172and to form the matrix product 173@tex 174$@code{A}^T@code{A}$, 175@end tex 176@ifnottex 177@code{transpose (A) * A}, 178@end ifnottex 179type the command 180 181@example 182octave:6> A' * A 183@end example 184 185@subsection Solving Systems of Linear Equations 186 187Systems of linear equations are ubiquitous in numerical analysis. 188To solve the set of linear equations @code{A@var{x} = b}, 189use the left division operator, @samp{\}: 190 191@example 192@var{x} = A \ b 193@end example 194 195@noindent 196This is conceptually equivalent to 197@tex 198$@code{A}^{-1}@code{b}$, 199@end tex 200@ifnottex 201@code{inv (A) * b}, 202@end ifnottex 203but avoids computing the inverse of a matrix directly. 204 205If the coefficient matrix is singular, Octave will print a warning 206message and compute a minimum norm solution. 207 208A simple example comes from chemistry and the need to obtain balanced 209chemical equations. Consider the burning of hydrogen and oxygen to 210produce water. 211@tex 212$$ {\rm H_{2}} + {\rm O_{2}} \rightarrow {\rm H_{2}O} $$ 213@end tex 214@ifnottex 215 216@example 217H2 + O2 --> H2O 218@end example 219 220@end ifnottex 221@noindent 222The equation above is not accurate. The Law of Conservation of Mass requires 223that the number of molecules of each type balance on the left- and right-hand 224sides of the equation. Writing the variable overall reaction with 225individual equations for hydrogen and oxygen one finds: 226@tex 227\vbox{ 228$$ x_{1}{\rm H_{2}} + x_{2}{\rm O_{2}} \rightarrow {\rm H_{2}O} $$ 229$$ {\rm H:}\quad 2x_{1} + 0x_{2} \rightarrow 2 $$ 230$$ {\rm O:}\quad 0x_{1} + 2x_{2} \rightarrow 1 $$ 231} 232@end tex 233@ifnottex 234 235@example 236@group 237x1*H2 + x2*O2 --> H2O 238H: 2*x1 + 0*x2 --> 2 239O: 0*x1 + 2*x2 --> 1 240@end group 241@end example 242 243@end ifnottex 244@noindent 245The solution in Octave is found in just three steps. 246 247@example 248@group 249octave:1> A = [ 2, 0; 0, 2 ]; 250octave:2> b = [ 2; 1 ]; 251octave:3> x = A \ b 252@end group 253@end example 254 255@subsection Integrating Differential Equations 256 257Octave has built-in functions for solving nonlinear differential 258equations of the form 259@tex 260$$ 261 {dx \over dt} = f(x,t), \qquad x(t=t_0) = x_0 262$$ 263@end tex 264@ifnottex 265 266@example 267@group 268dx 269-- = f (x, t) 270dt 271@end group 272@end example 273 274@noindent 275with the initial condition 276 277@example 278x(t = t0) = x0 279@end example 280 281@end ifnottex 282@noindent 283For Octave to integrate equations of this form, you must first provide a 284definition of the function 285@tex 286$f (x, t)$. 287@end tex 288@ifnottex 289@code{f(x,t)}. 290@end ifnottex 291This is straightforward, and may be accomplished by entering the 292function body directly on the command line. For example, the following 293commands define the right-hand side function for an interesting pair of 294nonlinear differential equations. Note that while you are entering a 295function, Octave responds with a different prompt, to indicate that it 296is waiting for you to complete your input. 297 298@example 299@group 300octave:1> function xdot = f (x, t) 301> 302> r = 0.25; 303> k = 1.4; 304> a = 1.5; 305> b = 0.16; 306> c = 0.9; 307> d = 0.8; 308> 309> xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1)); 310> xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2); 311> 312> endfunction 313@end group 314@end example 315 316@noindent 317Given the initial condition 318 319@example 320octave:2> x0 = [1; 2]; 321@end example 322 323@noindent 324and the set of output times as a column vector (note that the first 325output time corresponds to the initial condition given above) 326 327@example 328octave:3> t = linspace (0, 50, 200)'; 329@end example 330 331@noindent 332it is easy to integrate the set of differential equations: 333 334@example 335octave:4> x = lsode ("f", x0, t); 336@end example 337 338@noindent 339The function @code{lsode} uses the Livermore Solver for Ordinary 340Differential Equations, described in @nospell{A. C. Hindmarsh}, 341@cite{ODEPACK, a Systematized Collection of ODE Solvers}, in: Scientific 342Computing, @nospell{R. S. Stepleman} et al. (Eds.), North-Holland, Amsterdam, 3431983, pages 55--64. 344 345@subsection Producing Graphical Output 346 347To display the solution of the previous example graphically, use the 348command 349 350@example 351octave:1> plot (t, x) 352@end example 353 354@noindent 355Octave will automatically create a separate window to display the plot. 356 357To save a plot once it has been displayed on the screen, use the print 358command. For example, 359 360@example 361print foo.pdf 362@end example 363 364@noindent 365will create a file called @file{foo.pdf} that contains a rendering of 366the current plot in Portable Document Format. The command 367 368@example 369help print 370@end example 371 372@noindent 373explains more options for the @code{print} command and provides a list 374of additional output file formats. 375 376@subsection Help and Documentation 377 378Octave has an extensive help facility. The same documentation that is 379available in printed form is also available from the Octave prompt, 380because both forms of the documentation are created from the same input 381file. 382 383In order to get good help you first need to know the name of the command 384that you want to use. The name of this function may not always be 385obvious, but a good place to start is to type @code{help --list}. 386This will show you all the operators, keywords, built-in functions, 387and loadable functions available in the current session of Octave. An 388alternative is to search the documentation using the @code{lookfor} 389function (described in @ref{Getting Help}). 390 391Once you know the name of the function you wish to use, you can get more 392help on the function by simply including the name as an argument to help. 393For example, 394 395@example 396help plot 397@end example 398 399@noindent 400will display the help text for the @code{plot} function. 401 402The part of Octave's help facility that allows you to read the complete 403text of the printed manual from within Octave normally uses a separate 404program called Info. When you invoke Info you will be put into a menu 405driven program that contains the entire Octave manual. Help for using 406Info is provided in this manual, @pxref{Getting Help}. 407 408@subsection Editing What You Have Typed 409 410At the Octave prompt, you can recall, edit, and reissue previous 411commands using Emacs- or vi-style editing commands. The default 412keybindings use Emacs-style commands. For example, to recall the 413previous command, press @kbd{Control-p} (written @kbd{C-p} for 414short). Doing this will normally bring back the previous line of input. 415@kbd{C-n} will bring up the next line of input, @kbd{C-b} will move 416the cursor backward on the line, @kbd{C-f} will move the cursor forward 417on the line, etc. 418 419A complete description of the command line editing capability is given 420in this manual, @pxref{Command Line Editing}. 421 422@node Conventions 423@section Conventions 424 425This section explains the notation conventions that are used in this 426manual. You may want to skip this section and refer back to it later. 427 428@menu 429* Fonts:: 430* Evaluation Notation:: 431* Printing Notation:: 432* Error Messages:: 433* Format of Descriptions:: 434@end menu 435 436@node Fonts 437@subsection Fonts 438@cindex documentation fonts 439 440Examples of Octave code appear in this font or form: @w{@code{svd (a)}}. 441Names that represent variables or function arguments appear in this font 442or form: @var{first-number}. Commands that you type at the shell prompt 443appear in this font or form: @w{@samp{octave --no-init-file}}. Commands 444that you type at the Octave prompt sometimes appear in this font or 445form: @w{@kbd{foo --bar --baz}}. Specific keys on your keyboard appear 446in this font or form: @key{RET}. 447 448@node Evaluation Notation 449@subsection Evaluation Notation 450@cindex evaluation notation 451@cindex documentation notation 452 453In the examples in this manual, results from expressions that you 454evaluate are indicated with @samp{@result{}}. For example: 455 456@example 457@group 458sqrt (2) 459 @result{} 1.4142 460@end group 461@end example 462 463@noindent 464You can read this as ``@code{sqrt (2)} evaluates to 1.4142''. 465 466In some cases, matrix values that are returned by expressions are 467displayed like this 468 469@example 470@group 471[1, 2; 3, 4] == [1, 3; 2, 4] 472 @result{} [ 1, 0; 0, 1 ] 473@end group 474@end example 475 476@noindent 477and in other cases, they are displayed like this 478 479@example 480@group 481eye (3) 482 @result{} 1 0 0 483 0 1 0 484 0 0 1 485@end group 486@end example 487 488@noindent 489in order to clearly show the structure of the result. 490 491Sometimes to help describe one expression, another expression is shown 492that produces identical results. The exact equivalence of expressions 493is indicated with @samp{@equiv{}}. For example: 494 495@example 496@group 497rot90 ([1, 2; 3, 4], -1) 498@equiv{} 499rot90 ([1, 2; 3, 4], 3) 500@equiv{} 501rot90 ([1, 2; 3, 4], 7) 502@end group 503@end example 504 505@node Printing Notation 506@subsection Printing Notation 507@cindex printing notation 508 509Many of the examples in this manual print text when they are evaluated. 510In this manual the printed text resulting from an example is indicated 511by @samp{@print{}}. The value that is returned by evaluating the 512expression is displayed with @samp{@result{}} (@code{1} in the next 513example) and follows on a separate line. 514 515@example 516@group 517printf ("foo %s\n", "bar") 518 @print{} foo bar 519 @result{} 1 520@end group 521@end example 522 523@node Error Messages 524@subsection Error Messages 525@cindex error message notation 526 527Some examples signal errors. This normally displays an error message 528on your terminal. Error messages are shown on a line beginning with 529@code{error:}. 530 531@example 532@group 533fieldnames ([1, 2; 3, 4]) 534error: fieldnames: Invalid input argument 535@end group 536@end example 537 538@node Format of Descriptions 539@subsection Format of Descriptions 540@cindex description format 541 542Functions and commands are described in this manual in a uniform format. 543The first line of a description contains the name of the item followed 544by its arguments, if any. If there are multiple ways to invoke the 545function then each allowable form is listed. 546 547The description follows on succeeding lines, sometimes with examples. 548 549@menu 550* A Sample Function Description:: 551* A Sample Command Description:: 552@end menu 553 554@node A Sample Function Description 555@subsubsection A Sample Function Description 556@cindex function descriptions 557 558In a function description, the name of the function being described 559appears first. It is followed on the same line by a list of parameters. 560The names used for the parameters are also used in the body of the 561description. 562 563After all of the calling forms have been enumerated, the next line is a 564concise one-sentence summary of the function. 565 566After the summary there may be documentation on the inputs and outputs, 567examples of function usage, notes about the algorithm used, and references 568to related functions. 569 570Here is a description of an imaginary function @code{foo}: 571 572@need 4000 573@deftypefn {} {} foo (@var{x}) 574@deftypefnx {} {} foo (@var{x}, @var{y}) 575@deftypefnx {} {} foo (@var{x}, @var{y}, @dots{}) 576Subtract @var{x} from @var{y}, then add any remaining arguments to the 577result. 578 579The input @var{x} must be a numeric scalar, vector, or array. 580 581The optional input @var{y} defaults to 19 if it is not supplied. 582 583Example: 584 585@example 586@group 587foo (1, [3, 5], 3, 9) 588 @result{} [ 14, 16 ] 589foo (5) 590 @result{} 14 591@end group 592@end example 593 594More generally, 595 596@example 597@group 598foo (@var{w}, @var{x}, @var{y}, @dots{}) 599@equiv{} 600@var{x} - @var{w} + @var{y} + @dots{} 601@end group 602@end example 603 604@b{See also:} bar 605@end deftypefn 606 607Any parameter whose name contains the name of a type (e.g., 608@var{integer} or @var{matrix}) is expected to be of that 609type. Parameters named @var{object} may be of any type. Parameters 610with other sorts of names (e.g., @var{new_file}) are discussed 611specifically in the description of the function. In some sections, 612features common to parameters of several functions are described at the 613beginning. 614 615@node A Sample Command Description 616@subsubsection A Sample Command Description 617@cindex command descriptions 618 619Commands are functions that may be called without surrounding their arguments 620in parentheses. Command descriptions have a format similar to function 621descriptions. For example, here is the description for Octave's @code{diary} 622command: 623 624@need 4000 625@deftypefn {} {} diary 626@deftypefnx {} {} diary on 627@deftypefnx {} {} diary off 628@deftypefnx {} {} diary @var{filename} 629@deftypefnx {} {[@var{status}, @var{diaryfile}] =} diary 630Record a list of all commands @emph{and} the output they produce, mixed 631together just as they appear on the terminal. 632 633Valid options are: 634 635@table @asis 636@item on 637Start recording a session in a file called @file{diary} in the current working 638directory. 639 640@item off 641Stop recording the session in the diary file. 642 643@item @var{filename} 644Record the session in the file named @var{filename}. 645@end table 646 647With no input or output arguments, @code{diary} toggles the current diary 648state. 649 650If output arguments are requested, @code{diary} ignores inputs and returns 651the current status. The boolean @var{status} indicates whether recording is on 652or off, and @var{diaryfile} is the name of the file where the session is 653stored. 654@seealso{history, evalc} 655@end deftypefn 656