# HG changeset patch # User jwe # Date 856256952 0 # Node ID 8c7955a8d49f5ab8aedcf53b7ef13299f696d09c # Parent fe5e83216458d775332597c05e0315d0446a0dde [project @ 1997-02-18 09:06:10 by jwe] diff --git a/ChangeLog b/ChangeLog --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Tue Feb 18 00:33:36 1997 John W. Eaton + + * examples/oregonator.m, examples/oregonator.cc: New files. + * examples/Makefile.in (SOURCES): Add them to the list. + Fri Feb 14 14:07:08 1997 John W. Eaton * install-octave: Don't fail if LIBRARIES file is missing. diff --git a/doc/interpreter/Makefile.in b/doc/interpreter/Makefile.in --- a/doc/interpreter/Makefile.in +++ b/doc/interpreter/Makefile.in @@ -47,7 +47,7 @@ version_file := $(firstword $(foreach file, $(xfiles), $(wildcard $(file)))) -SPELL = $(patsubst %.texi, %.spell, $(ALL_TEXINFO)) +SPELL = $(patsubst %.texi, %.spell, $(TEXINFO)) %.spell : %.texi rm -f $@ diff --git a/doc/interpreter/arith.texi b/doc/interpreter/arith.texi --- a/doc/interpreter/arith.texi +++ b/doc/interpreter/arith.texi @@ -99,7 +99,7 @@ @var{f} and @var{e} such that @iftex @tex - $1/2 <= |f| < 1$ and $x = f * 2^e$. + $1/2 <= |f| < 1$ and $x = f \cdot 2^e$. @end tex @end iftex @ifinfo @@ -154,7 +154,7 @@ for each element of @var{x}. With two arguments, returns @iftex @tex - $f 2^e$. + $f \cdot 2^e$. @end tex @end iftex @ifinfo @@ -209,8 +209,8 @@ @deftypefn {Mapping Function} {} xor (@var{x}, @var{y}) Return the `exclusive or' of the entries of @var{x} and @var{y}. For boolean expressions @var{x} and @var{y}, -@code{xor (@var{x}, @var{y})} is true if and only if either @var{x} or -@var{y} is true. +@code{xor (@var{x}, @var{y})} is true if and only if @var{x} or @var{y} +is true, but not if both @var{x} and @var{y} are true. @end deftypefn @node Complex Arithmetic, Trigonometry, Utility Functions, Arithmetic @@ -218,23 +218,79 @@ The following functions are available for working with complex numbers. Each expects a single argument. Given a matrix they work on -an element by element basis. +an element by element basis. In the descriptions of the following +functions, +@iftex +@tex +$z$ is the complex number $x + iy$, where $i$ is defined as +$\sqrt{-1}$. +@end tex +@end iftex +@ifinfo +@var{z} is the complex number @var{x} + @var{i}@var{y}, where @var{i} is +defined as @code{sqrt (-1)}. +@end ifinfo @deftypefn {Mapping Function} {} abs (@var{z}) -Compute the magnitude of @var{z}. +Compute the magnitude of @var{z}, defined as +@iftex +@tex +$|z| = \sqrt{x^2 + y^2}$. +@end tex +@end iftex +@ifinfo +|@var{z}| = @code{sqrt (x^2 + y^2)}. +@end ifinfo + +For example, + +@example +@group +abs (3 + 4i) + @result{} 5 +@end group +@end example @end deftypefn @deftypefn {Mapping Function} {} arg (@var{z}) @deftypefnx {Mapping Function} {} angle (@var{z}) -Compute the argument of @var{z}. +Compute the argument of @var{z}, defined as +@iftex +@tex +$\theta = \tan^{-1}(y/x)$. +@end tex +@end iftex +@ifinfo +@var{theta} = @code{atan (@var{y}/@var{x})}. +@end ifinfo + +@noindent +in radians. + +For example, + +@example +@group +arg (3 + 4i) + @result{} 0.92730 +@end group +@end example @end deftypefn @deftypefn {Mapping Function} {} conj (@var{z}) -Return the complex conjugate of @var{z}. +Return the complex conjugate of @var{z}, defined as +@iftex +@tex +$\bar{z} = x - iy$. +@end tex +@end iftex +@ifinfo +@code{conj (@var{z})} = @var{x} - @var{i}@var{y}. +@end ifinfo @end deftypefn @deftypefn {Mapping Function} {} imag (@var{z}) -Return the imaginary part of @var{z}. +Return the imaginary part of @var{z} as a real number. @end deftypefn @deftypefn {Mapping Function} {} real (@var{z}) @@ -402,7 +458,35 @@ @end deftypefn @deftypefn {Mapping Function} {} bincoeff (@var{n}, @var{k}) -Returns the binomial coefficient of @var{n} and @var{k}. +Returns the binomial coefficient of @var{n} and @var{k}, defined as +@iftex +@tex +$$ + {n \choose k} = {n (n-1) (n-2) \cdots (n-k+1) \over k!} +$$ +@end tex +@end iftex +@ifinfo + +@example +@group + / \ + | n | n (n-1) (n-2) ... (n-k+1) + | | = ------------------------- + | k | k! + \ / +@end group +@end example +@end ifinfo + +For example, + +@example +@group +bincoeff (5, 2) + @result{} 10 +@end group +@end example @end deftypefn @deftypefn {Mapping Function} {} erf (@var{z}) @@ -427,11 +511,19 @@ @end deftypefn @deftypefn {Mapping Function} {} erfc (@var{z}) -Computes the complementary error function, @code{1 - erf (@var{z})}. +Computes the complementary error function, +@iftex +@tex +$1 - {\rm erf} (z)$. +@end tex +@end iftex +@ifinfo +@code{1 - erf (@var{z})}. +@end ifinfo @end deftypefn @deftypefn {Mapping Function} {} erfinv (@var{z}) -Computes the inverse of the error function. +Computes the inverse of the error function, @end deftypefn @deftypefn {Mapping Function} {} gamma (@var{z}) @@ -460,7 +552,7 @@ @iftex @tex $$ - \gamma (a, x) = {\int_0^x e^{-t} t^{a-1} dt \over \Gamma (a)} + \gamma (a, x) = {\displaystyle\int_0^x e^{-t} t^{a-1} dt \over \Gamma (a)} $$ @end tex @end iftex @@ -489,14 +581,21 @@ @deftypefn {Function File} {} cross (@var{x}, @var{y}) Computes the vector cross product of the two 3-dimensional vectors -@var{x} and @var{y}. +@var{x} and @var{y}. For example, + +@example +@group +cross ([1,1,0], [0,1,1]) + @result{} [ 1; -1; 1 ] +@end group +@end example @end deftypefn @deftypefn {Function File} {} commutation_matrix (@var{m}, @var{n}) Returns the commutation matrix @iftex +@tex $K_{m,n}$ -@tex @end tex @end iftex @ifinfo @@ -514,7 +613,7 @@ matrix such that @iftex @tex - $K_{m,n} * {\rm vec} (A) = {\rm vec} (A^T)$ + $K_{m,n} \cdot {\rm vec} (A) = {\rm vec} (A^T)$ @end tex @end iftex @ifinfo @@ -580,13 +679,13 @@ @end tex @end iftex @ifinfo - @var{D}_@var{n} * vech (@var{A}) = vec (@var{A}) + @var{D}_@var{n} \cdot vech (@var{A}) = vec (@var{A}) @end ifinfo for all symmetric @iftex @tex + $n \times n$ @end tex - $n \times n$ @end iftex @ifinfo @var{n} by @var{n} @@ -636,24 +735,16 @@ @defvr {Built-in Variable} NaN @defvrx {Built-in Variable} nan -Not a number. This is the result of an operation like @samp{0/0}, or -@samp{Inf - Inf}, or any operation with a NaN. -@end defvr - -@defvr {Built-in Variable} eps -The machine precision. More precisely, @code{eps} is the largest -relative spacing between any two adjacent numbers in the machine's -floating point system. This number is obviously system-dependent. On -machines that support 64 bit IEEE floating point arithmetic, @code{eps} -is approximately -@ifinfo - 2.2204e-16. -@end ifinfo +Not a number. This is the result of an operation like @iftex @tex - $2.2204\times10^{-16}$. +$0/0$, or $\infty - \infty$, @end tex @end iftex +@ifinfo +0/0, or @samp{Inf - Inf}, +@end ifinfo +or any operation with a NaN. @end defvr @defvr {Built-in Variable} pi @@ -682,6 +773,22 @@ @end ifinfo @end defvr +@defvr {Built-in Variable} eps +The machine precision. More precisely, @code{eps} is the largest +relative spacing between any two adjacent numbers in the machine's +floating point system. This number is obviously system-dependent. On +machines that support 64 bit IEEE floating point arithmetic, @code{eps} +is approximately +@ifinfo + 2.2204e-16. +@end ifinfo +@iftex +@tex + $2.2204\times10^{-16}$. +@end tex +@end iftex +@end defvr + @defvr {Built-in Variable} realmax The largest floating point number that is representable. The actual value is system-dependent. On machines that support 64 bit IEEE diff --git a/doc/interpreter/audio.texi b/doc/interpreter/audio.texi --- a/doc/interpreter/audio.texi +++ b/doc/interpreter/audio.texi @@ -30,20 +30,17 @@ @deftypefn {Function File} {} lin2mu (@var{x}) If the vector @var{x} represents mono audio data in 8- or 16-bit -linear encoding, @code{lin2mu (@var{x})} is the correspoding mu-law +linear encoding, @code{lin2mu (@var{x})} is the corresponding mu-law encoding. @end deftypefn @deftypefn {Function File} {} mu2lin (@var{x}, @var{bps}) If the vector @var{x} represents mono audio data in mu-law encoding, -@code{mu2lin (@var{x} [, @var{bps}])} converts it to linear encoding. -The optional argument @var{bps} specifies whether the input data uses -8 bit per sample (default) or 16 bit. +@code{mu2lin} converts it to linear encoding. The optional argument +@var{bps} specifies whether the input data uses 8 bit per sample +(default) or 16 bit. @end deftypefn -@c XXX FIXME XXX -- ext and bps are optional, but we need to note the -@c default values here too. - @deftypefn {Function File} {} loadaudio (@var{name}, @var{ext}, @var{bps}) Loads audio data from the file @file{@var{name}.@var{ext}} into the vector @var{x}. @@ -69,20 +66,20 @@ operating system support. It is assumed that audio data in linear encoding can be played and recorded by reading from and writing to @file{/dev/dsp}, and that similarly @file{/dev/audio} is used for mu-law -encoding. This definitely works on Linux systems, and should also work -on Suns. If your hardware is accessed differently, please contact -Andreas Weingessel . +encoding. These file names are system-dependent. Improvements so that +these functions will work without modification on a wide variety of +hardware are welcome. @deftypefn {Function File} {} playaudio (@var{name}, @var{ext}) @deftypefnx {Function File} {} playaudio (@var{x}) -Plays the audio file @file{@var{name}.@var{ext}} or in the vector -@var{x}. +Plays the audio file @file{@var{name}.@var{ext}} or the audio data +stored in the vector @var{x}. @end deftypefn @deftypefn {Function File} {} record (@var{sec}, @var{sampling_rate}) Records @var{sec} seconds of audio input into the vector @var{x}. The default value for @var{sampling_rate} is 8000 samples per second, or -8kHz. The program waits until the user types @kbd{RET} and then +8kHz. The program waits until the user types @key{RET} and then immediately starts to record. @end deftypefn diff --git a/doc/interpreter/basics.texi b/doc/interpreter/basics.texi --- a/doc/interpreter/basics.texi +++ b/doc/interpreter/basics.texi @@ -70,9 +70,8 @@ @cindex @code{--exec-path @var{path}} Specify the path to search for programs to run. The value of @var{path} specified on the command line will override any value of -@samp{OCTAVE_EXEC_PATH} found in the environment, but not any -@samp{EXEC_PATH = "path"} commands found in the system or user startup -files. +@code{OCTAVE_EXEC_PATH} found in the environment, but not any commands +in the system or user startup files that set @code{EXEC_PATH}. @item --help @itemx -h @@ -86,23 +85,24 @@ @cindex @code{--info-file @var{filename}} Specify the name of the info file to use. The value of @var{filename} specified on the command line will override any value of -@samp{OCTAVE_INFO_FILE} found in the environment, but not any -@samp{INFO_FILE = "filename"} commands found in the system or user -startup files. +@code{OCTAVE_INFO_FILE} found in the environment, but not any commands +in the system or user startup files that set @samp{INFO_FILE}. @item --info-program @var{program} @cindex @code{--info-program @var{program}} Specify the name of the info program to use. The value of @var{program} specified on the command line will override any value of -@samp{OCTAVE_INFO_PROGRAM} found in the environment, but not any -@samp{INFO_PROGRAM = "program"} commands found in the system or user -startup files. +@code{OCTAVE_INFO_PROGRAM} found in the environment, but not any +commands in the system or user startup files that set +@code{INFO_PROGRAM}. @item --interactive @itemx -i @cindex @code{--interactive} @cindex @code{-i} -Force interactive behavior. +Force interactive behavior. This can be useful for running Octave via a +remote shell command or inside an Emacs shell buffer. For another way +to run Octave within Emacs, see @ref{Emacs}. @item --no-init-file @cindex @code{--no-init-file} @@ -130,9 +130,8 @@ @cindex @code{-p @var{path}} Specify the path to search for function files. The value of @var{path} specified on the command line will override any value of -@samp{OCTAVE_PATH} found in the environment, but not any -@samp{LOADPATH = "path"} commands found in the system or user startup -files. +@code{OCTAVE_PATH} found in the environment, but not any commands in the +system or user startup files that set @code{LOADPATH}. @item --silent @itemx --quiet @@ -140,7 +139,7 @@ @cindex @code{--silent} @cindex @code{--quiet} @cindex @code{-q} -Don't print message at startup. +Don't print the usual greeting and version message at startup. @item --traditional @itemx --braindead @@ -307,7 +306,20 @@ @end deftypefn @deftypefn {Built-in Function} {} atexit (@var{fcn}) -Register function to be called when Octave exits. +Register function to be called when Octave exits. For example, + +@example +@group +function print_flops_at_exit () + printf ("\n%s\n", system ("fortune")); + fflush (stdout); +endfunction +atexit ("print_flops_at_exit"); +@end group +@end example + +@noindent +will print a message when Octave exits. @end deftypefn @node Getting Help, Command Line Editing, Quitting Octave, Getting Started @@ -336,7 +348,7 @@ describing the @code{help} command, and @kbd{help -i help} starts the GNU Info browser at this node in the on-line version of the manual. -Once the GNU Info browser is runnig, help for using it is available +Once the GNU Info browser is running, help for using it is available using the command @kbd{C-h}. @end deffn @@ -373,7 +385,7 @@ Octave uses the GNU readline library to provide an extensive set of command-line editing and history features. Only the most common features are described in this manual. Please see The GNU Readline -Library for more information. +Library manual for more information. To insert printing characters (letters, digits, symbols, etc.), simply type the character. Octave will insert the character at the cursor and @@ -556,13 +568,13 @@ @subsection Letting Readline Type For You @cindex command completion -The following commands allow Octave to complete commands and file names -for you. +The following commands allow Octave to complete command and variable +names for you. @table @kbd @item TAB Attempt to do completion on the text before the cursor. Octave can -complete commands and variables. +complete the names of commands and variables. @item M-? List the possible completions of the text before the cursor. @@ -658,7 +670,7 @@ For example, to display the five most recent commands that you have typed without displaying line numbers, use the command -@samp{history -q 5}. +@kbd{history -q 5}. @end deffn @deffn {Command} edit_history options @@ -903,8 +915,7 @@ @cindex messages, error There are two classes of errors that Octave produces when it encounters -input that it is unable to understand -an action. +input that it is unable to understand. A @dfn{parse error} occurs if Octave cannot understand something you have typed. For example, if you misspell a keyword, @@ -968,9 +979,9 @@ 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 @samp{f}. -If the function @samp{f} had been called from another function, for -example, @samp{g}, the list of errors would have ended with one more +message indicates that the error occurred within the function @code{f}. +If the function @code{f} had been called from another function, for +example, @code{g}, the list of errors would have ended with one more line: @example diff --git a/doc/interpreter/bugs.texi b/doc/interpreter/bugs.texi --- a/doc/interpreter/bugs.texi +++ b/doc/interpreter/bugs.texi @@ -235,15 +235,11 @@ for you. If for some reason you cannot use Octave's @code{bug_report} function, -send bug reports for Octave to: - -@example -bug-octave@@bevo.che.wisc.edu -@end example +send bug reports for Octave to @email{bug-octave@@bevo.che.wisc.edu}. @strong{Do not send bug reports to @samp{help-octave}}. Most users of Octave do not want to receive bug reports. Those that do have asked to -be on @samp{bug-octave}. +be on the mailing list. As a last resort, send bug reports on paper to: @@ -360,7 +356,7 @@ If you wish to suggest changes to the Octave source, send them as context diffs. If you even discuss something in the Octave source, refer to it by context, not by line number, because the line numbers in -the development sources probalby won't match those in your sources. +the development sources probably won't match those in your sources. @end itemize Here are some things that are not necessary: @@ -462,20 +458,15 @@ @appendixsec How To Get Help with Octave @cindex help, where to find -If you need help installing, using or changing Octave, the mailing list - -@example -help-octave@@bevo.che.wisc.edu -@end example - -exists for the discussion of Octave matters related to using, -installing, and porting Octave. If you would like to join the -discussion, please send a short note to - -@example -help-octave-request@@bevo.che.wisc.edu - ^^^^^^^ -@end example +The mailing list @email{help-octave@@bevo.che.wisc.edu} exists for the +discussion of matters related to using and installing Octave. If would +like to join the discussion, please send a short note to +@email{help-octave@strong{-request}@@bevo.che.wisc.edu}. @strong{Please do not} send requests to be added or removed from the the mailing list, or other administrative trivia to the list itself. + +If you think you have found a bug in the installation procedure, +however, you should send a complete bug report for the problem to +@email{bug-octave@@bevo.che.wisc.edu}. @xref{Bug Reporting} for +information that will help you to submit a useful report. diff --git a/doc/interpreter/control.texi b/doc/interpreter/control.texi --- a/doc/interpreter/control.texi +++ b/doc/interpreter/control.texi @@ -5,20 +5,28 @@ @node Control Theory, Signal Processing, Polynomial Manipulations, Top @chapter Control Theory -@deftypefn {Function File} {} abcddim (@var{a}, @var{b}, @var{c}, @var{d}) +Most of the functions described in this chapter were contributed by +A. Scottedward Hodel @email{A.S.Hodel@@eng.auburn.edu} and R. Bruce Tenison +@email{Bruce.Tenison@@eng.auburn.edu}. They have also written a larger +collection of functions for solving linear control problems. It is +currently being updated for Octave version 2, with snapshots of the +sources available from @url{ftp://ftp.eng.auburn.edu/pub/hodel}. + +@deftypefn {Function File} {[@var{n}, @var{m}, @var{p}] =} abcddim (@var{a}, @var{b}, @var{c}, @var{d}) Check for compatibility of the dimensions of the matrices defining -the linear system [A, B, C, D] corresponding to +the linear system @iftex @tex -$$ - {dx\over dt} = A x + B u +$[A, B, C, D]$ corresponding to $$ -$$ - y = C x + D u +\eqalign{ + {dx\over dt} &= A x + B u\cr + y &= C x + D u} $$ @end tex @end iftex @ifinfo +[A, B, C, D] corresponding to @example dx/dt = a x + b u @@ -29,33 +37,54 @@ or a similar discrete-time system. If the matrices are compatibly dimensioned, then @code{abcddim} returns -@var{n} = number of system states, @var{m} = number of system inputs, -and @var{p} = number of system outputs. Otherwise @code{abcddim} -returns @var{n} = @var{m} = @var{p} = @minus{}1. + +@table @var +@item n +The number of system states. + +@item m +The number of system inputs. + +@item p +The number of system outputs. +@end table + +Otherwise @code{abcddim} returns @var{n} = @var{m} = @var{p} = @minus{}1. @end deftypefn @deftypefn {Function File} {} are (@var{a}, @var{b}, @var{c}, @var{opt}) -Returns the solution, @var{x}, of the algebraic Riccati equation +Return the solution, @var{x}, of the algebraic Riccati equation +@iftex +@tex +$$ +A^TX + XA - XBX + C = 0 +$$ +@end tex +@end iftex +@ifinfo @example -a' x + x a - x b x + c = 0 +a' * x + x * a - x * b * x + c = 0 @end example +@end ifinfo @noindent -for identically dimensioned square matrices @var{a}, @var{b}, @var{c}. -If @var{b} (@var{c}) is not square, then the function attempts to use -@code{@var{b}*@var{b}'} (@code{@var{c}'*@var{c}}) instead. +for identically dimensioned square matrices @var{a}, @var{b}, and +@var{c}. If @var{b} is not square, @code{are} attempts to use +@code{@var{b}*@var{b}'} instead. If @var{c} is not square, @code{are} +attempts to use @code{@var{c}'*@var{c}}) instead. -Solution method: apply Laub's Schur method (IEEE Transactions on -Automatic Control, 1979) to the appropriate Hamiltonian matrix. +To form the solution, Laub's Schur method (IEEE Transactions on +Automatic Control, 1979) is applied to the appropriate Hamiltonian +matrix. -@var{opt} is an option passed to the eigenvalue balancing routine. -Default is @code{"B"}. +The optional argument @var{opt} is passed to the eigenvalue balancing +routine. If it is omitted, a value of @code{"B"} is assumed. @end deftypefn @deftypefn {Function File} {} c2d (@var{a}, @var{b}, @var{t}) -Converts the continuous time system described by: +Convert the continuous time system described by: @iftex @tex $$ @@ -92,39 +121,56 @@ @deftypefn {Function File} {} dare (@var{a}, @var{b}, @var{c}, @var{r}, @var{opt}) -Returns the solution, @var{x} of the discrete-time algebraic Riccati +Return the solution, @var{x} of the discrete-time algebraic Riccati equation +@iftex +@tex +$$ +A^TXA - X + A^TXB (R + B^TXB)^{-1} B^TXA + C = 0 +$$ +@end tex +@end iftex +@ifinfo @example a' x a - x + a' x b (r + b' x b)^(-1) b' x a + c = 0 @end example +@end ifinfo @noindent for matrices with dimensions: -@example -@var{a}: @var{n} by @var{n} -@var{b}: @var{n} by @var{m} -@var{c}: @var{n} by @var{n}, symmetric positive semidefinite -@var{r}: @var{m} by @var{m}, symmetric positive definite (invertible) -@end example +@table @var +@item a +@var{n} by @var{n}. + +@item b +@var{n} by @var{m}. + +@item c +@var{n} by @var{n}, symmetric positive semidefinite. + +@item r +@var{m} by @var{m}, symmetric positive definite (invertible). +@end table If @var{c} is not square, then the function attempts to use @code{@var{c}'*@var{c}} instead. -Solution method: Laub's Schur method (IEEE Transactions on Automatic -Control, 1979) is applied to the appropriate symplectic matrix. +To form the solution, Laub's Schur method (IEEE Transactions on +Automatic Control, 1979) is applied to the appropriate symplectic +matrix. -See also: Ran and Rodman, @cite{Stable Hermitian Solutions of Discrete +See also Ran and Rodman, @cite{Stable Hermitian Solutions of Discrete Algebraic Riccati Equations}, Mathematics of Control, Signals and Systems, Volume 5, Number 2 (1992). -@var{opt} is an option passed to the eigenvalue balancing routine. -The default is @code{"B"}. +The optional argument @var{opt} is passed to the eigenvalue balancing +routine. If it is omitted, a value of @code{"B"} is assumed. @end deftypefn @deftypefn {Function File} {} dgram (@var{a}, @var{b}) -Returns the discrete controllability and observability gramian for the +Return the discrete controllability or observability gramian for the discrete time system described by @iftex @tex @@ -144,14 +190,14 @@ @end example @end ifinfo -@code{dgram (@var{a}, @var{b})} returns the discrete controllability -gramian and @code{dgram (@var{a}', @var{c}')} returns the observability -gramian. +For example, @code{dgram (@var{a}, @var{b})} returns the discrete +controllability gramian and @code{dgram (@var{a}', @var{c}')} returns +the observability gramian. @end deftypefn -@deftypefn {Function File} {} dlqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv} [, @var{z}]) -Linear quadratic estimator (Kalman filter) design for the discrete time -system +@deftypefn {Function File} {[@var{l}, @var{m}, @var{p}, @var{e}] =} dlqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z}) +Construct the linear quadratic estimator (Kalman filter) for the +discrete time system @iftex @tex $$ @@ -193,19 +239,42 @@ @end ifinfo @noindent -Returns: +The following values are returned: -@var{l} is the observer gain, @code{(A - A L C)} is stable. +@table @var +@item l +The observer gain, +@iftex +@tex +$(A - ALC)$. +@end tex +@end iftex +@ifinfo +(@var{a} - @var{a}@var{l}@var{c}). +@end ifinfo +is stable. -@var{m} is the Ricatti equation solution. +@item m +The Riccati equation solution. + +@item p +The estimate error covariance after the measurement update. -@var{p} is the estimate error covariance after the measurement update. - -@var{e} are the closed loop poles of @code{(A - A L C)}. +@item e +The closed loop poles of +@iftex +@tex +$(A - ALC)$. +@end tex +@end iftex +@ifinfo +(@var{a} - @var{a}@var{l}@var{c}). +@end ifinfo +@end table @end deftypefn -@deftypefn {Function File} {} dlqr (@var{a}, @var{b}, @var{q}, @var{r} [, @var{z}]) -Linear quadratic regulator design for the discrete time system +@deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} dlqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) +Construct the linear quadratic regulator for the discrete time system @iftex @tex $$ @@ -221,51 +290,88 @@ @end ifinfo to minimize the cost functional +@iftex +@tex +$$ + J = \sum x^T Q x + u^T R u +$$ +@end tex +@end iftex +@ifinfo @example -J = Sum [ x' Q x + u' R u ], Z omitted +J = Sum (x' Q x + u' R u) @end example +@end ifinfo @noindent -or +@var{z} omitted or +@iftex +@tex +$$ + J = \sum x^T Q x + u^T R u + 2 x^T Z u +$$ +@end tex +@end iftex +@ifinfo @example -J = Sum [ x' Q x + u' R u +2 x' Z u ], Z included +J = Sum (x' Q x + u' R u + 2 x' Z u) @end example -@noindent -Returns: +@end ifinfo +@var{z} included. + +The following values are returned: -@var{k} is the state feedback gain, @code{(A - B K)} is stable. +@table @var +@item k +The state feedback gain, +@iftex +@tex +$(A - B K)$ +@end tex +@end iftex +@ifinfo +(@var{a} - @var{b}@var{k}) +@end ifinfo +is stable. -@var{p} is the solution of algebraic Riccati equation. +@item p +The solution of algebraic Riccati equation. -@var{e} are the closed loop poles of @var{(A - B K)}. +@item e +The closed loop poles of +@iftex +@tex +$(A - B K)$. +@end tex +@end iftex +@ifinfo +(@var{a} - @var{b}@var{k}). +@end ifinfo +@end table @end deftypefn @deftypefn {Function File} {} dlyap (@var{a}, @var{b}) Solve the discrete-time Lyapunov equation - -@example -a x a' - x + b = 0 -@end example - -@noindent +@iftex +@tex +$AXA^T - X + B = 0$ +@end tex +@end iftex +@ifinfo +@code{a x a' - x + b = 0} +@end ifinfo for square matrices @var{a}, @var{b}. If @var{b} is not square, then the function attempts to solve either - -@example -a x a' - x + b b' = 0 -@end example - -@noindent -or - -@example -a' x a - x + b' b = 0 -@end example - -@noindent +@iftex +$AXA^T - X + B B^T = 0$ or $A^TXA - X + B^TB = 0$, +@tex +@end tex +@ifinfo +@code{a x a' - x + b b' = 0} or @code{a' x a - x + b' b = 0}, +@end ifinfo whichever is appropriate. Uses Schur decomposition method as in Kitagawa, International Journal of @@ -274,47 +380,28 @@ @end deftypefn @deftypefn {Function File} {} is_controllable (@var{a}, @var{b}, @var{tol}) - -If the pair (a, b) is controllable, then return value 1. -Otherwise, returns a value of 0. - -@var{tol} is a roundoff parameter, set to @code{2*eps} if omitted. +Return 1 if the pair (@var{a}, @var{b}) is controllable. Otherwise, +return 0. -Currently just constructs the controllability matrix and checks rank. -A better method is as follows (Boley and Golub, Systems and Control -Letters, 1984): Controllability is determined by applying Arnoldi -iteration with complete re-orthogonalization to obtain an orthogonal -basis of the Krylov subspace -@iftex -@tex -$$ - {\rm span} \left(\left[b~ab~\ldots~a^{n-1}b\right]\right) -$$ -@end tex -@end iftex -@ifinfo +The optional argument @var{tol} is a roundoff parameter. If it is +omitted, a value of @code{2*eps} is used. -@example - n-1 - span ([b, a*b, ..., a^ *b]). -@end example -@end ifinfo +Currently, @code{is_controllable} just constructs the controllability +matrix and checks rank. @end deftypefn @deftypefn {Function File} {} is_observable (@var{a}, @var{c}, @var{tol}) -Returns 1 if the pair @code{(a, c)} is observable. -Otherwise, returns a value of 0. +Return 1 if the pair (@var{a}, @var{c}) is observable. +Otherwise, return0. + +The optional argument @var{tol} is a roundoff parameter. If it is +omitted, a value of @code{2*eps} is used. @end deftypefn -@deftypefn {Function File} {} lqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z}) - -@example -[k, p, e] = lqe (a, g, c, sigw, sigv, z) -@end example - -Linear quadratic estimator (Kalman filter) design for the continuous -time system +@deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} lqe (@var{a}, @var{g}, @var{c}, @var{sigw}, @var{sigv}, @var{z}) +Construct the linear quadratic estimator (Kalman filter) for the +continuous time system @iftex @tex $$ @@ -336,7 +423,7 @@ @end example @end ifinfo -where @var{w}, @var{v} are zero-mean gaussian noise processes with +where @var{w} and @var{v} are zero-mean gaussian noise processes with respective intensities @example @@ -344,25 +431,45 @@ sigv = cov (v, v) @end example -@noindent -@var{z} (if specified) is the cross-covariance -@code{cov (@var{w}, @var{v})}; the default value is -@code{cov (@var{w}, @var{v}) = 0}. +The optional argument @var{z} is the cross-covariance +@code{cov (@var{w}, @var{v})}. If it is omitted, +@code{cov (@var{w}, @var{v}) = 0} is assumed. Observer structure is @code{dz/dt = A z + B u + k (y - C z - D u)} -returns: +The following values are returned: -@var{k} is observer gain: @code{(A - K C)} is stable. +@table @var +@item k +The observer gain, +@iftex +@tex +$(A - K C)$ +@end tex +@end iftex +@ifinfo +(@var{a} - @var{k}@var{c}) +@end ifinfo +is stable. -@var{p} is solution of algebraic Riccati equation. +@item p +The solution of algebraic Riccati equation. -@var{e} is the vector of closed loop poles of @code{(A - K C)}. +@item e +The vector of closed loop poles of +@iftex +@tex +$(A - K C)$. +@end tex +@end iftex +@ifinfo +(@var{a} - @var{k}@var{c}). +@end ifinfo +@end table @end deftypefn -@deftypefn {Function File} {} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) -@deftypefnx {Function File} {[@var{k}, @var{p}, @var{e}] =} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) -Linear quadratic regulator design for the continuous time system +@deftypefn {Function File} {[@var{k}, @var{p}, @var{e}] =} lqr (@var{a}, @var{b}, @var{q}, @var{r}, @var{z}) +construct the linear quadratic regulator for the continuous time system @iftex @tex $$ @@ -383,7 +490,7 @@ @iftex @tex $$ - J = \int_0^\infty x' Q x + u' R u + J = \int_0^\infty x^T Q x + u^T R u $$ @end tex @end iftex @@ -403,7 +510,7 @@ @iftex @tex $$ - J = \int_0^\infty x' Q x + u' R u + 2 x' Z u + J = \int_0^\infty x^T Q x + u^T R u + 2 x^T Z u $$ @end tex @end iftex @@ -418,62 +525,121 @@ @end example @end ifinfo -@var{z} included +@var{z} included. -@noindent -Returns: +The following values are returned: -@var{k} is state feedback gain: @code{(A - B K)} is stable. +@table @var +@item k +The state feedback gain, +@iftex +$(A - B K)$ +@tex +@end tex +@end iftex +@ifinfo +(@var{a} - @var{b}@var{k}) +@end ifinfo +is stable. -@var{p} is the stabilizing solution of appropriate algebraic Riccati -equation. +@item p +The stabilizing solution of appropriate algebraic Riccati equation. -@var{e} is the vector of the closed loop poles of @code{(A - B K)}. +@item e +The vector of the closed loop poles of +@iftex +@tex +$(A - B K)$. +@end tex +@end iftex +@ifinfo +(@var{a} - @var{b}@var{k}). +@end ifinfo +@end table @end deftypefn @deftypefn {Function File} {} lyap (@var{a}, @var{b}, @var{c}) Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart algorithm (Communications of the ACM, 1972). -If @code{(a, b, c)} are specified, then @code{lyap} returns the solution -of the Sylvester equation +If @var{a}, @var{b}, and @var{c} are specified, then @code{lyap} returns +the solution of the Sylvester equation +@iftex +@tex +$$ + A X + X B + C = 0 +$$ +@end tex +@end iftex +@ifinfo @example a x + x b + c = 0 @end example +@end ifinfo If only @code{(a, b)} are specified, then @code{lyap} returns the solution of the Lyapunov equation +@iftex +@tex +$$ + A^T X + X A + B = 0 +$$ +@end tex +@end iftex +@ifinfo @example a' x + x a + b = 0 @end example +@end ifinfo If @var{b} is not square, then @code{lyap} returns the solution of either +@iftex +@tex +$$ + A^T X + X A + B^T B = 0 +$$ +@end tex +@end iftex +@ifinfo @example a' x + x a + b' b = 0 @end example +@end ifinfo @noindent or +@iftex +@tex +$$ + A X + X A^T + B B^T = 0 +$$ +@end tex +@end iftex +@ifinfo @example a x + x a' + b b' = 0 @end example +@end ifinfo @noindent whichever is appropriate. - -Solves by using the Bartels-Stewart algorithm (1972). @end deftypefn -@deftypefn {Function File} {} tzero (@var{a}, @var{b}, @var{c}, @var{d}, @var{bal}) -Compute the transmission zeros of [A, B, C, D]. - -@var{bal} = balancing option (see balance); default is @code{"B"}. +@deftypefn {Function File} {} tzero (@var{a}, @var{b}, @var{c}, @var{d}, @var{opt}) +Compute the transmission zeros of +@iftex +@tex +$[A, B, C, D]$. +@end tex +@end iftex +@ifinfo +[A, B, C, D]. +@end ifinfo -Needs to incorporate @code{mvzero} algorithm to isolate finite zeros; -see Hodel, @cite{Computation of System Zeros with Balancing}, Linear -Algebra and its Applications, July 1993. +The optional argument @var{opt} is passed to the eigenvalue balancing +routine. If it is omitted, a value of @code{"B"} is assumed. @end deftypefn diff --git a/doc/interpreter/data.texi b/doc/interpreter/data.texi --- a/doc/interpreter/data.texi +++ b/doc/interpreter/data.texi @@ -15,7 +15,8 @@ dynamically while Octave is running, so it is not necessary to recompile all of Octave just to add a new type. @xref{Dynamically Linked Functions} for more information about Octave's dynamic linking -capabilities. +capabilities. @ref{User-defined Data Types} describes what you must do +to define a new data type for Octave. @menu * Built-in Data Types:: @@ -29,11 +30,11 @@ @cindex built-in data types The standard built-in data types are real and complex scalars and -matrices, character strings, and a data structure type. Additional -built-in data types may be added in future versions. If you need a -specialize data type that is not currently provided as a built-in type, -you are encouraged to write your own user-defined data type and -contribute it for distribution in a future release of Octave. +matrices, ranges, character strings, and a data structure type. +Additional built-in data types may be added in future versions. If you +need a specialized data type that is not currently provided as a +built-in type, you are encouraged to write your own user-defined data +type and contribute it for distribution in a future release of Octave. @menu * Numeric Objects:: @@ -49,7 +50,7 @@ Octave's built-in numeric objects include real and complex scalars and matrices. All built-in numeric data is currently stored as double precision numbers. On systems that use the IEEE floating point format, -values in the range +values in the range of approximately @iftex @tex $2.2251\times10^{-308}$ to $1.7977\times10^{308}$ @@ -67,12 +68,12 @@ @ifinfo 2.2204e-16. @end ifinfo -The exact values are given by the variables @var{realmin}, -@var{realmax}, and @var{eps}, respectively. +The exact values are given by the variables @code{realmin}, +@code{realmax}, and @code{eps}, respectively. Matrix objects can be of any size, and can be dynamically reshaped and resized. It is easy to extract individual rows, columns, or submatrices -is using a variety of powerful indexing features. +is using a variety of powerful indexing features. @xref{Index Expressions}. @xref{Numeric Data Types}, for more information. @@ -107,14 +108,20 @@ @cindex user-defined data types @cindex data types, user-defined +Someday I hope to expand this to include a complete description of +Octave's mechanism for managing user-defined data types. Until this +feature is documented here, you will have to make do by reading the code +in the @file{ov.h}, @file{ops.h}, and related files from Octave's +@file{src} directory. + @node Object Sizes, , User-defined Data Types, Data Types @section Object Sizes The following functions allow you to determine the size of a variable or expression. These functions are defined for all objects. They return --1 when the operation doesn't make sense. For example, Octave's data -structure type doesn't have rows or columns, so @code{rows} and -@code{columns} return -1 for structure arguments. +@minus{}1 when the operation doesn't make sense. For example, Octave's +data structure type doesn't have rows or columns, so the @code{rows} and +@code{columns} functions return @minus{}1 for structure arguments. @deftypefn {Function File} {} columns (@var{a}) Return the number of columns of @var{a}. @@ -139,15 +146,14 @@ @example @group -octave:13> size ([1, 2; 3, 4; 5, 6]) -ans = - - 3 2 +size ([1, 2; 3, 4; 5, 6]) + @result{} [ 3, 2 ] -octave:14> [nr, nc] = size ([1, 2; 3, 4; 5, 6]) -nr = 3 +[nr, nc] = size ([1, 2; 3, 4; 5, 6]) -nc = 2 + @result{} nr = 3 + + @result{} nc = 2 @end group @end example @@ -155,8 +161,8 @@ only the row or column dimension. For example @example -octave:15> size ([1, 2; 3, 4; 5, 6], 2) -ans = 2 +size ([1, 2; 3, 4; 5, 6], 2) + @result{} 2 @end example @noindent diff --git a/doc/interpreter/diffeq.texi b/doc/interpreter/diffeq.texi --- a/doc/interpreter/diffeq.texi +++ b/doc/interpreter/diffeq.texi @@ -38,9 +38,9 @@ @end ifinfo @noindent -using Hindmarsh's ODE solver LSODE. +using Hindmarsh's ODE solver @sc{Lsode}. -@deftypefn {Lodable Function} {} lsode (@var{fcn}, @var{x0}, @var{t}, @var{t_crit}) +@deftypefn {Loadable Function} {} lsode (@var{fcn}, @var{x0}, @var{t}, @var{t_crit}) Return a matrix of @var{x} as a function of @var{t}, given the initial state of the system @var{x0}. Each row in the result matrix corresponds to one of the elements in the vector @var{t}. The first element of @@ -107,7 +107,7 @@ @end group @end example -@deftypefn {Lodable Function} {} lsode_options (@var{opt}, @var{val}) +@deftypefn {Loadable Function} {} lsode_options (@var{opt}, @var{val}) When called with two arguments, this function allows you set options parameters for the function @code{lsode}. Given one argument, @code{lsode_options} returns the value of the corresponding option. If @@ -137,8 +137,11 @@ @end example @end ifinfo +@noindent +using Petzold's DAE solver @sc{Dassl}. + @deftypefn {Loadable Function} {[@var{x}, @var{xdot}] =} dassl (@var{fcn}, @var{x0}, @var{xdot0}, @var{t}, @var{t_crit}) -Return a matrix of states and their first derivaties with respect to +Return a matrix of states and their first derivatives with respect to @var{t}. Each row in the result matrices correspond to one of the elements in the vector @var{t}. The first element of @var{t} corresponds to the initial state @var{x0} and derivative @var{xdot0}, so @@ -163,7 +166,7 @@ including the time corresponding to the initial condition. The set of initial states and derivatives are not strictly required to -be consistent. In practice, however, DASSL is not very good at +be consistent. In practice, however, @sc{Dassl} is not very good at determining a consistent set for you, so it is best if you ensure that the initial values result in the function evaluating to zero. @@ -183,4 +186,4 @@ See K. E. Brenan, et al., @cite{Numerical Solution of Initial-Value Problems in Differential-Algebraic Equations}, North-Holland (1989) for -more information about the implementation of DASSL. +more information about the implementation of @sc{Dassl}. diff --git a/doc/interpreter/emacs.texi b/doc/interpreter/emacs.texi --- a/doc/interpreter/emacs.texi +++ b/doc/interpreter/emacs.texi @@ -24,8 +24,8 @@ All functionality is provided by the Emacs Lisp package @file{octave}. This chapter describes how to set up and use this package. -Please contact if you have any questions -or suggestions on using Emacs with Octave. +Please contact @email{Kurt.Hornik@@ci.tuwien.ac.at} if you have any +questions or suggestions on using Emacs with Octave. @menu * Installing the Emacs Octave Package:: diff --git a/doc/interpreter/errors.texi b/doc/interpreter/errors.texi --- a/doc/interpreter/errors.texi +++ b/doc/interpreter/errors.texi @@ -5,6 +5,11 @@ @node Error Handling, Input and Output, Functions and Scripts, Top @chapter Error Handling +Octave includes several functions for printing error and warning +messages. When you write functions that need to take special action +when they encounter abnormal conditions, you should print the error +messages using the functions described in this chapter. + @deftypefn {Built-in Function} {} error (@var{template}, @dots{}) The @code{error} function formats the optional arguments under the control of the template string @var{template} using the same rules as @@ -65,7 +70,7 @@ @code{try} statement or the @var{try} part of the most recent call to the @code{eval} function. Outside of the @code{unwind_protect} and @code{try} statements or the @code{eval} function, or if no error has -ocurred within them, the value of @code{error_text} is guaranteed to be +occurred within them, the value of @code{error_text} is guaranteed to be the empty string. Note that the message does not include the first @samp{error: } prefix, @@ -83,7 +88,11 @@ @end defvr @deftypefn {Built-in Function} {} warning (@var{msg}) -Print the message @var{msg} prefixed by the string @samp{warning: }. +Print a warning message @var{msg} prefixed by the string @samp{warning: }. +After printing the warning message, Octave will continue to execute +commands. You should use this function should when you want to notify +the user of an unusual condition, but only when it makes sense for your +program to go on. @end deftypefn @deftypefn {Built-in Function} {} usage (@var{msg}) @@ -94,6 +103,23 @@ After @code{usage} is evaluated, Octave will print a traceback of all the function calls leading to the usage message. + +You should use this function for reporting problems errors that result +from an improper call to a function, such as calling a function with an +incorrect number of arguments, or with arguments of the wrong type. For +example, most functions distributed with Octave begin with code like +this + +@example +@group +if (nargin != 2) + usage ("foo (a, b)"); +endif +@end group +@end example + +@noindent +to check for the proper number of arguments. @end deftypefn The following pair of functions are of limited usefulness, and may be diff --git a/doc/interpreter/eval.texi b/doc/interpreter/eval.texi --- a/doc/interpreter/eval.texi +++ b/doc/interpreter/eval.texi @@ -23,28 +23,27 @@ @code{eval} returns. For example, @example -octave:13> a -error: `a' undefined -octave:14> eval ("a = 13") -a = 13 -ans = 13 -octave:15> a -a = 13 +@group +eval ("a = 13") + + @print{} a = 13 + + @result{} 13 +@end group @end example -In this case, two values are printed: one for the expression that was -evaluated, and one for the value returned from @code{eval}. Just as -with any other expression, you can turn printing off by ending the -expression in a semicolon. For example, +In this case, the value of the evaluated expression is printed and it is +also returned returned from @code{eval}. Just as with any other +expression, you can turn printing off by ending the expression in a +semicolon. For example, @example -octave:13> a -error: `a' undefined -octave:14> eval ("a = 13;") -ans = 13 -octave:15> a -a = 13 +eval ("a = 13;") + @result{} 13 @end example + +In this example, the variable @code{a} has been given the value 13, but +the value of the expression is not printed. @end deftypefn @deftypefn {Built-in Function} {} feval (@var{name}, @dots{}) @@ -52,8 +51,8 @@ are passed on to the named function. For example, @example -octave:12> feval ("acos", -1) -ans = 3.1416 +feval ("acos", -1) + @result{} 3.1416 @end example @noindent diff --git a/doc/interpreter/expr.texi b/doc/interpreter/expr.texi --- a/doc/interpreter/expr.texi +++ b/doc/interpreter/expr.texi @@ -85,7 +85,7 @@ @end example @noindent -selects the first row of the matrix @samp{a}. +selects the first row of the matrix @code{a}. This operation can be useful for selecting elements of a matrix based on some condition, since the comparison operators return matrices of ones @@ -127,9 +127,9 @@ @end example @noindent -results in the matrix @samp{[ 1 2 3 4 ]}. If the value of +results in the matrix @code{[ 1, 2, 3, 4 ]}. If the value of @code{prefer_zero_one_indexing} set to 0, the result would be -the matrix @samp{[ 1 1 1 1 ]}. +the matrix @code{[ 1, 1, 1, 1 ]}. In the first case, Octave is selecting each element corresponding to a @samp{1} in the index vector. In the second, Octave is selecting the @@ -166,7 +166,7 @@ create a 2 by 3 matrix with all elements equal to 13. This is an obscure notation and should be avoided. It is better to -use the function @samp{ones} to generate a matrix of the appropriate +use the function @code{ones} to generate a matrix of the appropriate size whose elements are all one, and then to scale it to produce the desired result. @xref{Special Utility Matrices}. @@ -180,7 +180,7 @@ @end example @noindent -(for @samp{a} previously undefined) produce column vectors. Otherwise, row +(for @code{a} previously undefined) produce column vectors. Otherwise, row vectors are preferred. The default value is 0. If a variable is already defined to be a vector (a matrix with a single @@ -199,7 +199,7 @@ @end example @noindent -(for @samp{a} previously undefined) result in the variable @samp{a} +(for @code{a} previously undefined) result in the variable @code{a} being resized to be just large enough to hold the new value. New elements that have not been given a value are set to zero. If the value of @code{resize_on_range_error} is 0, an error message is printed and @@ -219,7 +219,7 @@ required, or a number of values must be combined to form a larger matrix, it is generally much faster to set the size of the matrix first, and then insert elements using indexing commands. For example, given a -matrix @samp{a}, +matrix @code{a}, @example @group @@ -303,8 +303,8 @@ @end example @noindent -computes the singular value decomposition of the matrix @samp{a} and -assigns the three result matrices to @samp{u}, @samp{s}, and @samp{v}. +computes the singular value decomposition of the matrix @code{a} and +assigns the three result matrices to @code{u}, @code{s}, and @code{v}. The left side of a multiple assignment expression is itself a list of expressions, and is allowed to be a list of variable names or index @@ -385,7 +385,7 @@ With some restrictions@footnote{Some of Octave's function are implemented in terms of functions that cannot be called recursively. -For example, the ODE solver @code{lsode} is ultimiately implemented in a +For example, the ODE solver @code{lsode} is ultimately implemented in a Fortran subroutine that cannot be called recursively, so @code{lsode} should not be called either directly or indirectly from within the user-supplied function that @code{lsode} requires. Doing so will result @@ -612,7 +612,8 @@ @group [1, 2; 3, 4] == [1, 3; 2, 4] - @result{} [ 1, 0; 0, 1 ] + @result{} 1 0 + 0 1 @end group @end example @@ -800,13 +801,13 @@ @group function f (a, b, c) if (nargin > 2 && isstr (c)) - ... + @dots{} @end group @end example @noindent instead of having to use two @code{if} statements to avoid attempting to -evaluate an argument that doesn't exist. For example, without hte +evaluate an argument that doesn't exist. For example, without the short-circuit feature, it would be necessary to write @example @@ -814,10 +815,25 @@ function f (a, b, c) if (nargin > 2) if (isstr (c)) - ... + @dots{} @end group @end example +Writing + +@example +@group +function f (a, b, c) + if (nargin > 2 & isstr (c)) + @dots{} +@end group +@end example + +@noindent +would result in an error if @code{f} were called with one or two +arguments because Octave would be forced to try to evaluate both of the +operands for the operator @samp{&}. + @node Assignment Ops, Increment Ops, Boolean Expressions, Expressions @section Assignment Expressions @cindex assignment expressions @@ -890,6 +906,19 @@ When the second assignment gives @code{foo} a string value, the fact that it previously had a numeric value is forgotten. +Assignment of a scalar to an indexed matrix sets all of the elements +that are referenced by the indices to the scalar value. For example, if +@code{a} is a matrix with at least two columns, + +@example +@group +a(:, 2) = 5 +@end group +@end example + +@noindent +sets all the elements in the second column of @code{a} to 5. + Assigning an empty matrix @samp{[]} works in most cases to allow you to delete rows or columns of matrices and vectors. @xref{Empty Matrices}. For example, given a 4 by 5 matrix @var{A}, the assignment diff --git a/doc/interpreter/func.texi b/doc/interpreter/func.texi --- a/doc/interpreter/func.texi +++ b/doc/interpreter/func.texi @@ -196,7 +196,7 @@ function retval = avg (v) retval = 0; if (nargin != 1) - error ("usage: avg (vector)"); + usage ("avg (vector)"); endif if (is_vector (v)) retval = sum (v) / length (v); @@ -362,7 +362,7 @@ @end defvr @defvr {Built-in Variable} default_return_value -The value given to otherwise unitialized return values if +The value given to otherwise uninitialized return values if @code{define_all_return_values} is nonzero. The default value is @code{[]}. @end defvr @@ -422,7 +422,7 @@ @end deftypefn @deftypefn {Built-in Function} {} va_arg () -Return the value of the next available argument and moves the internal +Return the value of the next available argument and move the internal pointer to the next argument. It is an error to call @code{va_arg()} when there are no more arguments available. @end deftypefn @@ -608,12 +608,14 @@ time stamp every time a function is used is rather inefficient, but it has to be done to ensure that the correct function definition is used. -Octave assumes that function files in the -@file{@value{OCTAVEHOME}/share/octave/@value{VERSION}/m} directory tree -will not change, so it doesn't have to check their time stamps every -time the functions defined in those files are used. This is normally a -very good assumption and provides a significant improvement in -performance for the function files that are distributed with Octave. +To avoid degrading performance unnecessarily by checking the time stamps +on functions that are not likely to change, Octave assumes that function +files in the directory tree +@file{@value{OCTAVEHOME}/share/octave/@value{VERSION}/m} will not +change, so it doesn't have to check their time stamps every time the +functions defined in those files are used. This is normally a very good +assumption and provides a significant improvement in performance for the +function files that are distributed with Octave. If you know that your own function files will not change while you are running Octave, you can improve performance by setting the variable @@ -655,7 +657,7 @@ @code{stat} each time it looks up functions defined in function files. If @code{ignore_function_time_stamp} to @code{"system"}, Octave will not automatically recompile function files in subdirectories of -@code{@value{OCTAVEHOME}/lib/@value{VERSION}} if they have changed since +@file{@value{OCTAVEHOME}/lib/@value{VERSION}} if they have changed since they were last compiled, but will recompile other function files in the @code{LOADPATH} if they change. If set to @code{"all"}, Octave will not recompile any function files unless their definitions are removed with @@ -669,7 +671,7 @@ If the value of @code{warn_function_name_clash} is nonzero, a warning is issued when Octave finds that the name of a function defined in a function file differs from the name of the file. (If the names -disagree, the name delcared inside the file is ignored.) If the value +disagree, the name declared inside the file is ignored.) If the value is 0, the warning is omitted. The default value is 1. @end defvr @@ -723,7 +725,7 @@ message warning about any non-whitespace characters that appear after the function definition. -Note that Octave does not try to lookup the definition of any identifier +Note that Octave does not try to look up the definition of any identifier until it needs to evaluate it. This means that Octave will compile the following statements if they appear in a script file, or are typed at the command line, @@ -743,7 +745,7 @@ @noindent even though the function @code{do_something} is not defined before it is -referenced in the function @code{foo}. This is not an error because the +referenced in the function @code{foo}. This is not an error because Octave does not need to resolve all symbols that are referenced by a function until the function is actually evaluated. @@ -770,71 +772,188 @@ string might come from user input, or depend on things that are not known until the function is evaluated). +Although Octave normally executes commands from script files that have +the name @file{@var{file}.m}, you can use the function @code{source} to +execute commands from any file. + @deftypefn {Built-in Function} {} source (@var{file}) Parse and execute the contents of @var{file}. This is equivalent to executing commands from a script file, but without requiring the file to -be named @var{file}.m. +be named @file{@var{file}.m}. @end deftypefn @node Dynamically Linked Functions, Organization of Functions, Script Files, Functions and Scripts @section Dynamically Linked Functions +@cindex dynamic linking On some systems, Octave can dynamically load and execute functions -written in C++ or other compiled languages. This currently only works -on systems that have a working version of the GNU dynamic linker, -@code{dld}. Unfortunately, @code{dld} does not work on very many -systems, but someone is working on making @code{dld} use the GNU Binary -File Descriptor library, @code{BFD}, so that may soon change. In any -case, it should not be too hard to make Octave's dynamic linking -features work on other systems using system-specific dynamic linking -facilities. +written in C++. Octave can only directly call functions written in C++, +but you can also load functions written in other languages +by calling them from a simple wrapper function written in C++. Here is an example of how to write a C++ function that Octave can load, with commentary. The source for this function is included in the source -distributions of Octave, in the file @file{examples/hello.cc}. +distributions of Octave, in the file @file{examples/oregonator.cc}. It +defines the same set of differential equations that are used in the +example problem of @ref{Ordinary Differential Equations}. By running +that example and this one, we can compare the execution times to see +what sort of increase in speed you can expect by using dynamically +linked functions. -To use this file, your version of Octave must support dynamic -linking. To find out if it does, type the command +The function defined in @file{oregonator.cc} contains just 8 statements, +and is not much different than the code defined in the corresponding +M-file (also distributed with Octave in the file +@file{examples/oregonator.m}). + +Here is the complete text of @file{oregonator.cc}: + +just @example -x = octave_config_info; x.DEFS +@group +#include + +DEFUN_DLD (oregonator, args, , + "The `oregonator'.") +@{ + ColumnVector dx (3); + + ColumnVector x = args(0).vector_value (); + + dx(0) = 77.27 * (x(1) - x(0)*x(1) + x(0) + - 8.375e-06*pow (x(0), 2)); + + dx(1) = (x(2) - x(0)*x(1) - x(1)) / 77.27; + + dx(2) = 0.161*(x(0) - x(2)); + + return octave_value (dx); +@} +@end group +@end example + +The first line of the file, + +@example +#include +@end example + +@noindent +includes declarations for all of Octave's internal functions that you +will need. If you need other functions from the standard C++ or C +libraries, you can include the necessary headers here. + +The next two lines +@example +@group +DEFUN_DLD (oregonator, args, , + "The `oregonator'.") +@end group @end example @noindent -at the Octave prompt. Support for dynamic linking is included if -the output contains the string @code{-DWITH_DYNAMIC_LINKING=1}. +declares the function. The macro @code{DEFUN_DLD} and the macros that +it depends on are defined in the files @file{defun-dld.h}, +@file{defun.h}, and @file{defun-int.h} (these files are included in the +header file @file{octave/oct.h}). -To compile this file, type the command +Note that the third parameter to @code{DEFUN_DLD} (@code{nargout}) is +not used, so it is omitted from the list of arguments to in order to +avoid the warning from gcc about an unused function parameter. + +@noindent +simply declares an object to store the right hand sides of the +differential equation, and + +The statement @example -mkoctfile hello.cc +ColumnVector x = args(0).vector_value (); @end example @noindent -at the shell prompt. The script @file{mkoctfile} should have been -installed along with Octave. Running it will create a file called -@file{hello.oct} that can be loaded by Octave. To test the -@file{hello.oct} file, start Octave and type the command +extracts a column vector from the input arguments. The variable +@code{args} is passed to functions defined with @code{DEFUN_DLD} as an +@code{octave_value_list} object, which includes methods for getting the +length of the list and extracting individual elements. + +In this example, we don't check for errors, but that is not difficult. +All of the Octave's built-in functions do some form of checking on their +arguments, so you can check the source code for those functions for +examples of various strategies for verifying that the correct number and +types of arguments have been supplied. + +The next statements @example -hello ("easy as", 1, 2, 3) +@group +ColumnVector dx (3); + +dx(0) = 77.27 * (x(1) - x(0)*x(1) + x(0) + - 8.375e-06*pow (x(0), 2)); + +dx(1) = (x(2) - x(0)*x(1) - x(1)) / 77.27; + +dx(2) = 0.161*(x(0) - x(2)); +@end group +@end example + +@noindent +define the right hand side of the differential equation. Finally, we +can return @code{dx}: + +@example +return octave_value (dx); +@end example + +@noindent +The actual return type is @code{octave_value_list}, but it is only +necessary to convert the return type to an @code{octave_value} because +there is a default constructor that can automatically create an object +of that type from an @code{octave_value} object, so we can just use that +instead. + +To use this file, your version of Octave must support dynamic linking. +To find out if it does, type the command +@kbd{octave_config_info ("dld")} at the Octave prompt. Support for +dynamic linking is included if this command returns 1. + +To compile the example file, type the command @kbd{mkoctfile +oregonator.cc} at the shell prompt. The script @code{mkoctfile} should +have been installed along with Octave. Running it will create a file +called @file{oregonator.oct} that can be loaded by Octave. To test the +@file{oregonator.oct} file, start Octave and type the command + +@example +oregonator ([1, 2, 3], 0) @end example @noindent at the Octave prompt. Octave should respond by printing @example -Hello, world! -easy as -1 -2 -3 -ans = 3 +@group +ans = + + 77.269353 + -0.012942 + -0.322000 +@end group @end example -Additional examples are available in the files in the src directory -of the Octave distribution that use the macro @code{DEFUN_DLD_BUILTIN}. -Currently, this includes the files +You can now use the @file{oregonator.oct} file just as you would the +@code{oregonator.m} file to solve the set of differential equations. + +On a 133 MHz Pentium running Linux, Octave can solve the problem shown +in @ref{Ordinary Differential Equations} in about 1.4 second using the +dynamically linked function, compared to about 19 seconds using the +M-file. Similar decreases in execution time can be expected for other +functions, particularly those that rely on functions like @code{lsode} +that require user-supplied functions. + +Additional examples are available in the files in the @file{src} +directory of the Octave distribution. Currently, this includes the +files @example @group @@ -848,82 +967,17 @@ @end group @end example -The difference between @code{DEFUN_DLD} and @code{DEFUN_DLD_BUILTIN} is -that @code{DEFUN_DLD_BUILTIN} can define a built-in function that is not +@noindent +These files use the macro @code{DEFUN_DLD_BUILTIN} instead of +@code{DEFUN_DLD}. The difference between these two macros is just that +@code{DEFUN_DLD_BUILTIN} can define a built-in function that is not dynamically loaded if the operating system does not support dynamic linking. To define your own dynamically linked functions you should use @code{DEFUN_DLD}. -@example -@group -#include - -#include - -#include -#include -#include -#include -#include -#include -@end group -@end example - -@code{DEFUN_DLD} and the macros that it depends on are defined in the -files @file{defun-dld.h}, @file{defun.h}, and @file{defun-int.h}. - -Note that the third parameter (@code{nargout}) is not used, so it is -omitted from the list of arguments to @code{DEFUN_DLD} in order to avoid -the warning from gcc about an unused function parameter. - -@example -@group -DEFUN_DLD (hello, args, , - "[...] = hello (...)\n\ -\n\ -Print greeting followed by the values of all the arguments passed.\n\ -Returns all arguments in reverse order.") -@{ -@end group -@end example - -The list of values to return. See the declaration in @file{oct-obj.h}. - -@example - octave_value_list retval; -@end example - -This stream is normally connected to the pager. - -@example - octave_stdout << "Hello, world!\n"; -@end example - -The arguments to this function are available in @samp{args}. - -@example - int nargin = args.length (); -@end example - -The @code{octave_value_list} class is a zero-based array of -@code{octave_value} objects. The declaration for the -@code{octave_value} class is in the file @code{pt-const.h}. The -@code{print} method will send its output to @code{octave_stdout}, so -it will also end up going through the pager. - -@example -@group - for (int i = 0; i < nargin; i++) - @{ - octave_value tmp = args (i); - tmp.print (); - retval (nargin-i-1) = tmp; - @} - - return retval; -@} -@end group -@end example +There is currently no detailed description of all the functions that you +can call in a built-in function. For the time being, you will have to +read the source code for Octave. @node Organization of Functions, , Dynamically Linked Functions, Functions and Scripts @section Organization of Functions Distributed with Octave diff --git a/doc/interpreter/image.texi b/doc/interpreter/image.texi --- a/doc/interpreter/image.texi +++ b/doc/interpreter/image.texi @@ -11,6 +11,13 @@ manipulate images, however, so some of these functions may be useful even if you are not able to view the results. +Loading images only works with Octave's image format (a file with a +matrix containing the image data, and a matrix containing the +colormap). Contributions of robust, well-written functions to read +other image formats are welcome. If you can provide them, or would like +to improve Octave's image processing capabilities in other ways, please +contact @email{bug-octave@@bevo.che.wisc.edu}. + @deftypefn {Function File} {} colormap (@var{map}) @deftypefnx {Function File} {} colormap ("default") Set the current colormap. diff --git a/doc/interpreter/install.texi b/doc/interpreter/install.texi --- a/doc/interpreter/install.texi +++ b/doc/interpreter/install.texi @@ -47,16 +47,25 @@ Look for Octave sources in the directory @var{dir}. @item --with-f2c -Use f2c even if Fortran compiler is available. +Use @code{f2c} even if a Fortran compiler is available. + +@item --with-g77 +Use @code{g77} to compile Fortran code. -@item --enable-dld -Use DLD to make Octave capable of dynamically linking -externally compiled functions. This only works on systems that have a -working port of DLD. +@item --enable-dl +Use @code{dlopen} and friends to make Octave capable of dynamically +linking externally compiled functions. This only works on systems that +actually have these functions. + +@item --enable-shl +Use @code{shl_load} and friends to make Octave capable of dynamically +linking externally compiled functions. This only works on systems that +actually have these functions (only HP-UX systems). @item --enable-lite-kernel -Compile smaller kernel. This currently requires DLD so that Octave can -load functions at run time that are not loaded at compile time. +Compile smaller kernel. This currently requires the dynamic linking +functions @code{dlopen} or @code{shl_load} and friends so that Octave +can load functions at run time that are not loaded at compile time. @item --help Print a summary of the options recognized by the configure script. @@ -69,9 +78,9 @@ @item Run make. -You will need a recent version of GNU make. Modifying Octave's +You will need a recent version of GNU Make. Modifying Octave's makefiles to work with other make programs is probably not worth -your time. We recommend you get and compile GNU make instead. +your time. We recommend you get and compile GNU Make instead. For plotting, you will need to have gnuplot installed on your system. Gnuplot is a command-driven interactive function plotting program. @@ -79,32 +88,33 @@ is a coincidence---it is not related to the GNU project or the FSF in any but the most peripheral sense. -For version @value{VERSION}, you must have the GNU C++ compiler (gcc) -version 2.7.2 or later to compile Octave. You will also need version -2.7.1 or 2.7.2 of the GNU C++ class library (libg++). If you plan to -modify the parser you will also need GNU bison and fles. If you modify -the documentation, you will need GNU Texinfo, along with the patch for -the makeinfo program that is distributed with Octave. +For version @value{VERSION}, you must have the GNU C++ compiler +(@code{gcc}) version 2.7.2 or later to compile Octave. You will also +need version 2.7.1 or 2.7.2 of the GNU C++ class library +(@code{libg++}). If you plan to modify the parser you will also need +GNU @code{bison} and @code{flex}. If you modify the documentation, you +will need GNU Texinfo, along with the patch for the @code{makeinfo} +program that is distributed with Octave. -GNU make, gcc, and libg++, gnuplot, bison, flex, and Texinfo are all -available from many anonymous ftp archives. The primary site is -prep.ai.mit.edu, but it is often very busy. A list of sites that mirror -the software on prep is available by anonymous ftp from prep.ai.mit.edu -in the file @file{/pub/gnu/GNUinfo/FTP}, or by fingering -fsf@@prep.ai.mit.edu. +GNU Make, @code{gcc}, and @code{libg++}, @code{gnuplot}, @code{bison}, +@code{flex}, and Texinfo are all available from many anonymous ftp +archives. The primary site is @url{prep.ai.mit.edu}, but it is often +very busy. A list of sites that mirror the software on @code{prep} is +available by anonymous ftp from +@url{ftp://prep.ai.mit.edu/pub/gnu/GNUinfo/FTP}, or by fingering +@email{fsf@@prep.ai.mit.edu}. If you don't have a Fortran compiler, or if your Fortran compiler doesn't work like the traditional Unix f77, you will need to have the -Fortran to C translator f2c. You can get f2c from any -number of anonymous ftp archives. The most recent version of f2c -is always available from netlib.att.com. +Fortran to C translator @code{f2c}. You can get @code{f2c} from any +number of anonymous ftp archives. The most recent version of @code{f2c} +is always available from @url{netlib.att.com}. -On an otherwise idle SPARCstation II, it will take somewhere between 60 -and 90 minutes to compile everything, depending on whether you are -compiling the Fortran libraries with f2c or using the Fortran compiler -directly. You will need about 50 megabytes of disk storage to work with -(considerably less if you don't compile with debugging symbols). To do -that, use the command +On an otherwise idle Pentium 133 running Linux, it will take somewhere +between 1-1/2 to 3 hours to compile everything, depending on whether you +are building shared libraries. You will need about 100 megabytes of disk +storage to work with (considerably less if you don't compile with debugging +symbols). To do that, use the command @example make CFLAGS=-O CXXFLAGS=-O LDFLAGS= @@ -194,7 +204,7 @@ find the source for the header file and install it in the directory @file{usr/include}. This is reportedly a problem with Slackware 3.1. For Linux/GNU systems, the source for @file{dlfcn.h} is in the -@samp{ldso} package. +@code{ldso} package. @item If you encounter errors like @@ -215,7 +225,7 @@ @noindent while compiling @file{sighandlers.cc}, you may need to edit some files -in the gcc include subdirectory to add proper prototypes for functions +in the @code{gcc} include subdirectory to add proper prototypes for functions there. For example, Ultrix 4.2 needs proper declarations for the @code{signal} function and the @code{SIG_IGN} macro in the file @file{signal.h}. @@ -240,29 +250,29 @@ symbols. It may be necessary to change the definitions in @file{sys/signal.h} as well. -The gcc fixincludes/fixproto script should probably fix these problems -when gcc installs its modified set of header files, but I don't think -that's been done yet. +The @code{gcc} @code{fixincludes} and @code{fixproto} scripts should +probably fix these problems when @code{gcc} installs its modified set of +header files, but I don't think that's been done yet. @strong{You should not change the files in @file{/usr/include}}. You -can find the gcc include directory tree by running the command +can find the @code{gcc} include directory tree by running the command @example gcc -print-libgcc-file-name @end example @noindent -The directory of gcc include files normally begins in the same directory +The directory of @code{gcc} include files normally begins in the same directory that contains the file @file{libgcc.a}. @item -There is a bug with the makeinfo program that is distributed with +There is a bug with the @code{makeinfo} program that is distributed with Texinfo (through version 3.9) that causes the indices in Octave's on-line manual to be generated incorrectly. If you need to recreate the -on-line documentation, you should get the makeinfo program that is -distributed with texinfo-3.9 and apply the patch for makeinfo that is -distributed with Octave. See the file @file{MAKEINFO.PATCH} for more -details. +on-line documentation, you should get the @code{makeinfo} program that +is distributed with texinfo-3.9 and apply the patch for @code{makeinfo} +that is distributed with Octave. See the file @file{MAKEINFO.PATCH} for +more details. @item Some of the Fortran subroutines may fail to compile with older versions @@ -305,7 +315,7 @@ Some people have reported that calls to shell_cmd and the pager do not work on SunOS systems. This is apparently due to having @code{G_HAVE_SYS_WAIT} defined to be 0 instead of 1 when compiling -libg++. +@code{libg++}. @item On NeXT systems, linking to @file{libsys_s.a} may fail to resolve the @@ -356,13 +366,13 @@ proper thing to do. @item -If you don't have NPSOL but you still want to be able to solve NLPs, or -if you don't have QPSOL but you still want to solve QPs, you'll need to -find replacements or order them from Stanford. If you know of a freely -redistributable replacement, please let us know---we might be interested -in distributing it with Octave. +If you don't have @sc{Npsol} but you still want to be able to solve +NLPs, or if you don't have @sc{Qpsol} but you still want to solve QPs, +you'll need to find replacements or order them from Stanford. If you +know of a freely redistributable replacement, please let us know---we +might be interested in distributing it with Octave. -You can get more information about NPSOL and QPSOL from +You can get more information about @sc{Npsol} and @sc{Qpsol} from @quotation Stanford Business Sofrtware, Inc.@* @@ -372,17 +382,37 @@ Fax: (415) 962-1869 @end quotation -Octave may soon support FSQP, an NLP solver from Andre Tits -(andre@@src.umd.edu) of the University of Maryland. FSQP is available -free of charge to academic sites, but can not be redistributed to third -parties. +Octave may soon support @sc{Fsqp}, an NLP solver from Andre Tits +@email{andre@@src.umd.edu} of the University of Maryland. @sc{Fsqp} is +available free of charge to academic sites, but can not be redistributed +to third parties. @end itemize @node Binary Distributions, , Installation Problems, Installation @appendixsec Binary Distributions -This section contains instructions for creating and installing a -binary distribution. +Although Octave is not very difficult to build from its sources, it is a +relatively large program that does require a significant amount of time +and disk space to compile and install. Because of this, many people +want to be able to obtain binary distributions so they can start using +Octave immediately, without having to bother with the details of +compiling it first. This is understandable, so I try to maintain a +current collection of binary distributions at +@url{ftp://ftp.che.wisc.edu/pub/octave/BINARIES}. + +Please understand, however, that there is only a limited amount of time +available to devote to making binaries, so binaries may not be +immediately available for some platforms. (Please contact +@email{bug-octave@@bevo.che.wisc.edu} if you are interested in helping +make a binary distributions available for your system.) + +Also, binary distributions are limited to static binaries that do not +support dynamic linking. For earlier versions of Octave, I tried +distributing dynamically linked binaries but that proved to be too much +trouble to support. If you want to have a copy of Octave that includes +all the features described in this manual, you will have to build it +from the sources yourself, or find someone else who is willing to do it +for you. @menu * Installing Octave from a Binary Distribution:: @@ -392,8 +422,6 @@ @node Installing Octave from a Binary Distribution, Creating a Binary Distribution, Binary Distributions, Binary Distributions @appendixsubsec Installing Octave from a Binary Distribution -@itemize @bullet -@item To install Octave from a binary distribution, execute the command @example @@ -439,9 +467,9 @@ @noindent where @var{version} stands for the current version number of the interpreter, and @var{host_type} is the type of computer on which Octave -is installed (for example, @samp{i486-unknown-gnu}). +is installed (for example, @samp{@value{TARGETHOSTTYPE}}). -If these directories don't exist, the script @file{install-octave} will +If these directories don't exist, the script @code{install-octave} will create them for you. The installation script also creates the following subdirectories of @file{/usr/local} that are intended for locally installed functions: @@ -451,7 +479,7 @@ Locally installed M-files. @item libexec/octave/site/exec/@var{host_type} -Locally installed binaries intendec to be run by Octave rather than by +Locally installed binaries intended to be run by Octave rather than by the user. @item libexec/octave/site/octave/@var{host_type} @@ -470,57 +498,41 @@ @noindent will install Octave in subdirectories of the directory @file{/some/other/directory}. -@end itemize @node Creating a Binary Distribution, , Installing Octave from a Binary Distribution, Binary Distributions @appendixsubsec Creating a Binary Distribution -Here is how to build a binary distribution for others. +Here is how to build a binary distribution for others to use. If you +want to make a binary distribution for your system available along with +the Octave sources and binaries on @url{ftp.che.wisc.edu}, please follow +this procedure. For directions explaining how to make the binary +available on the ftp site, please contact +@email{bug-octave@@bevo.che.wisc.edu}. @itemize @bullet @item -Unpack the source distribution. - -@item -Configure Octave using the command +Unpack the source distribution: @example -./configure --disable-dl --disable-shl --disable-shared -@end example - -If your system supports shared libraries and dynamic linking, you should -also build a binary that supports those features, but it is important to -create a statically linked executable that will run no matter what -versions of the libraries are installed on the target system. - -@item -Build the binaries using the command - -@example -make LDFLAGS=-static +gunzip -c octave-@value{VERSION}.tar.gz | tar xf - @end example @item -Type @samp{make static-binary-dist}. This will create a compressed tar -file ready for distribution. The file will have a name like -@file{octave-@var{version}-@var{host_type}-static.tar.gz}. - -@item -If your system supports dynamic linking and shared libraries, build -another version of Octave that supports these features. Use the -commands +Change your current directory to the top-level directory of the source +distribution: @example -@group -configure --enable-shared -make -make dynamic-binary-dist -@end group +cd octave-@value{VERSION} @end example -@noindent -This will create a compressed tar file ready for distribution. The file -will have a name like -@file{octave-@var{version}-@var{host_type}-dynamic.tar.gz}. +@item +Make the binary distribution: +@example +make binary-dist +@end example + +This will create a compressed tar file ready for distribution. +It will contain statically linked binaries and have a name like +@file{octave-@value{VERSION}-@value{TARGETHOSTTYPE}.tar.gz} @end itemize diff --git a/doc/interpreter/intro.texi b/doc/interpreter/intro.texi --- a/doc/interpreter/intro.texi +++ b/doc/interpreter/intro.texi @@ -37,7 +37,7 @@ @section Running Octave On most systems, the way to invoke Octave is with the shell command -@samp{octave}. Octave displays an initial message and then a prompt +@kbd{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. @@ -49,7 +49,7 @@ @cindex exiting octave @cindex quitting octave -To exit Octave, type @samp{quit}, or @samp{exit} at the Octave prompt. +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}. @@ -90,7 +90,7 @@ To display the value of any variable, simply type the name of the variable. For example, to display the value stored in the matrix -@samp{b}, type the command +@code{b}, type the command @example octave:3> b @@ -99,14 +99,14 @@ @unnumberedsubsec Matrix Arithmetic Octave has a convenient operator notation for performing matrix -arithmetic. For example, to multiply the matrix @var{a} by a scalar +arithmetic. For example, to multiply the matrix @code{a} by a scalar value, type the command @example octave:4> 2 * a @end example -To multiply the two matrices @var{a} and @var{b}, type the command +To multiply the two matrices @code{a} and @code{b}, type the command @example octave:5> a * b @@ -115,11 +115,11 @@ To form the matrix product @iftex @tex - $a^Ta$, +$@code{a}^T@code{a}$, @end tex @end iftex @ifinfo - @code{transpose (a) * a}, +@code{transpose (a) * a}, @end ifinfo type the command @@ -129,15 +129,7 @@ @unnumberedsubsec Solving Linear Equations -To solve the set of linear equations -@iftex -@tex - ${\bf Ax} = {\bf b}$, -@end tex -@end iftex -@ifinfo -@code{Ax = b}, -@end ifinfo +To solve the set of linear equations @code{a@var{x} = b}, use the left division operator, @samp{\}: @example @@ -148,11 +140,11 @@ This is conceptually equivalent to @iftex @tex - ${\bf A}^{-1}{\bf b}$, +$@code{a}^{-1}@code{b}$, @end tex @end iftex @ifinfo -inv (A) * b, +@code{inv (a) * b}, @end ifinfo but avoids computing the inverse of a matrix directly. @@ -166,7 +158,7 @@ @iftex @tex $$ - {dx \over dt} = f(x,t), \qquad {\rm with} x(t=t_0) = x_0 + {dx \over dt} = f(x,t), \qquad x(t=t_0) = x_0 $$ @end tex @end iftex @@ -247,7 +239,7 @@ @end example @noindent -The function @samp{lsode} uses the Livermore Solver for Ordinary +The function @code{lsode} uses the Livermore Solver for Ordinary Differential Equations, described in A. C. Hindmarsh, @cite{ODEPACK, a Systematized Collection of ODE Solvers}, in: Scientific Computing, R. S. Stepleman et al. (Eds.), North-Holland, Amsterdam, 1983, pages 55--64. @@ -267,7 +259,7 @@ kind of terminal you have. Type the command @example -set term +gset term @end example @noindent @@ -281,15 +273,15 @@ @example @group -set term postscript -set output "foo.ps" +gset term postscript +gset output "foo.ps" replot @end group @end example @noindent This will work for other types of output devices as well. Octave's -@samp{set} command is really just piped to the @code{gnuplot} +@code{gset} command is really just piped to the @code{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. @@ -298,8 +290,8 @@ @example @group -set term postscript -set output "|lpr -Pname_of_your_graphics_printer" +gset term postscript +gset output "|lpr -Pname_of_your_graphics_printer" replot @end group @end example @@ -342,9 +334,8 @@ will display the help text for the @code{plot} function. Octave sends output that is too long to fit on one screen through a -pager like @code{less} or @code{more}. Type a carriage return to -advance one line, a space character to advance one page, and @samp{q} to -exit the pager. +pager like @code{less} or @code{more}. Type a @key{RET} to advance one +line, a @key{SPC} to advance one page, and @key{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 @@ -560,6 +551,11 @@ @cindex function file The function described is defined using Octave commands stored in a text file. @xref{Function Files}. + +@item Mapping Function +@cindex mapping function +The function described works element-by-element for matrix and vector +arguments. @end table @node A Sample Command Description, A Sample Variable Description, A Sample Function Description, Format of Descriptions @@ -592,7 +588,7 @@ using a format like that for functions except that there are no arguments. -Here is a description of the imaginary built-in variable +Here is a description of the imaginary variable @code{do_what_i_mean_not_what_i_say}. @defvr {Built-in Variable} do_what_i_mean_not_what_i_say diff --git a/doc/interpreter/io.texi b/doc/interpreter/io.texi --- a/doc/interpreter/io.texi +++ b/doc/interpreter/io.texi @@ -100,8 +100,8 @@ value of pi @example -octave:13> pi -pi = 3.1416 +pi + @print{} pi = 3.1416 @end example This works well as long as it is acceptable to have the name of the @@ -121,22 +121,17 @@ @end example @noindent -is evaluated, the value of @code{ans} is @samp{25}. +is evaluated, the value of @code{ans} is 25. @end defvr @deftypefn {Built-in Function} {} disp (@var{x}) -Display the value of @var{x}. For example, the following expression +Display the value of @var{x}. For example, @example disp ("The value of pi is:"), disp (pi) -@end example -@noindent -will print - -@example -The value of pi is: -3.1416 + @print{} the value of pi is: + @print{} 3.1416 @end example @noindent @@ -170,21 +165,14 @@ @itemx short e The same as @samp{format long} or @samp{format short} but always display output with an @samp{e} format. For example, with the @samp{short e} -format, pi is displayed as - -@example - 3.14e+00 -@end example +format, pi is displayed as @code{3.14e+00}. @item long E @itemx short E The same as @samp{format long e} or @samp{format short e} but always display output with an uppercase @samp{E} format. For example, with the @samp{long E} format, pi is displayed as - -@example - 3.14159265358979E+00 -@end example +@code{3.14159265358979E+00}. @item free @itemx none @@ -375,7 +363,7 @@ match all lower and upper case alphabetic characters. @end table -Except when using hte @sc{Matlab} binary data file format, saving global +Except when using the @sc{Matlab} binary data file format, saving global variables also saves the global status of the variable, so that if it is restored at a later time using @samp{load}, it will be restored as a global variable. @@ -406,10 +394,10 @@ @end defvr @deffn {Command} load options file v1 v2 @dots{} -To restore the values from a file, use the @code{load} command. As with -@code{save}, you may specify a list of variables and @code{load} will -only extract those variables with names that match. For example, to -restore the variables saved in the file @file{data}, use the command +Load the named variables from the file @var{file}. As with @code{save}, +you may specify a list of variables and @code{load} will only extract +those variables with names that match. For example, to restore the +variables saved in the file @file{data}, use the command @example load data @@ -458,7 +446,7 @@ argument lists for some of the input functions are slightly different, however, because Octave has no way of passing arguments by reference. -In the following, @var{file} refers to a file name and @code{fid} returs +In the following, @var{file} refers to a file name and @code{fid} refers to an integer file number, as returned by @code{fopen}. There are three files that are always available. Although these files @@ -508,14 +496,14 @@ @node Opening and Closing Files, Simple Output, C-Style I/O Functions, C-Style I/O Functions @subsection Opening and Closing Files -@deftypefn {Built-in Function} {[fid, msg] =} fopen (@var{name}, @var{mode}, @var{arch}) -@deftypefnx {Built-in Function} {fid_list =} fopen ("all") -@deftypefnx {Built-in Function} {file =} fopen (@var{fid}) +@deftypefn {Built-in Function} {[@var{fid}, @var{msg}] =} fopen (@var{name}, @var{mode}, @var{arch}) +@deftypefnx {Built-in Function} {@var{fid_list} =} fopen ("all") +@deftypefnx {Built-in Function} {@var{file} =} fopen (@var{fid}) The first form of the @code{fopen} function opens the named file with the specified mode (read-write, read-only, etc.) and architecture interpretation (IEEE big endian, IEEE little endian, etc.), and returns an integer value that may be used to refer to the file later. If an -error occurs, @var{fid} is set to -1 and @var{msg} contains the +error occurs, @var{fid} is set to @minus{}1 and @var{msg} contains the corresponding system error message. The @var{mode} is a one or two character string that specifies whether the file is to be opened for reading, writing, or both. @@ -625,7 +613,7 @@ If @var{len} is omitted, @code{fgetl} reads until the next newline character. -If there are no more characters to read, @code{fgetl} returns -1. +If there are no more characters to read, @code{fgetl} returns @minus{}1. @end deftypefn @deftypefn {Built-in Function} {} fgets (@var{fid}, @var{len}) @@ -637,7 +625,7 @@ If @var{len} is omitted, @code{fgets} reads until the next newline character. -If there are no more characters to read, @code{fgets} returns -1. +If there are no more characters to read, @code{fgets} returns @minus{}1. @end deftypefn @node Formatted Output, Output Conversion for Matrices, Line-Oriented Input, C-Style I/O Functions @@ -1043,27 +1031,62 @@ @node Formatted Input, Input Conversion Syntax, Other Output Conversions, C-Style I/O Functions @subsection Formatted Input -Here are the descriptions of the functions for performing formatted -input. +Octave provides the @code{scanf}, @code{fscanf}, and @code{sscanf} +functions to read formatted input. There are two forms of each of these +functions. One can be used to extract vectors of data from a file, and +the other is more `C-like'. + +@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} fscanf (@var{fid}, @var{template}, @var{size}) +@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}] = } fscanf (@var{fid}, @var{template}, "C") +In the first form, read from @var{fid} according to @var{template}, +returning the result in the matrix @var{val}. + +The optional argument @var{size} specifies the amount of data to read +and may be one of + +@table @code +@item Inf +Read as much as possible, returning a column vector. -@deftypefn {Built-in Function} {} scanf (@var{template}) -@deftypefnx {Built-in Function} {} scanf (@var{template}, "C") -The @code{scanf} function reads formatted input from the stream -@code{stdin} under the control of the template string @var{template}. -The resulting values are returned. +@item @var{nr} +@itemx [@var{nr}, Inf] +Read as much as possible, returning a matrix with @var{nr} rows. If the +number of elements read is not an exact multiple of @var{nr}, the last +column is padded with zeros. + +@item [@var{nr}, @var{nc}] +Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with +@var{nr} rows. If the number of elements read is not an exact multiple +of @var{nr}, the last column is padded with zeros. +@end table + +@noindent +If @var{size} is omitted, a value of @code{Inf} is assumed. + +A string is returned if @var{template} specifies only character +conversions. + +The number of items successfully read is returned in @var{count}. + +In the second form, read from @var{fid} according to @var{template}, +with each conversion specifier in @var{template} corresponding to a +single scalar return value. This form is more `C-like', and also +compatible with previous versions of Octave. @end deftypefn -@deftypefn {Built-in Function} {} fscanf (@var{fid}, @var{template}) -@deftypefnx {Built-in Function} {} fscanf (@var{fid}, @var{template}, "C") -This function is just like @code{scanf}, except that the input is read -from the stream @var{fid} instead of @code{stdin}. +@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} sscanf (@var{string}, @var{template}, @var{size}) +@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}] = } sscanf (@var{string}, @var{template}, "C") +This is like @code{fscanf}, except that the characters are taken from the +string @var{string} instead of from a stream. Reaching the end of the +string is treated as an end-of-file condition. @end deftypefn -@deftypefn {Built-in Function} {} sscanf (@var{string}, @var{template}) -@deftypefnx {Built-in Function} {} sscanf (@var{string}, @var{template}, "C") -This is like @code{scanf}, except that the characters are taken from the -string @var{string} instead of from a stream. Reaching the end of the -string is treated as an end-of-file condition. +@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} scanf (@var{template}, @var{size}) +@deftypefnx {Built-in Function} {[@var{v1}, @var{v2}, @dots{}] = } scanf (@var{template}, "C") +This is equivalent to calling @code{fscanf} with @var{fid} = @code{stdin}. + +It is currently not useful to call @code{scanf} in interactive +programs. @end deftypefn Calls to @code{scanf} are superficially similar to calls to @@ -1262,48 +1285,144 @@ @node Binary I/O, Temporary Files, String Input Conversions, C-Style I/O Functions @subsection Binary I/O -Octave has to C-style functions for reading and writing binary data. -They are @code{fread} and @code{fwrite} and are patterned after the -standard C functions with the same names. +Octave can read and write binary data using the functions @code{fread} +and @code{fwrite}, which are patterned after the standard C functions +with the same names. The are able to automatically swap the byte order +of integer data and convert among ths supported floating point formats +as the data are read. + +@deftypefn {Built-in Function} {[@var{val}, @var{count}] =} fread (@var{fid}, @var{size}, @var{precision}, @var{skip}, @var{arch}) +Read binary data of type @var{precision} from the specified file ID +@var{fid}. + +The optional argument @var{size} specifies the amount of data to read +and may be one of + +@table @code +@item Inf +Read as much as possible, returning a column vector. + +@item @var{nr} +@itemx [@var{nr}, Inf] +Read as much as possible, returning a matrix with @var{nr} rows. If the +number of elements read is not an exact multiple of @var{nr}, the last +column is padded with zeros. + +@item [@var{nr}, @var{nc}] +Read up to @code{@var{nr} * @var{nc}} elements, returning a matrix with +@var{nr} rows. If the number of elements read is not an exact multiple +of @var{nr}, the last column is padded with zeros. +@end table -@deftypefn {Built-in Function} {} fread (@var{fid}, @var{size}, @var{precision}, @var{arch}) -This function reads data in binary form of type @var{precision} from the -specified @var{fid}, which may be either a file name, or a file id -as returned from @code{fopen}. +@noindent +If @var{size} is omitted, a value of @code{Inf} is assumed. + +The optional argument @var{precision} is a string specifying the type of +data to read and may be one of + +@table @code +@item "char" +@itemx "char*1" +@itemx "integer*1" +@itemx "int8" +Single character. + +@item "signed char" +@itemx "schar" +Signed character. + +@item "unsigned char" +@itemx "uchar" +Unsigned character. + +@item "short" +Short integer. + +@item "unsigned short" +@itemx "ushort" +Unsigned short integer. + +@item "int" +Integer. -The argument @var{size} specifies the size of the matrix to return. It -may be a scalar or a two-element vector. If it is a scalar, -@code{fread} returns a column vector of the specified length. If it is -a two-element vector, it specifies the number of rows and columns of the -result matrix, and @code{fread} fills the elements of the matrix in -column-major order. +@item "unsigned int" +@itemx "uint" +Unsigned integer. + +@item "long" +Long integer. + +@item "unsigned long" +@itemx "ulong" +Unsigned long integer. + +@item "float" +@itemx "float32" +@itemx "real*4" +Single precision float. + +@item "double" +@itemx "float64" +@itemx "real*8" +Double precision float. + +@item "integer*2" +@itemx "int16" +Two byte integer. + +@item "integer*4" +@itemx "int32" +Four byte integer. +@end table + +@noindent +The default precision is @code{"uchar"}. -The argument @var{precision} is a string specifying the type of data to -read and may be one of @code{"char"}, @code{"schar"}, @code{"short"}, -@code{"int"}, @code{"long"}, @code{"float"}, @code{"double"}, -@code{"uchar"}, @code{"ushort"}, @code{"uint"}, or @code{"ulong"}. The -default precision is @code{"uchar"}. +The optional argument @var{skip} specifies the number of bytes to skip +before each element is read. If it is not specified, a value of 0 is +assumed. + +The optional argument @var{arch} is a string specifying the data format +for the file. Valid values are + +@table @code +@item "native" +The format of the current machine. + +@item "ieee-le" +IEEE big endian. + +@item "ieee-be" +IEEE little endian. -The @code{fread} function returns two values, @code{data}, which is the -data read from the file, and @code{count}, which is the number of -elements read. +@item "vaxd" +VAX D floating format. + +@item "vaxg" +VAX G floating format. + +@item "cray" +Cray floating format. +@end table + +@noindent +Conversions are currently only supported for @code{"ieee-be"} and +@code{"ieee-le"} formats. + +The data read from the file is returned in @var{val}, and the number of +values read is returned in @code{count} @end deftypefn -@deftypefn {Built-in Function} {} fwrite (@var{fid}, @var{data}, @var{precision}, @var{arch}) -This function writes data in binary form of type @var{precision} to the -specified @var{fid}, which may be either a file name, or a file id -as returned from @code{fopen}. +@deftypefn {Built-in Function} {@var{count} =} fwrite (@var{fid}, @var{data}, @var{precision}, @var{skip}, @var{arch}) +Write data in binary form of type @var{precision} to the specified file +ID @var{fid}, returning the number of values successfully written to the +file. The argument @var{data} is a matrix of values that are to be written to the file. The values are extracted in column-major order. -The argument @var{precision} is a string specifying the type of data to -read and may be one of @code{"char"}, @code{"schar"}, @code{"short"}, -@code{"int"}, @code{"long"}, @code{"float"}, @code{"double"}, -@code{"uchar"}, @code{"ushort"}, @code{"uint"}, or @code{"ulong"}. The -default precision is @code{"uchar"}. - -The @code{fwrite} function returns the number of elements written. +The remaining arguments @var{precision}, @var{skip}, and @var{arch} are +optional, and are interpreted as described for @code{fread}. The behavior of @code{fwrite} is undefined if the values in @var{data} are too large to fit in the specified precision. @@ -1366,14 +1485,14 @@ from the beginning of the file @var{fid}. @end deftypefn -@deftypefn {Built-in Function} {} fseek (@var{fid}, offset, origin) +@deftypefn {Built-in Function} {} fseek (@var{fid}, @var{offset}, @var{origin}) Set the file pointer to any location within the file @var{fid}. The -pointer is positioned @code{offset} characters from the @code{origin}, +pointer is positioned @var{offset} characters from the @var{origin}, which may be one of the predefined variables @code{SEEK_CUR} (current position), @code{SEEK_SET} (beginning), or @code{SEEK_END} (end of -file). If @code{origin} is omitted, @code{SEEK_SET} is assumed. The +file). If @var{origin} is omitted, @code{SEEK_SET} is assumed. The offset must be zero, or a value returned by @code{ftell} (in which case -@code{origin} must be @code{SEEK_SET}. +@var{origin} must be @code{SEEK_SET}. @end deftypefn @defvr {Built-in Variable} SEEK_SET @@ -1390,7 +1509,7 @@ @end deftypefn The following example stores the current file position in the variable -@samp{marker}, moves the pointer to the beginning of the file, reads +@code{marker}, moves the pointer to the beginning of the file, reads four characters, and then returns to the original position. @example diff --git a/doc/interpreter/linalg.texi b/doc/interpreter/linalg.texi --- a/doc/interpreter/linalg.texi +++ b/doc/interpreter/linalg.texi @@ -8,7 +8,7 @@ This chapter documents the linear algebra functions of Octave. Reference material for many of these functions may be found in Golub and Van Loan, @cite{Matrix Computations, 2nd Ed.}, Johns Hopkins, -1989, and in @cite{LAPACK Users' Guide}, SIAM, 1992. +1989, and in @cite{@sc{Lapack} Users' Guide}, SIAM, 1992. @menu * Basic Matrix Functions:: @@ -24,17 +24,17 @@ @deftypefnx {Loadable Function} {[@var{cc}, @var{dd}, @var{aa}, @var{bb]} =} balance (@var{a}, @var{b}, @var{opt}) @code{[dd, aa] = balance (a)} returns @code{aa = dd \ a * dd}. -@code{aa} is a matrix whose row/column norms are roughly equal in +@code{aa} is a matrix whose row and column norms are roughly equal in magnitude, and @code{dd} = @code{p * d}, where @code{p} is a permutation matrix and @code{d} is a diagonal matrix of powers of two. This allows the equilibration to be computed without roundoff. Results of eigenvalue calculation are typically improved by balancing first. -@code{[cc, dd, aa, bb] = balance (a, b)} returns @code{aa} (@code{bb}) -@code{= cc*a*dd (cc*b*dd)}), where @code{aa} and @code{bb} have -non-zero elements of approximately the same magnitude and @code{cc} -and @code{dd} are permuted diagonal matrices as in @code{dd} for -the algebraic eigenvalue problem. +@code{[cc, dd, aa, bb] = balance (a, b)} returns @code{aa = cc*a*dd} and +@code{bb = cc*b*dd)}, where @code{aa} and @code{bb} have non-zero +elements of approximately the same magnitude and @code{cc} and @code{dd} +are permuted diagonal matrices as in @code{dd} for the algebraic +eigenvalue problem. The eigenvalue balancing option @code{opt} is selected as follows: @@ -54,7 +54,7 @@ behavior. @end table -Algebraic eigenvalue balancing uses standard LAPACK routines. +Algebraic eigenvalue balancing uses standard @sc{Lapack} routines. Generalized eigenvalue problem balancing uses Ward's algorithm (SIAM Journal on Scientific and Statistical Computing, 1981). @@ -67,33 +67,49 @@ @end deftypefn @deftypefn {Loadable Function} {} det (@var{a}) -Compute the determinant of @var{a} using LINPACK. +Compute the determinant of @var{a} using @sc{Linpack}. @end deftypefn @deftypefn {Loadable Function} {@var{lambda} =} eig (@var{a}) @deftypefnx {Loadable Function} {[@var{v}, @var{lambda}] =} eig (@var{a}) The eigenvalues (and eigenvectors) of a matrix are computed in a several -step process which begins with a Hessenberg decomposition (see -@code{hess}), followed by a Schur decomposition (see @code{schur}), from -which the eigenvalues are apparent. The eigenvectors, when desired, are -computed by further manipulations of the Schur decomposition. - -See also: @code{hess}, @code{schur}. +step process which begins with a Hessenberg decomposition, followed by a +Schur decomposition, from which the eigenvalues are apparent. The +eigenvectors, when desired, are computed by further manipulations of the +Schur decomposition. @end deftypefn @deftypefn {Loadable Function} {@var{G} =} givens (@var{x}, @var{y}) @deftypefnx {Loadable Function} {[@var{c}, @var{s}] =} givens (@var{x}, @var{y}) -@code{G = givens(x, y)} returns a @iftex @tex -$2\times 2$ +Return a $2\times 2$ orthogonal matrix +$$ + G = \left[\matrix{c & s\cr -s'& c\cr}\right] +$$ +such that +$$ + G \left[\matrix{x\cr y}\right] = \left[\matrix{\ast\cr 0}\right] +$$ +with $x$ and $y$ scalars. @end tex @end iftex @ifinfo -2 x 2 +Return a 2 by 2 orthogonal matrix +@code{@var{G} = [@var{c} @var{s}; -@var{s}' @var{c}]} such that +@code{@var{G} [@var{x}; @var{y}] = [*; 0]} with @var{x} and @var{y} scalars. @end ifinfo -orthogonal matrix @code{G = [c s; -s' c]} such that -@code{G [x; y] = [*; 0]} (x, y scalars) + +For example, + +@example +@group +givens (1, 1) + + @result{} 0.70711 0.70711 + -0.70711 0.70711 +@end group +@end example @end deftypefn @deftypefn {Loadable Function} {} inv (@var{a}) @@ -115,23 +131,25 @@ Largest singular value of @var{a}. @item @var{p} = @code{Inf} +@cindex infinity norm Infinity norm, the largest row sum of @var{a}. @item @var{p} = @code{"fro"} -Frobenius norm of @var{a}, @code{sqrt (sum (diag (a' * a)))}. +@cindex Frobenius norm +Frobenius norm of @var{a}, @code{sqrt (sum (diag (@var{a}' * @var{a})))}. @end table If @var{a} is a vector or a scalar: @table @asis @item @var{p} = @code{Inf} -@code{max (abs (a))}. +@code{max (abs (@var{a}))}. @item @var{p} = @code{-Inf} -@code{min (abs (a))}. +@code{min (abs (@var{a}))}. @item other -p-norm of @var{a}, @code{(sum (abs (a) .^ p)) ^ (1/p)}. +p-norm of @var{a}, @code{(sum (abs (@var{a}) .^ @var{p})) ^ (1/@var{p})}. @end table @end deftypefn @@ -143,7 +161,7 @@ is missing, it is computed as @example -max (size (a)) * max (svd (a)) * eps +max (size (@var{a})) * max (svd (@var{a})) * eps @end example @end deftypefn @@ -155,22 +173,22 @@ missing, it is computed as @example -max (size (a)) * max (svd (a)) * eps +max (size (@var{a})) * max (svd (@var{a})) * eps @end example @end deftypefn -@deftypefn {Function File} {} pinv (@var{X}, @var{tol}) -Returns the pseudoinverse of @var{X}. Singular values less than +@deftypefn {Function File} {} pinv (@var{x}, @var{tol}) +Returns the pseudoinverse of @var{x}. Singular values less than @var{tol} are ignored. If the second argument is omitted, it is assumed that @example -tol = max (size (X)) * sigma_max (X) * eps, +tol = max (size (@var{x})) * sigma_max (@var{x}) * eps, @end example @noindent -where @code{sigma_max (@var{X})} is the maximal singular value of @var{X}. +where @code{sigma_max (@var{x})} is the maximal singular value of @var{x}. @end deftypefn @deftypefn {Function File} {} rank (@var{a}, @var{tol}) @@ -180,22 +198,23 @@ argument is omitted, it is taken to be @example -tol = max (size (a)) * sigma (1) * eps; +tol = max (size (@var{a})) * sigma (1) * eps; @end example @noindent where @code{eps} is machine precision and @code{sigma} is the largest -singular value of @code{a}. +singular value of @var{a}. @end deftypefn @deftypefn {Function File} {} trace (@var{a}) -Compute the trace of @var{a}, @code{sum (diag (a))}. +Compute the trace of @var{a}, @code{sum (diag (@var{a}))}. @end deftypefn @node Matrix Factorizations, Functions of a Matrix, Basic Matrix Functions, Linear Algebra @section Matrix Factorizations @deftypefn {Loadable Function} {} chol (@var{a}) +@cindex Cholesky factorization Compute the Cholesky factor, @var{r}, of the symmetric positive definite matrix @var{a}, where @iftex @@ -213,20 +232,33 @@ @deftypefn {Loadable Function} {@var{h} =} hess (@var{a}) @deftypefnx {Loadable Function} {[@var{p}, @var{h}] =} hess (@var{a}) +@cindex Hessenberg decomposition Compute the Hessenberg decomposition of the matrix @var{a}. The Hessenberg decomposition is usually used as the first step in an eigenvalue computation, but has other applications as well (see Golub, Nash, and Van Loan, IEEE Transactions on Automatic Control, 1979. The -Hessenberg decomposition is @code{p * h * p' = a} where @code{p} is a -square unitary matrix (@code{p' * p = I}, using complex-conjugate -transposition) and @code{h} is upper Hessenberg -(@code{i >= j+1 => h (i, j) = 0}). +Hessenberg decomposition is +@iftex +@tex +$$ +A = PHP^T +$$ +where $P$ is a square unitary matrix ($P^HP = I$), and $H$ +is upper Hessenberg ($H_{i,j} = 0, \forall i \ge j+1$). +@end tex +@end iftex +@ifinfo +@code{p * h * p' = a} where @code{p} is a square unitary matrix +(@code{p' * p = I}, using complex-conjugate transposition) and @code{h} +is upper Hessenberg (@code{i >= j+1 => h (i, j) = 0}). +@end ifinfo @end deftypefn @deftypefn {Loadable Function} {[@var{l}, @var{u}, @var{p}] =} lu (@var{a}) +@cindex LU decomposition Compute the LU decomposition of @var{a}, using subroutines from -LAPACK. The result is returned in a permuted form, according to +@sc{Lapack}. The result is returned in a permuted form, according to the optional return value @var{p}. For example, given the matrix @code{a = [1, 2; 3, 4]}, @@ -256,7 +288,8 @@ @end deftypefn @deftypefn {Loadable Function} {[@var{q}, @var{r}] =} qr (@var{a}) -Compute the QR factorization of @var{a}, using standard LAPACK +@cindex QR factorization +Compute the QR factorization of @var{a}, using standard @sc{Lapack} subroutines. For example, given the matrix @code{a = [1, 2; 3, 4]}, @example @@ -342,6 +375,7 @@ @deftypefn {Loadable Function} {@var{s}} schur (@var{a}) @deftypefnx {Loadable Function} {[@var{u}, @var{s}] =} schur (@var{a}, @var{opt}) +@cindex Schur decomposition The Schur decomposition is used to compute eigenvalues of a square matrix, and has applications in the solution of algebraic Riccati equations in control (see @code{are} and @code{dare}). @@ -547,6 +581,7 @@ @deftypefn {Loadable Function} {@var{s} =} svd (@var{a}) @deftypefnx {Loadable Function} {[@var{u}, @var{s}, @var{v}] =} svd (@var{a}) +@cindex singular value decomposition Compute the singular value decomposition of @var{a} @iftex @tex @@ -729,30 +764,63 @@ @example x = [a(i, j) b] @end example + +For example, + +@example +@group +kron (1:4, ones (3, 1)) + + @result{} 1 2 3 4 + 1 2 3 4 + 1 2 3 4 +@end group +@end example @end deftypefn -@deftypefn {Function File} {} qzhess (@var{a}, @var{b}) +@deftypefn {Function File} {[@var{aa}, @var{bb}, @var{q}, @var{z}] =} qzhess (@var{a}, @var{b}) Compute the Hessenberg-triangular decomposition of the matrix pencil -@code{(a, b)}. This function returns @code{aa = q * a * z}, -@code{bb = q * b * z}, @code{q}, @code{z} orthogonal. For example, +@code{(@var{a}, @var{b})}, returning +@code{@var{aa} = @var{q} * @var{a} * @var{z}}, +@code{@var{bb} = @var{q} * @var{b} * @var{z}}, with @var{q} and @var{z} +orthogonal. For example, @example -[aa, bb, q, z] = qzhess (a, b) +@group +[aa, bb, q, z] = qzhess ([1, 2; 3, 4], [5, 6; 7, 8]) + + @result{} aa = [ -3.02244, -4.41741; 0.92998, 0.69749 ] + + @result{} bb = [ -8.60233, -9.99730; 0.00000, -0.23250 ] + + @result{} q = [ -0.58124, -0.81373; -0.81373, 0.58124 ] + + @result{} z = [ 1, 0; 0, 1 ] +@end group @end example The Hessenberg-triangular decomposition is the first step in -Moler and Stewart's QZ decomposition algorithm. (The QZ decomposition -will be included in a later release of Octave.) +Moler and Stewart's QZ decomposition algorithm. Algorithm taken from Golub and Van Loan, @cite{Matrix Computations, 2nd edition}. @end deftypefn @deftypefn {Loadable Function} {} qzval (@var{a}, @var{b}) -Compute generalized eigenvalues. +Compute generalized eigenvalues of the matrix pencil +@iftex +@tex +$a - \lambda b$. +@end tex +@end iftex +@ifinfo +@code{@var{a} - lambda @var{b}}. +@end ifinfo + +The arguments @var{a} and @var{b} must be real matrices. @end deftypefn -@deftypefn {Loadable Function} {} syl (@var{a}, @var{b}, @var{c}) +@deftypefn {Loadable Function} {@var{x} =} syl (@var{a}, @var{b}, @var{c}) Solve the Sylvester equation @iftex @tex @@ -766,7 +834,13 @@ @example A X + X B + C = 0 @end example +@end ifinfo +using standard @sc{Lapack} subroutines. For example, -@end ifinfo -using standard LAPACK subroutines. +@example +@group +syl ([1, 2; 3, 4], [5, 6; 7, 8], [9, 10; 11, 12]) + @result{} [ -0.50000, -0.66667; -0.66667, -0.50000 ] +@end group +@end example @end deftypefn diff --git a/doc/interpreter/matrix.texi b/doc/interpreter/matrix.texi --- a/doc/interpreter/matrix.texi +++ b/doc/interpreter/matrix.texi @@ -77,12 +77,12 @@ @code{while} statements) Octave treats the test as if you had typed @code{all (all (condition))}. -@deftypefn {Function File} {[@var{errorcode}, @var{y_1}, ...] =} common_size (@var{x_1}, ...) +@deftypefn {Function File} {[@var{err}, @var{y1}, ...] =} common_size (@var{x1}, ...) Determine if all input arguments are either scalar or of common -size. If so, errorcode is zero, and @var{y_i} is a matrix of the -common size with all entries equal to @var{x_i} if this is a scalar or -@var{x_i} otherwise. If the inputs cannot be brought to a common size, -errorcode is 1, and @var{y_i} is @var{x_i}. For example, +size. If so, @var{err} is zero, and @var{yi} is a matrix of the +common size with all entries equal to @var{xi} if this is a scalar or +@var{xi} otherwise. If the inputs cannot be brought to a common size, +errorcode is 1, and @var{yi} is @var{xi}. For example, @example @group @@ -411,18 +411,12 @@ @deftypefn {Function File} {} vec (@var{x}) For a matrix @var{x}, returns the vector obtained by stacking the columns of @var{x} one above the other. - -See Magnus and Neudecker (1988), Matrix differential calculus with -applications in statistics and econometrics. @end deftypefn @deftypefn {Function File} {} vech (@var{x}) For a square matrix @var{x}, returns the vector obtained from @var{x} by eliminating all supradiagonal elements and stacking the result one column above the other. - -See Magnus and Neudecker (1988), Matrix differential calculus with -applications in statistics and econometrics. @end deftypefn @node Special Utility Matrices, Famous Matrices, Rearranging Matrices, Matrix Manipulation @@ -435,7 +429,7 @@ supply two scalar arguments, @code{eye} takes them to be the number of rows and columns. If given a vector with two elements, @code{eye} uses the values of the elements as the number of rows and columns, -respecively. For example, +respectively. For example, @example @group @@ -492,7 +486,7 @@ form @example -randn ("seed", @var{x}) +rand ("seed", @var{x}) @end example @noindent @@ -569,10 +563,11 @@ If it is invoked without arguments, @code{rand} and @code{randn} return a single element of a random sequence. -The @code{rand} and @code{randn} functions use Fortran code from RANLIB, -a library of fortran routines for random number generation, compiled by -Barry W. Brown and James Lovato of the Department of Biomathematics at -The University of Texas, M.D. Anderson Cancer Center, Houston, TX 77030. +The @code{rand} and @code{randn} functions use Fortran code from +@sc{Ranlib}, a library of fortran routines for random number generation, +compiled by Barry W. Brown and James Lovato of the Department of +Biomathematics at The University of Texas, M.D. Anderson Cancer Center, +Houston, TX 77030. @deftypefn {Built-in Function} {} diag (@var{v}, @var{k}) Returns a diagonal matrix with vector @var{v} on diagonal @var{k}. The @@ -612,11 +607,12 @@ @xref{Ranges}. @deftypefn {Function File} {} linspace (@var{base}, @var{limit}, @var{n}) -creates a row vector with @var{n} (@var{n} greater than 1) linearly -spaced elements between @var{base} and @var{limit}. The @var{base} and -@var{limit} are always included in the range. If @var{base} is greater -than @var{limit}, the elements are stored in decreasing order. If the -number of points is not specified, a value of 100 is used. +Return a row vector with @var{n} linearly spaced elements between +@var{base} and @var{limit}. The number of elements, @var{n}, must be +greater than 1. The @var{base} and @var{limit} are always included in +the range. If @var{base} is greater than @var{limit}, the elements are +stored in decreasing order. If the number of points is not specified, a +value of 100 is used. The @code{linspace} function always returns a row vector, regardless of the value of @code{prefer_column_vectors}. @@ -684,7 +680,15 @@ The following functions return famous matrix forms. @deftypefn {Function File} {} hadamard (@var{k}) -Return the Hadamard matrix of order n = 2^k. +Return the Hadamard matrix of order +@iftex +@tex +$n = 2^k$. +@end tex +@end iftex +@ifinfo +n = 2^k. +@end ifinfo @end deftypefn @deftypefn {Function File} {} hankel (@var{c}, @var{r}) diff --git a/doc/interpreter/nonlin.texi b/doc/interpreter/nonlin.texi --- a/doc/interpreter/nonlin.texi +++ b/doc/interpreter/nonlin.texi @@ -23,7 +23,7 @@ @end ifinfo @noindent -using the function @code{fsolve}, which is based on the MINPACK +using the function @code{fsolve}, which is based on the @sc{Minpack} subroutine @code{hybrd}. @deftypefn {Loadable Function} {[@var{x}, @var{info}] =} fsolve (@var{fcn}, @var{x0}) @@ -63,10 +63,8 @@ @example function y = f (x) - y(1) = -2*x(1)^2 + 3*x(1)*x(2) + 4*sin(x(2)) - 6; y(2) = 3*x(1)^2 - 2*x(1)*x(2)^2 + 3*cos(x(1)) + 4; - endfunction @end example @@ -96,12 +94,10 @@ corresponding to the numeric error codes. For example, @example +@group perror ("fsolve", 1) + @print{} solution converged to requested tolerance +@end group @end example -@noindent -prints -@example -solution converged to requested tolerance -@end example diff --git a/doc/interpreter/numbers.texi b/doc/interpreter/numbers.texi --- a/doc/interpreter/numbers.texi +++ b/doc/interpreter/numbers.texi @@ -90,13 +90,13 @@ @noindent results in the matrix - @iftex @tex $$ a = \left[ \matrix{ 1 & 2 \cr 3 & 4 } \right] $$ @end tex @end iftex @ifinfo + @example @group @@ -185,7 +185,7 @@ @noindent the @samp{-} is treated as a unary operator and the result is the -vector @code{[ 1 -1 ]}. +vector @code{[ 1, -1 ]}. Given @code{a = 1}, the expression @@ -195,7 +195,7 @@ @noindent results in the single quote character @samp{'} being treated as a -transpose operator and the result is the vector @code{[ 1 1 ]}, but the +transpose operator and the result is the vector @code{[ 1, 1 ]}, but the expression @example @@ -225,7 +225,7 @@ @defvr {Built-in Variable} whitespace_in_literal_matrix This variable allows some control over how Octave decides to convert spaces to commas and semicolons in matrix expressions like -@samp{[m (1)]} or +@code{[m (1)]} or @example [ 1, 2, @@ -234,8 +234,8 @@ If the value of @code{whitespace_in_literal_matrix} is @code{"ignore"}, Octave will never insert a comma or a semicolon in a literal matrix -list. For example, the expression @samp{[1 2]} will result in an error -instead of being treated the same as @samp{[1, 2]}, and the expression +list. For example, the expression @code{[1 2]} will result in an error +instead of being treated the same as @code{[1, 2]}, and the expression @example [ 1, 2, @@ -243,7 +243,7 @@ @end example @noindent -will result in the vector [1 2 3 4] instead of a matrix. +will result in the vector @code{[ 1, 2, 3, 4 ]} instead of a matrix. If the value of @code{whitespace_in_literal_matrix} is @code{"traditional"}, Octave will convert spaces to a comma between identifiers and @samp{(}. For @@ -369,7 +369,24 @@ Exercise}, SIGNUM, Volume 25, pages 2--6, 1990 and C. N. Nett and W. M. Haddad, in @cite{A System-Theoretic Appropriate Realization of the Empty Matrix Concept}, IEEE Transactions on Automatic Control, Volume 38, -Number 5, May 1993. Briefly, given a scalar @code{s}, and an @var{m} by +Number 5, May 1993. +@iftex +@tex +Briefly, given a scalar $s$, an $m\times n$ matrix $M_{m\times n}$, +and an $m\times n$ empty matrix $[\,]_{m\times n}$ (with either one or +both dimensions equal to zero), the following are true: +$$ +\eqalign{% +s \cdot [\,]_{m\times n} = [\,]_{m\times n} \cdot s &= [\,]_{m\times n}\cr +[\,]_{m\times n} + [\,]_{m\times n} &= [\,]_{m\times n}\cr +[\,]_{0\times m} \cdot M_{m\times n} &= [\,]_{0\times n}\cr +M_{m\times n} \cdot [\,]_{n\times 0} &= [\,]_{m\times 0}\cr +[\,]_{m\times 0} \cdot [\,]_{0\times n} &= 0_{m\times n}} +$$ +@end tex +@end iftex +@ifinfo +Briefly, given a scalar @var{s}, an @var{m} by @var{n} matrix @code{M(mxn)}, and an @var{m} by @var{n} empty matrix @code{[](mxn)} (with either one or both dimensions equal to zero), the following are true: @@ -387,21 +404,11 @@ [](mx0) * [](0xn) = 0(mxn) @end group @end example +@end ifinfo By default, dimensions of the empty matrix are printed along with the -empty matrix symbol, @samp{[]}. For example: - -@example -@group -octave:13> zeros (3, 0) -ans = - -[](3x0) -@end group -@end example - -The built-in variable @code{print_empty_dimensions} controls this -behavior. +empty matrix symbol, @samp{[]}. The built-in variable +@code{print_empty_dimensions} controls this behavior. @defvr {Built-in Variable} print_empty_dimensions If the value of @code{print_empty_dimensions} is nonzero, the @@ -416,9 +423,7 @@ will print @example -ans = - -[](3x0) +ans = [](3x0) @end example @end defvr @@ -443,7 +448,7 @@ @end example @noindent -and the variable @samp{a} will be assigned the value @samp{[ 1 3 5 ]}. +and the variable @code{a} will be assigned the value @code{[ 1, 3, 5 ]}. The default value is @code{"warn"}. @end defvr @@ -479,14 +484,14 @@ @end example @noindent -defines the set of values @samp{[ 1 2 3 4 5 ]}, and the range +defines the set of values @samp{[ 1, 2, 3, 4, 5 ]}, and the range @example 1 : 3 : 5 @end example @noindent -defines the set of values @samp{[ 1 4 ]}. +defines the set of values @samp{[ 1, 4 ]}. Although a range constant specifies a row vector, Octave does @emph{not} convert range constants to vectors unless it is necessary to do so. diff --git a/doc/interpreter/octave.texi b/doc/interpreter/octave.texi --- a/doc/interpreter/octave.texi +++ b/doc/interpreter/octave.texi @@ -69,7 +69,7 @@ @title Octave @subtitle A high-level interactive language for numerical computations @subtitle Edition 3 for Octave version @value{VERSION} -@subtitle October 1996 +@subtitle February 1997 @author John W. Eaton @page @vskip 0pt plus 1filll @@ -151,7 +151,7 @@ Preface -* Acknowlegements:: +* Acknowledgements:: * How You Can Contribute to Octave:: * Distribution:: @@ -320,9 +320,10 @@ Plotting * Two-Dimensional Plotting:: +* Specialized Two-Dimensional Plots:: * Three-Dimensional Plotting:: +* Plot Annotations:: * Multiple Plots on One Page:: -* Miscellaneous Plotting Functions:: Matrix Manipulation diff --git a/doc/interpreter/optim.texi b/doc/interpreter/optim.texi --- a/doc/interpreter/optim.texi +++ b/doc/interpreter/optim.texi @@ -23,9 +23,10 @@ @section Quadratic Programming @deftypefn {Loadable Function} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} qpsol (@var{x}, @var{H}, @var{c}, @var{lb}, @var{ub}, @var{lb}, @var{A}, @var{ub}) -Solve quadratic programs using Gill and Murray's QPSOL. Because QPSOL -is not freely redistributable, this function is only available if you -have obtained your own copy of QPSOL. @xref{Installation}. +Solve quadratic programs using Gill and Murray's @sc{Qpsol}. Because +@sc{Qpsol} is not freely redistributable, this function is only +available if you have obtained your own copy of @sc{Qpsol}. +@xref{Installation}. @end deftypefn @deftypefn {Loadable Function} {} qpsol_options (@var{opt}, @var{val}) @@ -55,9 +56,10 @@ @end ignore @deftypefn {Loadable Function} {[@var{x}, @var{obj}, @var{info}, @var{lambda}] =} npsol (@var{x}, @var{phi}, @var{lb}, @var{ub}, @var{lb}, @var{A}, @var{ub}, @var{lb}, @var{g}, @var{ub}) -Solve nonlinear programs using Gill and Murray's NPSOL. Because NPSOL -is not freely redistributable, this function is only available if you -have obtained your own copy of NPSOL. @xref{Installation}. +Solve nonlinear programs using Gill and Murray's @sc{Npsol}. Because +@sc{Npsol} is not freely redistributable, this function is only +available if you have obtained your own copy of @sc{Npsol}. +@xref{Installation}. The second argument is a string containing the name of the objective function to call. The objective function must be of the form @@ -83,7 +85,6 @@ @deftypefn {Function File} {[@var{beta}, @var{v}, @var{r}] =} gls (@var{y}, @var{x}, @var{o}) Generalized least squares estimation for the multivariate model - @iftex @tex $y = x b + e$ @@ -130,7 +131,6 @@ @deftypefn {Function File} {[@var{beta}, @var{sigma}, @var{r}] =} ols (@var{y}, @var{x}) Ordinary least squares estimation for the multivariate model - @iftex @tex $y = x b + e$ @@ -151,11 +151,9 @@ @end tex @end iftex @ifinfo -@example @var{y} is a @var{t} by @var{p} matrix, @var{X} is a @var{t} by @var{k} matrix, @var{B} is a @var{k} by @var{p} matrix, and @var{e} is a @var{t} by @var{p} matrix. -@end example @end ifinfo Each row of @var{y} and @var{x} is an observation and each column a diff --git a/doc/interpreter/plot.texi b/doc/interpreter/plot.texi --- a/doc/interpreter/plot.texi +++ b/doc/interpreter/plot.texi @@ -16,12 +16,13 @@ @menu * Two-Dimensional Plotting:: +* Specialized Two-Dimensional Plots:: * Three-Dimensional Plotting:: +* Plot Annotations:: * Multiple Plots on One Page:: -* Miscellaneous Plotting Functions:: @end menu -@node Two-Dimensional Plotting, Three-Dimensional Plotting, Plotting, Plotting +@node Two-Dimensional Plotting, Specialized Two-Dimensional Plots, Plotting, Plotting @section Two-Dimensional Plotting @deffn {Command} gplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} @@ -88,9 +89,9 @@ @noindent will plot two lines. The first line is generated by the command @code{data with lines}, and is a graph of the sine function over the -range -10 to 10. The data is taken from the first two columns of the -matrix because columns to plot were not specified with the @var{using} -qualifier. +range @minus{}10 to 10. The data is taken from the first two columns of +the matrix because columns to plot were not specified with the +@var{using} qualifier. The clause @code{using 1:3} in the second part of this plot command specifies that the first and third columns of the matrix @code{data} @@ -139,7 +140,16 @@ @end example will change the terminal type for plotting, add a title to the current -plot, add a graph of sin (x) to the plot, and force the new plot to be +plot, add a graph of +@iftex +@tex +$\sin(x)$ +@end tex +@end iftex +@ifinfo +sin (x) +@end ifinfo +to the plot, and force the new plot to be sent to the plot device. This last step is normally required in order to update the plot. This default is reasonable for slow terminals or hardcopy output devices because even when you are adding additional @@ -178,7 +188,7 @@ combinations of arguments are possible. The simplest form is @example -plot (y) +plot (@var{y}) @end example @noindent @@ -189,7 +199,7 @@ If more than one argument is given, they are interpreted as @example -plot (x [, y] [, fmt] ...) +plot (@var{x}, @var{y}, @var{fmt} ...) @end example @noindent @@ -257,18 +267,18 @@ @item #~ Set boxerrorbars plot style. -@item n +@item @var{n} Interpreted as the plot color if @var{n} is an integer in the range 1 to 6. -@item nm +@item @var{nm} If @var{nm} is a two digit integer and @var{m} is an integer in the range 1 to 6, @var{m} is interpreted as the point style. This is only valid in combination with the @code{@@} or @code{-@@} specifiers. -@item c -If @var{c} is one of @var{"r"}, @var{"g"}, @var{"b"}, @var{"m"}, -@var{"c"}, or @var{"w"}, it is interpreted as the plot color (red, +@item @var{c} +If @var{c} is one of @code{"r"}, @code{"g"}, @code{"b"}, @code{"m"}, +@code{"c"}, or @code{"w"}, it is interpreted as the plot color (red, green, blue, magenta, cyan, or white). @item + @@ -298,16 +308,16 @@ plot (x, y, "@@12", x, y2, x, y3, "4", x, y4, "+") @end example -This command will plot @var{y} with points of type 2 (displayed as -@samp{+}) and color 1 (red), @var{y2} with lines, @var{y3} with lines of -color 4 (magenta) and @var{y4} with points displayed as @samp{+}. +This command will plot @code{y} with points of type 2 (displayed as +@samp{+}) and color 1 (red), @code{y2} with lines, @code{y3} with lines of +color 4 (magenta) and @code{y4} with points displayed as @samp{+}. @example plot (b, "*") @end example -This command will plot the data in @var{b} will be plotted with points -displayed as @samp{*}. +This command will plot the data in the variable @code{b} will be plotted +with points displayed as @samp{*}. @end deftypefn @deftypefn {Function File} {} hold @var{args} @@ -327,16 +337,118 @@ @end deftypefn @deftypefn {Function File} {} ishold -Returns 1 if the next line will be added to the current plot, or 0 if +Return 1 if the next line will be added to the current plot, or 0 if the plot device will be cleared before drawing the next line. @end deftypefn +@deftypefn {Function File} {} clearplot +@deftypefnx {Function File} {} clg +Clear the plot window and any titles or axis labels. The name +@code{clg} is aliased to @code{clearplot} for compatibility with @sc{Matlab}. + +The commands @kbd{gplot clear}, @kbd{gsplot clear}, and @kbd{replot +clear} are equivalent to @code{clearplot}. (Previously, commands like +@kbd{gplot clear} would evaluate @code{clear} as an ordinary expression +and clear all the visible variables.) +@end deftypefn + +@deftypefn {Function File} {} closeplot +Close stream to the @code{gnuplot} subprocess. If you are using X11, +this will close the plot window. +@end deftypefn + +@deftypefn {Function File} {} purge_tmp_files +Delete the temporary files created by the plotting commands. + +Octave creates temporary data files for @code{gnuplot} and then sends +commands to @code{gnuplot} through a pipe. Octave will delete the +temporary files on exit, but if you are doing a lot of plotting you may +want to clean up in the middle of a session. + +A future version of Octave will eliminate the need to use temporary +files to hold the plot data. +@end deftypefn + +@deftypefn {Function File} {} axis (@var{limits}) +Sets the axis limits for plots. + +The argument @var{limits} should be a 2, 4, or 6 element vector. The +first and second elements specify the lower and upper limits for the x +axis. The third and fourth specify the limits for the y axis, and the +fifth and sixth specify the limits for the z axis. + +With no arguments, @code{axis} turns autoscaling on. + +If your plot is already drawn, then you need to use @code{replot} before +the new axis limits will take effect. You can get this to happen +automatically by setting the built-in variable @code{automatic_replot} +to a nonzero value. +@end deftypefn + +@node Specialized Two-Dimensional Plots, Three-Dimensional Plotting, Two-Dimensional Plotting, Plotting +@section Specialized Two-Dimensional Plots + +@deftypefn {Function File} {} bar (@var{x}, @var{y}) +Given two vectors of x-y data, @code{bar} produces a bar graph. + +If only one argument is given, it is taken as a vector of y-values +and the x coordinates are taken to be the indices of the elements. + +If two output arguments are specified, the data are generated but +not plotted. For example, + +@example +bar (x, y); +@end example + +@noindent +and + +@example +[xb, yb] = bar (x, y); +plot (xb, yb); +@end example + +@noindent +are equivalent. +@end deftypefn + +@deftypefn {Function File} {} contour (@var{z}, @var{n}, @var{x}, @var{y}) +Make a contour plot of the three-dimensional surface described by +@var{z}. Someone needs to improve @code{gnuplot}'s contour routines +before this will be very useful. +@end deftypefn + +@deftypefn {Function File} {} hist (@var{y}, @var{x}) +Produce histogram counts or plots. + +With one vector input argument, plot a histogram of the values with +10 bins. The range of the histogram bins is determined by the range +of the data. + +Given a second scalar argument, use that as the number of bins. + +Given a second vector argument, use that as the centers of the bins, +with the width of the bins determined from the adjacent values in +the vector. + +Extreme values are lumped in the first and last bins. + +With two output arguments, produce the values @var{nn} and @var{xx} such +that @code{bar (@var{xx}, @var{nn})} will plot the histogram. +@end deftypefn + @deftypefn {Function File} {} loglog (@var{args}) Make a two-dimensional plot using log scales for both axes. See the description of @code{plot} above for a description of the arguments that @code{loglog} will accept. @end deftypefn +@deftypefn {Function File} {} polar (@var{theta}, @var{rho}) +Make a two-dimensional plot given polar the coordinates @var{theta} and +@var{rho}. +@end deftypefn + @deftypefn {Function File} {} semilogx (@var{args}) Make a two-dimensional plot using a log scale for the @var{x} axis. See the description of @code{plot} above for a description of the arguments @@ -349,18 +461,32 @@ that @code{semilogy} will accept. @end deftypefn -@deftypefn {Function File} {} contour (@var{z}, @var{n}, @var{x}, @var{y}) -Make a contour plot of the three-dimensional surface described by -@var{z}. Someone needs to improve @code{gnuplot}'s contour routines -before this will be very useful. +@deftypefn {Function File} {} stairs (@var{x}, @var{y}) +Given two vectors of x-y data, bar produces a `stairstep' plot. + +If only one argument is given, it is taken as a vector of y-values +and the x coordinates are taken to be the indices of the elements. + +If two output arguments are specified, the data are generated but +not plotted. For example, + +@example +stairs (x, y); +@end example + +@noindent +and + +@example +[xs, ys] = stairs (x, y); +plot (xs, ys); +@end example + +@noindent +are equivalent. @end deftypefn -@deftypefn {Function File} {} polar (@var{theta}, @var{rho}) -Make a two-dimensional plot given polar the coordinates @var{theta} and -@var{rho}. -@end deftypefn - -@node Three-Dimensional Plotting, Multiple Plots on One Page, Two-Dimensional Plotting, Plotting +@node Three-Dimensional Plotting, Plot Annotations, Specialized Two-Dimensional Plots, Plotting @section Three-Dimensional Plotting @deffn {Command} gsplot @var{ranges} @var{expression} @var{using} @var{title} @var{style} @@ -410,7 +536,7 @@ @kbd{gset parametric}, then @code{gsplot} takes the columns of the matrix three at a time as the x, y and z values that define a line in three space. Any extra columns are ignored, and the x and y values are -expected to be sorted. For example, with @kbd{parametric} set, it +expected to be sorted. For example, with @code{parametric} set, it makes sense to plot a matrix like @iftex @tex @@ -478,7 +604,27 @@ configure got it wrong, or if you upgrade your gnuplot installation. @end defvr -@node Multiple Plots on One Page, Miscellaneous Plotting Functions, Three-Dimensional Plotting, Plotting +@node Plot Annotations, Multiple Plots on One Page, Three-Dimensional Plotting, Plotting +@section Plot Annotations + +@deftypefn {Function File} {} grid +For two-dimensional plotting, force the display of a grid on the plot. +@end deftypefn + +@deftypefn {Function File} {} title (@var{string}) +Specify a title for the plot. If you already have a plot displayed, use +the command @code{replot} to redisplay it with the new title. +@end deftypefn + +@deftypefn {Function File} {} xlabel (@var{string}) +@deftypefnx {Function File} {} ylabel (@var{string}) +@deftypefnx {Function File} {} zlabel (@var{string}) +Specify x, y, and z axis labels for the plot. If you already have a plot +displayed, use the command @code{replot} to redisplay it with the new +labels. +@end deftypefn + +@node Multiple Plots on One Page, , Plot Annotations, Plotting @section Multiple Plots on One Page The following functions all require a version of @code{gnuplot} that @@ -564,7 +710,6 @@ For example, a plot with 4 by 2 grid will have plot indices running as follows: - @iftex @tex \vskip 10pt @@ -593,148 +738,10 @@ Sets the subwindow position in multiplot mode for the next plot. The multiplot mode has to be previously initialized using the @code{multiplot} function, otherwise this command just becomes an alias -to @var{multiplot} +to @code{multiplot} @end deftypefn @deftypefn {Function File} {} top_title (@var{string}) @deftypefnx {Function File} {} bottom_title (@var{string}) Makes a title with text @var{string} at the top (bottom) of the plot. @end deftypefn - -@node Miscellaneous Plotting Functions, , Multiple Plots on One Page, Plotting -@section Miscellaneous Plotting Functions - -@deftypefn {Function File} {} bar (@var{x}, @var{y}) -Given two vectors of x-y data, @code{bar} produces a bar graph. - -If only one argument is given, it is taken as a vector of y-values -and the x coordinates are taken to be the indices of the elements. - -If two output arguments are specified, the data are generated but -not plotted. For example, - -@example -bar (x, y); -@end example - -@noindent -and - -@example -[xb, yb] = bar (x, y); -plot (xb, yb); -@end example - -@noindent -are equivalent. -@end deftypefn - -@deftypefn {Function File} {} grid -For two-dimensional plotting, force the display of a grid on the plot. -@end deftypefn - -@deftypefn {Function File} {} stairs (@var{x}, @var{y}) -Given two vectors of x-y data, bar produces a `stairstep' plot. - -If only one argument is given, it is taken as a vector of y-values -and the x coordinates are taken to be the indices of the elements. - -If two output arguments are specified, the data are generated but -not plotted. For example, - -@example -stairs (x, y); -@end example - -@noindent -and - -@example -[xs, ys] = stairs (x, y); -plot (xs, ys); -@end example - -@noindent -are equivalent. -@end deftypefn - -@deftypefn {Function File} {} title (@var{string}) -Specify a title for the plot. If you already have a plot displayed, use -the command @code{replot} to redisplay it with the new title. -@end deftypefn - -@deftypefn {Function File} {} xlabel (@var{string}) -@deftypefnx {Function File} {} ylabel (@var{string}) -@deftypefnx {Function File} {} zlabel (@var{string}) -Specify x, y, and z axis labels for the plot. If you already have a plot -displayed, use the command @code{replot} to redisplay it with the new -labels. -@end deftypefn - -@deftypefn {Function File} {} sombrero (@var{n}) -Display a classic three-dimensional mesh plot. The parameter @var{n} -allows you to increase the resolution. -@end deftypefn - -@deftypefn {Function File} {} clearplot -@deftypefnx {Function File} {} clg -Clear the plot window and any titles or axis labels. The name -@code{clg} is aliased to @code{clearplot} for compatibility with @sc{Matlab}. - -The commands @kbd{gplot clear}, @kbd{gsplot clear}, and @kbd{replot -clear} are equivalent to @code{clearplot}. (Previously, commands like -@kbd{gplot clear} would evaluate @code{clear} as an ordinary expression -and clear all the visible variables.) -@end deftypefn - -@deftypefn {Function File} {} closeplot -Close stream to the @code{gnuplot} subprocess. If you are using X11, -this will close the plot window. -@end deftypefn - -@deftypefn {Function File} {} purge_tmp_files -Delete the temporary files created by the plotting commands. - -Octave creates temporary data files for @code{gnuplot} and then sends -commands to @code{gnuplot} through a pipe. Octave will delete the -temporary files on exit, but if you are doing a lot of plotting you may -want to clean up in the middle of a session. - -A future version of Octave will eliminate the need to use temporary -files to hold the plot data. -@end deftypefn - -@deftypefn {Function File} {} axis (@var{limits}) -Sets the axis limits for plots. - -The argument @var{limits} should be a 2, 4, or 6 element vector. The -first and second elements specify the lower and upper limits for the x -axis. The third and fourth specify the limits for the y axis, and the -fifth and sixth specify the limits for the z axis. - -With no arguments, @code{axis} turns autoscaling on. - -If your plot is already drawn, then you need to use @code{replot} before -the new axis limits will take effect. You can get this to happen -automatically by setting the built-in variable @code{automatic_replot} -to a nonzero value. -@end deftypefn - -@deftypefn {Function File} {} hist (@var{y}, @var{x}) -Produce histogram counts or plots. - -With one vector input argument, plot a histogram of the values with -10 bins. The range of the histogram bins is determined by the range -of the data. - -Given a second scalar argument, use that as the number of bins. - -Given a second vector argument, use that as the centers of the bins, -with the width of the bins determined from the adjacent values in -the vector. - -Extreme values are lumped in the first and last bins. - -With two output arguments, produce the values @var{nn} and @var{xx} such -that @code{bar (@var{xx}, @var{nn})} will plot the histogram. -@end deftypefn diff --git a/doc/interpreter/poly.texi b/doc/interpreter/poly.texi --- a/doc/interpreter/poly.texi +++ b/doc/interpreter/poly.texi @@ -20,24 +20,17 @@ @ifinfo @var{N+1} @end ifinfo - corresponds to the following + corresponds to the following polynomial of order @iftex @tex - $N^{th}$ -@end tex -@end iftex -@ifinfo - @var{N}-th -@end ifinfo - order polynomial -@iftex -@tex + $N$ $$ p (x) = c_1 x^N + ... + c_N x + c_{N+1}. $$ @end tex @end iftex @ifinfo + @var{N} @example p(x) = @var{c}(1) x^@var{N} + ... + @var{c}(@var{N}) x + @var{c}(@var{N}+1). @@ -164,6 +157,7 @@ If @var{b} and @var{a} are vectors of polynomial coefficients, then residue calculates the partial fraction expansion corresponding to the ratio of the two polynomials. +@cindex partial fraction expansion The function @code{residue} returns @var{r}, @var{p}, @var{k}, and @var{e}, where the vector @var{r} contains the residue terms, @var{p} diff --git a/doc/interpreter/preface.texi b/doc/interpreter/preface.texi --- a/doc/interpreter/preface.texi +++ b/doc/interpreter/preface.texi @@ -48,13 +48,13 @@ it, and by reporting any problems you may have. @menu -* Acknowlegements:: +* Acknowledgements:: * How You Can Contribute to Octave:: * Distribution:: @end menu -@node Acknowlegements, How You Can Contribute to Octave, Preface, Preface -@unnumberedsec Acknowlegements +@node Acknowledgements, How You Can Contribute to Octave, Preface, Preface +@unnumberedsec Acknowledgements @cindex acknowledgements Many people have already contributed to Octave's development. In @@ -66,95 +66,96 @@ @itemize @bullet @item -Thomas Baier (baier@@ci.tuwien.ac.at) wrote the original versions of -@code{popen}, @code{pclose}, @code{execute}, @code{sync_system}, and +Thomas Baier @email{baier@@ci.tuwien.ac.at} wrote the original versions +of @code{popen}, @code{pclose}, @code{execute}, @code{sync_system}, and @code{async_system}. @item -Karl Berry (karl@@cs.umb.edu) wrote the @code{kpathsea} library that -allows Octave to recursively search directory paths for function and -script files. +Karl Berry @email{karl@@cs.umb.edu} wrote the @code{kpathsea} library +that allows Octave to recursively search directory paths for function +and script files. @item -Georg Beyerle (gbeyerle@@awi-potsdam.de) contributed code to save values -in @sc{Matlab}'s @file{.mat}-file format, and has provided many useful bug -reports and suggestions. +Georg Beyerle @email{gbeyerle@@awi-potsdam.de} contributed code to save +values in @sc{Matlab}'s @file{.mat}-file format, and has provided many +useful bug reports and suggestions. @item -John Campbell (jcc@@bevo.che.wisc.edu) wrote most of the file and +John Campbell @email{jcc@@bevo.che.wisc.edu} wrote most of the file and C-style input and output functions. @item -Brian Fox (bfox@@gnu.ai.mit.edu) wrote the @code{readline} library used -for command history editing, and the portion of this manual that +Brian Fox @email{bfox@@gnu.ai.mit.edu} wrote the @code{readline} library +used for command history editing, and the portion of this manual that documents it. @item -Klaus Gebhardt ported -Octave to OS/2 and worked with Michel Juillard -on the port to DOS. +Klaus Gebhardt @email{gebhardt@@crunch.ikp.physik.th-darmstadt.de} +ported Octave to OS/2 and worked with Michel Juillard +@email{juillard@@msh-paris.fr} on the port to DOS. @item -A. Scottedward Hodel (scotte@@eng.auburn.edu) contributed a number +A. Scottedward Hodel @email{A.S.Hodel@@eng.auburn.edu} contributed a number of functions including @code{expm}, @code{qzval}, @code{qzhess}, @code{syl}, @code{lyap}, and @code{balance}. @item -Kurt Hornik (Kurt.Hornik@@ci.tuwien.ac.at) provided the @code{corrcoef}, -@code{cov}, @code{fftconv}, @code{fftfilt}, @code{gcd}, @code{lcd}, -@code{kurtosis}, @code{null}, @code{orth}, @code{poly}, @code{polyfit}, -@code{roots}, and @code{skewness} functions, supplied documentation for -these and numerous other functions, rewrote the Emacs mode for editing -Octave code and provided its documentation, and has helped tremendously -with testing. He has also been a constant source of new ideas for -improving Octave. +Kurt Hornik @email{Kurt.Hornik@@ci.tuwien.ac.at} provided the +@code{corrcoef}, @code{cov}, @code{fftconv}, @code{fftfilt}, @code{gcd}, +@code{lcd}, @code{kurtosis}, @code{null}, @code{orth}, @code{poly}, +@code{polyfit}, @code{roots}, and @code{skewness} functions, supplied +documentation for these and numerous other functions, rewrote the Emacs +mode for editing Octave code and provided its documentation, and has +helped tremendously with testing. He has also been a constant source of +new ideas for improving Octave. @item -Phil Johnson (johnsonp@@nicco.sscnet.ucla.edu) has helped to make Linux -releases available. +Phil Johnson @email{johnsonp@@nicco.sscnet.ucla.edu} has helped to make +Linux releases available. @item -Michel Juillard ported Octave to DOS systems. +Michel Juillard @email{juillard@@msh-paris.fr} ported Octave to DOS +systems. @item -Friedrich Leisch (leisch@@ci.tuwien.ac.at) provided the +Friedrich Leisch @email{leisch@@ci.tuwien.ac.at} provided the @code{mahalanobis} function. @item -Ken Neighbors (wkn@@leland.stanford.edu) has provided many useful bug -reports and comments on @sc{Matlab} compatibility. +Ken Neighbors @email{wkn@@leland.stanford.edu} has provided many useful +bug reports and comments on @sc{Matlab} compatibility. @item -Rick Niles (niles@@axp745.gsfc.nasa.gov) rewrote Octave's plotting +Rick Niles @email{niles@@axp745.gsfc.nasa.gov} 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. +number of lines in a single call. He also continues to track down odd +incompatibilities and bugs. @item -Mark Odegard (meo@@sugarland.unocal.com) provided the initial +Mark Odegard @email{meo@@sugarland.unocal.com} provided the initial implementation of @code{fread}, @code{fwrite}, @code{feof}, and @code{ferror}. @item -Tony Richardson (tony@@guts.biomed.uakron.edu) wrote Octave's image -processing functions as well as most of the original polynomial +Tony Richardson @email{tony@@guts.biomed.uakron.edu} wrote Octave's +image processing functions as well as most of the original polynomial functions. @item -R. Bruce Tenison (Bruce.Tenison@@eng.auburn.edu) wrote the @code{hess} and -@code{schur} functions. +R. Bruce Tenison @email{Bruce.Tenison@@eng.auburn.edu} wrote the +@code{hess} and @code{schur} functions. @item -Teresa Twaroch (twaroch@@ci.tuwien.ac.at) provided the functions +Teresa Twaroch @email{twaroch@@ci.tuwien.ac.at} provided the functions @code{gls} and @code{ols}. @item -Andreas Weingessel (Andreas.Weingessel@@ci.tuwien.ac.at) wrote the +Andreas Weingessel @email{Andreas.Weingessel@@ci.tuwien.ac.at} wrote the audio functions @code{lin2mu}, @code{loadaudio}, @code{mu2lin}, @code{playaudio}, @code{record}, @code{saveaudio}, and @code{setaudio}. @item -Fook Fah Yap (ffy@@eng.cam.ac.uk) provided the @code{fft} and +Fook Fah Yap @email{ffy@@eng.cam.ac.uk} provided the @code{fft} and @code{ifft} functions and valuable bug reports for early versions. @end itemize @@ -200,7 +201,7 @@ This project would not have been possible without the GNU software used in and used to produce Octave. -@node How You Can Contribute to Octave, Distribution, Acknowlegements, Preface +@node How You Can Contribute to Octave, Distribution, Acknowledgements, Preface @unnumberedsec How You Can Contribute to Octave @cindex contributing to Octave @cindex funding Octave development diff --git a/doc/interpreter/quad.texi b/doc/interpreter/quad.texi --- a/doc/interpreter/quad.texi +++ b/doc/interpreter/quad.texi @@ -54,7 +54,6 @@ @end deftypefn Here is an example of using @code{quad} to integrate the function - @iftex @tex $$ @@ -64,6 +63,7 @@ @end tex @end iftex @ifinfo + @example @var{f}(@var{x}) = @var{x} * sin (1/@var{x}) * sqrt (abs (1 - @var{x})) @end example @@ -87,7 +87,8 @@ Note the use of the `dot' forms of the operators. This is not necessary for the call to @code{quad}, but it makes it much easier to generate a -set of points for plotting. +set of points for plotting (because it makes it possible to call the +function with a vector argument to produce a vector result). Then we simply call quad: @@ -106,9 +107,8 @@ @end example Although @code{quad} returns a nonzero value for @var{ier}, the result -is reasonably accurate (to understand what is happening, examine what -happens to the result if you move the lower bound to 0.1, then 0.01, -then 0.001, etc.). +is reasonably accurate (to see why, examine what happens to the result +if you move the lower bound to 0.1, then 0.01, then 0.001, etc.). @node Orthogonal Collocation, , Functions of One Variable, Quadrature @section Orthogonal Collocation @@ -119,3 +119,46 @@ M. L. Michelsen, @cite{Solution of Differential Equation Models by Polynomial Approximation}. @end deftypefn + +Here is an example of using @code{colloc} to generate weight matrices +for solving the second order differential equation +@iftex +@tex +$u^\prime - \alpha u^{\prime\prime} = 0$ with the boundary conditions +$u(0) = 0$ and $u(1) = 1$. +@end tex +@end iftex +@ifinfo +@var{u}' - @var{alpha} * @var{u}'' = 0 with the boundary conditions +@var{u}(0) = 0 and @var{u}(1) = 1. +@end ifinfo + +First, we can generate the weight matrices for @var{n} points (including +the endpoints of the interval), and incorporate the boundary conditions +in the right hand side (for a specific value of +@iftex +@tex +$\alpha$). +@end tex +@end iftex +@ifinfo +@var{alpha}). +@end ifinfo + +@example +@group +n = 7; +alpha = 0.1; +[r, a, b] = colloc (n-2, "left", "right"); +at = a(2:n-1,2:n-1); +bt = b(2:n-1,2:n-1); +rhs = alpha * b(2:n-1,n) - a(2:n-1,n); +@end group +@end example + +Then the solution at the roots @var{r} is + +@example +u = [ 0; (at - alpha * bt) \ rhs; 1] + @result{} [ 0.00; 0.004; 0.01 0.00; 0.12; 0.62; 1.00 ] +@end example diff --git a/doc/interpreter/set.texi b/doc/interpreter/set.texi --- a/doc/interpreter/set.texi +++ b/doc/interpreter/set.texi @@ -14,14 +14,10 @@ order. For example, @example +@group create_set ([ 1, 2; 3, 4; 4, 2 ]) -@end example - -@noindent -returns the vector - -@example -[ 1, 2, 3, 4 ] + @result{} [ 1, 2, 3, 4 ] +@end group @end example @end deftypefn @@ -30,19 +26,23 @@ @var{y}. For example, @example +@group union ([ 1, 2, 3 ], [ 2, 3, 5 ]) -@end example - -@noindent -returns the vector - -@example -[ 1, 2, 5 ] + @result{} [ 1, 2, 5 ] +@end group @end example @end deftypefn @deftypefn {Function File} {} intersection (@var{x}, @var{y}) Return the set of elements that are in both sets @var{x} and @var{y}. +For example, + +@example +@group +intersection ([ 1, 2, 3 ], [ 2, 3, 5 ]) + @result{} [ 2, 3 ] +@end group +@end example @end deftypefn @deftypefn {Function File} {} complement (@var{x}, @var{y}) @@ -50,9 +50,9 @@ example, @example +@group complement ([ 1, 2, 3 ], [ 2, 3, 5 ]) + @result{} 5 +@end group @end example - -@noindent -returns the value @samp{5}. @end deftypefn diff --git a/doc/interpreter/signal.texi b/doc/interpreter/signal.texi --- a/doc/interpreter/signal.texi +++ b/doc/interpreter/signal.texi @@ -7,7 +7,7 @@ I hope that someday Octave will include more signal processing functions. If you would like to help improve Octave in this area, -please contact @code{bug-octave@@bevo.che.wisc.edu}. +please contact @email{bug-octave@@bevo.che.wisc.edu}. @deftypefn {Function File} {} detrend (@var{x}, @var{p}) If @var{x} is a vector, @code{detrend (@var{x}, @var{p})} removes the @@ -21,7 +21,7 @@ @end deftypefn @deftypefn {Function} {} fft (@var{a}, @var{n}) -Compute the FFT of @var{a} using subroutines from FFTPACK. If @var{a} +Compute the FFT of @var{a} using subroutines from @sc{Fftpack}. If @var{a} is a matrix, @code{fft} computes the FFT for each column of @var{a}. If called with two arguments, @var{n} is expected to be an integer @@ -32,7 +32,7 @@ @end deftypefn @deftypefn {Loadable Function} {} ifft (@var{a}, @var{n}) -Compute the inverse FFT of @var{a} using subroutines from FFTPACK. If +Compute the inverse FFT of @var{a} using subroutines from @sc{Fftpack}. If @var{a} is a matrix, @code{fft} computes the inverse FFT for each column of @var{a}. @@ -146,7 +146,8 @@ @iftex @tex $$ -H(z) = {\sum_{k=0}^M d_{k+1} z^{-k} \over 1 + \sum_{k+1}^N c_{k+1} z^{-k}} +H(z) = {\displaystyle\sum_{k=0}^M d_{k+1} z^{-k} + \over 1 + \displaystyle\sum_{k+1}^N c_{k+1} z^{-k}} $$ @end tex @end iftex @@ -211,7 +212,7 @@ @end deftypefn @deftypefn {Function File} {} sinc (@var{x}) -Returns +Return @iftex @tex $ \sin (\pi x)/(\pi x)$. diff --git a/doc/interpreter/special.texi b/doc/interpreter/special.texi --- a/doc/interpreter/special.texi +++ b/doc/interpreter/special.texi @@ -24,7 +24,7 @@ supply two scalar arguments, @code{eye} takes them to be the number of rows and columns. If given a vector with two elements, @code{eye} uses the values of the elements as the number of rows and columns, -respecively. For example, +respectively. For example, @example @group diff --git a/doc/interpreter/stats.texi b/doc/interpreter/stats.texi --- a/doc/interpreter/stats.texi +++ b/doc/interpreter/stats.texi @@ -7,7 +7,7 @@ I hope that someday Octave will include more statistics functions. If you would like to help improve Octave in this area, please contact -@code{bug-octave@@bevo.che.wisc.edu}. +@email{bug-octave@@bevo.che.wisc.edu}. @deftypefn {Function File} {} mean (@var{x}) If @var{x} is a vector, compute the mean of the elements of @var{x} diff --git a/doc/interpreter/stmt.texi b/doc/interpreter/stmt.texi --- a/doc/interpreter/stmt.texi +++ b/doc/interpreter/stmt.texi @@ -127,7 +127,7 @@ @var{body} is executed. If none of the conditions are true and the @code{else} clause is present, its body is executed. Only one @code{else} clause may appear, and it must be the last part of the -satement. +statement. In the following example, if the first condition is true (that is, the value of @code{x} is divisible by 2), then the first @code{printf} @@ -293,8 +293,8 @@ @var{condition} is no longer true. If @var{condition} is initially false, the body of the loop is never executed. -This example creates a variable @code{fib} that contains the elements of -the Fibonacci sequence. +This example creates a variable @code{fib} that contains the first ten +elements of the Fibonacci sequence. @example @group @@ -371,7 +371,7 @@ @end example @noindent -This code works by first evaluating the expression @samp{3:10}, to +This code works by first evaluating the expression @code{3:10}, to produce a range of values from 3 to 10 inclusive. Then the variable @code{i} is assigned the first element of the range and the body of the loop is executed once. When the end of the loop body is reached, the diff --git a/doc/interpreter/strings.texi b/doc/interpreter/strings.texi --- a/doc/interpreter/strings.texi +++ b/doc/interpreter/strings.texi @@ -42,15 +42,16 @@ double-quote character as a part of the string. The backslash character itself is another character that cannot be included normally. You must write @samp{\\} to put one backslash in the string. Thus, the string -whose contents are the two characters @samp{"\} must be written -@code{"\"\\"}. +whose contents are the two characters @samp{"\} may be written +@code{"\"\\"} or @code{'"\\'}. Similarly, the string whose contents are +the two characters @samp{'\} may be written @code{'\'\\'} or @code{"'\\"}. Another use of backslash is to represent unprintable characters such as newline. While there is nothing to stop you from writing most of these characters directly in a string constant, they may look ugly. Here is a table of all the escape sequences used in Octave. They are -the same as those used in the C programming langauge. +the same as those used in the C programming language. @table @code @item \\ @@ -108,8 +109,8 @@ @end example @noindent -produces the string whose contents are @samp{foobarbaz}. The next -section explains more about how to create matrices. +produces the string whose contents are @samp{foobarbaz}. @xref{Numeric +Data Types} for more information about creating matrices. @menu * Creating Strings:: @@ -146,20 +147,33 @@ @end deftypefn @deftypefn {Function File} {} strcat (@var{s1}, @var{s2}, @dots{}) -Return a string containing all the arguments contatenated. For example, +Return a string containing all the arguments concatenated. For example, @example @group s = [ "ab"; "cde" ] strcat (s, s, s) - @result{} ab ab ab - cdecdecde + @result{} "ab ab ab " + "cdecdecde" @end group @end example @end deftypefn @defvr {Built-in Variable} string_fill_char +The value of this variable is used to pad all strings in a string matrix +to the same length. It should be a single character. The default value +is @code{" "} (a single space). For example, + +@example +@group +string_fill_char = "X"; +[ "these"; "are"; "strings" ] + @result{} "theseXX" + @result{} "areXXXX" + @result{} "strings" +@end group +@end example @end defvr @deftypefn {Function File} {} str2mat (@var{s_1}, @dots{}, @var{s_n}) @@ -167,11 +181,10 @@ its rows. Each string is padded with blanks in order to form a valid matrix. -@quotation @strong{Note:} This function is modelled after @sc{MATLAB}. In Octave, you can create -a matrix of strings by @kbd{[@var{s_1}; @dots{}; @var{s_n}]}. -@end quotation +a matrix of strings by @code{[@var{s_1}; @dots{}; @var{s_n}]} even if +the strings are not all the same length. @end deftypefn @deftypefn {Built-in Function} {} isstr (@var{a}) @@ -187,21 +200,21 @@ @deftypefn {Function File} {} findstr (@var{s}, @var{t}, @var{overlap}) Returns the vector of all positions in the longer of the two strings -@var{s} and @var{t} where an occurence of the shorter of the two starts. +@var{s} and @var{t} where an occurrence of the shorter of the two starts. If the optional argument @var{overlap} is nonzero, the returned vector can include overlapping positions (this is the default). For example, @example findstr ("ababab", "a") - @result{} [1 3 5] + @result{} [ 1, 3, 5 ] findstr ("abababa", "aba", 0) - @result{} [1, 5] + @result{} [ 1, 5 ] @end example @end deftypefn @deftypefn {Function File} {} index (@var{s}, @var{t}) -Returns the position of the first occurence of the string @var{t} in the -string @var{s}, or 0 if no occurence is found. For example, +Returns the position of the first occurrence of the string @var{t} in the +string @var{s}, or 0 if no occurrence is found. For example, @example index ("Teststring", "t") @@ -212,8 +225,8 @@ @end deftypefn @deftypefn {Function File} {} rindex (@var{s}, @var{t}) -Returns the position of the last occurence of the string @var{t} in the -string @var{s}, or 0 if no occurence is found. For example, +Returns the position of the last occurrence of the string @var{t} in the +string @var{s}, or 0 if no occurrence is found. For example, @example rindex ("Teststring", "t") @@ -230,27 +243,27 @@ @example split ("Test string", "t") - @result{} Tes - s - ring + @result{} "Tes " + " s " + "ring" @end example @end deftypefn @deftypefn {Function File} {} strcmp (@var{s1}, @var{s2}) Compares two strings, returning 1 if they are the same, and 0 otherwise. -@strong{Note: For compatibility with @sc{Matlab}, Octave's strcmp +@strong{Note:} For compatibility with @sc{Matlab}, Octave's strcmp function returns 1 if the strings are equal, and 0 otherwise. This is -just the opposite of the corresponding C library function.} +just the opposite of the corresponding C library function. @end deftypefn @deftypefn {Function File} {} strrep (@var{s}, @var{x}, @var{y}) -Replaces all occurences of the substring @var{x} of the string @var{s} +Replaces all occurrences of the substring @var{x} of the string @var{s} with the string @var{y}. For example, @example strrep ("This is a test string", "is", "&%$") - @result{} Th&%$ &%$ a test string + @result{} "Th&%$ &%$ a test string" @end example @end deftypefn @@ -260,13 +273,13 @@ @example substr ("This is a test string", 6, 9) - @result{} is a test + @result{} "is a test" @end example @quotation @strong{Note:} This function is patterned after AWK. You can get the same result by -@kbd{@var{s} (@var{beg} : (@var{beg} + @var{len} - 1))}. +@code{@var{s} (@var{beg} : (@var{beg} + @var{len} - 1))}. @end quotation @end deftypefn @@ -391,10 +404,18 @@ @node Character Class Functions, , String Conversions, Strings @section Character Class Functions -Octave also provides the following C-type character class test -functions. They all operate on string arrays and return matrices of -zeros and ones. Elements that are nonzero indicate that the condition -was true for the corresponding character in the string array. +Octave also provides the following character class test functions +patterned after the functions in the standard C library. They all +operate on string arrays and return matrices of zeros and ones. +Elements that are nonzero indicate that the condition was true for the +corresponding character in the string array. For example, + +@example +@group +isalpha ("!Q@@WERT^Y&") + @result{} [ 0, 1, 0, 1, 1, 1, 1, 0, 1, 0 ] +@end group +@end example @deftypefn {Mapping Function} {} isalnum (@var{s}) Returns true for characters that are letters or digits (@code{isalpha diff --git a/doc/interpreter/system.texi b/doc/interpreter/system.texi --- a/doc/interpreter/system.texi +++ b/doc/interpreter/system.texi @@ -74,34 +74,96 @@ @deftypefn {Loadable Function} {} time () Return the current time as the number of seconds since the epoch. The epoch is referenced to 00:00:00 CUT (Coordinated Universal Time) 1 Jan -1970. +1970. For example, on Monday February 17, 1997 at 07:15:06 CUT, the +value returned by @code{time} was 856163706. @end deftypefn @deftypefn {Function File} {} ctime (@var{t}) Convert a value returned from @code{time} (or any other nonnegative integer), to the local time and return a string of the same form as @code{asctime}. The function @code{ctime (time)} is equivalent to -@code{asctime (localtime (time))}. +@code{asctime (localtime (time))}. For example, + +@example +@group +ctime (time ()) + @result{} "Mon Feb 17 01:15:06 1997" +@end group +@end example @end deftypefn @deftypefn {Loadable Function} {} gmtime (@var{t}) Given a value returned from time (or any nonnegative integer), -return a time structure corresponding to CUT. +return a time structure corresponding to CUT. For example, + +@example +@group +gmtime (time ()) + @result{} @{ + usec = 0 + year = 97 + mon = 1 + mday = 17 + sec = 6 + zone = CST + min = 15 + wday = 1 + hour = 7 + isdst = 0 + yday = 47 + @} +@end group +@end example @end deftypefn @deftypefn {Loadable Function} {} localtime (@var{t}) Given a value returned from time (or any nonnegative integer), return a time structure corresponding to the local time zone. + +@example +@group +locatltime (time ()) + @result{} @{ + usec = 0 + year = 97 + mon = 1 + mday = 17 + sec = 6 + zone = CST + min = 15 + wday = 1 + hour = 1 + isdst = 0 + yday = 47 + @} +@end group +@end example @end deftypefn @deftypefn {Loadable Function} {} mktime (@var{tm_struct}) -Convert a time structure to the number of seconds since the epoch. +Convert a time structure to the number of seconds since the epoch. For +example, + +@example +@group +mktime (localtime (time ()) + @result{} 856163706 +@end group +@end example @end deftypefn @deftypefn {Function File} {} asctime (@var{tm_struct}) Convert a time structure to a string using the following five-field -format: Thu Mar 28 08:40:14 1996. The function @code{ctime (time)} is -equivalent to @code{asctime (localtime (time))}. +format: Thu Mar 28 08:40:14 1996. For example, + +@example +@group +asctime (localtime (time ()) + @result{} "Mon Feb 17 01:15:06 1997\n" +@end group +@end example + +This is equivalent to @code{ctime (time ())}. @end deftypefn @deftypefn {Loadable Function} {} strftime (@var{tm_struct}) @@ -112,7 +174,14 @@ number, padding can be changed or inhibited by following the @samp{%} with one of the modifiers described below. Unknown field specifiers are copied as normal characters. All other characters are copied to the -output without change. +output without change. For example, + +@example +@group +strftime ("%r (%Z) %A %e %B %Y", localtime (time ()) + @result{} "01:15:06 AM (CST) Monday 17 February 1997" +@end group +@end example Octave's @code{strftime} function supports a superset of the ANSI C field specifiers. @@ -256,10 +325,10 @@ hour (0-23), minute (0-59) and second (0-61). For example, @example -octave:13> clock -ans = - - 1993 8 20 4 56 1 +@group +clock () + @result{} [ 1993, 8, 20, 4, 56, 1 ] +@end group @end example The function clock is more accurate on systems that have the @@ -271,8 +340,10 @@ example, @example -octave:13> date -ans = 20-Aug-93 +@group +date () + @result{} "20-Aug-93" +@end group @end example @end deftypefn @@ -309,8 +380,10 @@ For example, @example -octave:13> is_leap_year (2000) -ans = 1 +@group +is_leap_year (2000) + @result{} 1 +@end group @end example @end deftypefn @@ -365,11 +438,14 @@ @end deftypefn @deftypefn {Built-in Function} {} sleep (@var{seconds}) -Suspend the execution of the program. +Suspend the execution of the program for the given number of seconds. @end deftypefn @deftypefn {Built-in Function} {} usleep (@var{microseconds}) -Suspend the execution of the program. +Suspend the execution of the program for the given number of +microseconds. On systems where it is not possible to sleep for periods +of time less than one second, @code{usleep} will pause the execution for +@code{round (@var{microseconds} / 1e6)} seconds. @end deftypefn @node Filesystem Utilities, Controlling Subprocesses, Timing Utilities, System Utilities @@ -436,8 +512,8 @@ interpreted as an octal number. @end deftypefn -@deftypefn {Built-in Function} {[info, err, msg] =} stat (@var{file}) -@deftypefnx {Built-in Function} {[info, err, msg] =} lstat (@var{file}) +@deftypefn {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} stat (@var{file}) +@deftypefnx {Built-in Function} {[@var{info}, @var{err}, @var{msg}] =} lstat (@var{file}) Return a structure @var{s} containing the following information about @var{file}. @@ -488,7 +564,7 @@ If the call is successful @var{err} is 0 and @var{msg} is an empty string. If the file does not exist, or some other error occurs, @var{s} -is an empty matrix, @var{err} is -1, and @var{msg} contains the +is an empty matrix, @var{err} is @minus{}1, and @var{msg} contains the corresponding system error message. If @var{file} is a symbolic link, @code{stat} will return information @@ -530,13 +606,30 @@ Given an array of strings in @var{pattern}, return the list of file names that any of them, or an empty string if no patterns match. Tilde expansion is performed on each of the patterns before looking for -matching file names. +matching file names. For example, + +@example +@group +glob ("/vm*") + @result{} "/vmlinuz" +@end group +@end example + +Note that multiple values are returned in a string matrix with the fill +character set to ASCII NUL. @end deftypefn @deftypefn {Built-in Function} {} fnmatch (@var{pattern}, @var{string}) Return 1 or zero for each element of @var{string} that matches any of the elements of the string array @var{pattern}, using the rules of -filename pattern matching. +filename pattern matching. For example, + +@example +@group +fnmatch ("a*b", ["ab"; "axyzb"; "xyzab"]) + @result{} [ 1; 1; 0 ] +@end group +@end example @end deftypefn @deftypefn {Built-in Function} {} file_in_path (@var{path}, @var{file}) @@ -549,13 +642,28 @@ For example, @example -octave:13> file_in_path (LOADPATH, "nargchk.m") -ans = "@value{OCTAVEHOME}/share/octave/2.0/m/general/nargchk.m" +file_in_path (LOADPATH, "nargchk.m") + @result{} "@value{OCTAVEHOME}/share/octave/2.0/m/general/nargchk.m" @end example @end deftypefn @deftypefn {Built-in Function} {} tilde_expand (@var{string}) -Performs tilde expansion on @var{string}. +Performs tilde expansion on @var{string}. If @var{string} begins with a +tilde character, (@samp{~}), all of the characters preceding the first +slash (or all characters, if there is no slash) are treated as a +possible user name, and the tilde and the following characters up to the +slash are replaced by the home directory of the named user. If the +tilde is followed immediately by a slash, the tilde is replaced by the +home directory of the user running Octave. For example, + +@example +@group +tilde_expand ("~joeuser/bin") + @result{} "/home/joeuser/bin" +tilde_expand ("~/bin") + @result{} "/home/jwe/bin" +@end group +@end example @end deftypefn @node Controlling Subprocesses, Process ID Information, Filesystem Utilities, System Utilities @@ -574,7 +682,7 @@ @deftypefn {Built-in Function} {} system (@var{string}, @var{return_output}, @var{type}) Execute a shell command specified by @var{string}. The second argument is optional. If @var{type} is @code{"async"}, the process is started in the -background and the process id of the child proces is returned +background and the process id of the child process is returned immediately. Otherwise, the process is started, and Octave waits until it exits. If @var{type} argument is omitted, a value of @code{"sync"} is assumed. @@ -612,15 +720,67 @@ @end deftypefn @deftypefn {Built-in Function} {fid =} popen (@var{command}, @var{mode}) -Open a pipe to a subprocess. +Start a process and create a pipe. The name of the command to run is +given by @var{command}. The file identifier corresponding to the input +or output stream of the process is returned in @var{fid}. The argument +@var{mode} may be + +@table @code +@item "r" +The pipe will be connected to the standard output of the process, and +open for reading. + +@item "w" +The pipe will be connected to the standard input of the process, and +open for writing. +@end table + +For example, + +@example +@group +fid = popen ("ls -ltr / | tail -3", "r"); +while (isstr (s = fgets (fid))) + fputs (stdout, s); +endwhile + @print{} drwxr-xr-x 33 root root 3072 Feb 15 13:28 etc + @print{} drwxr-xr-x 3 root root 1024 Feb 15 13:28 lib + @print{} drwxrwxrwt 15 root root 2048 Feb 17 14:53 tmp +@end group +@end example @end deftypefn @deftypefn {Built-in Function} {} pclose (@var{fid}) -Close a pipe from a subprocess. +Close a file identifier that was opened by @code{popen}. You may also +use @code{fclose} for the same purpose. @end deftypefn @deftypefn {Built-in Function} {[@var{in}, @var{out}, @var{pid}] =} popen2 (@var{command}, @var{args}) -Start a subprocess with 2-way communication. +Start a subprocess with two-way communication. The name of the process +is given by @var{command}, and @var{args} is an array of strings +containing options for the command. The file identifiers for the input +and output streams of the subprocess are returned in @var{in} and +@var{out}. If execution of the command is successful, @var{pid} +contains the process ID of the subprocess. Otherwise, @var{pid} is +@minus{}1. + +For example, + +@example +@group +[in, out, pid] = popen2 ("sort", "-nr"); +fputs (in, "these\nare\nsome\nstrings\n"); +fclose (in); +while (isstr (s = fgets (out))) + fputs (stdout, s); +endwhile +fclose (out); + @print{} are + @print{} some + @print{} strings + @print{} these +@end group +@end example @end deftypefn @defvr {Built-in Variable} EXEC_PATH @@ -633,9 +793,10 @@ begins (ends) with a colon, the directories @example +@group OCTAVE_HOME/libexec/octave/site/exec/ARCH OCTAVE_HOME/libexec/octave/VERSION/exec/ARCH -OCTAVE_HOME/bin +@end group @end example @noindent @@ -709,7 +870,7 @@ Wait for process @var{pid} to terminate. The @var{pid} argument can be: @table @asis -@item -1 +@item @minus{}1 Wait for any child process. @item 0 @@ -828,7 +989,7 @@ @end deftypefn @node Environment Variables, Current Working Directory, Process ID Information, System Utilities -@section Environemnt Variables +@section Environment Variables @deftypefn {Built-in Function} {} getenv (@var{var}) Returns the value of the environment variable @var{var}. For example, @@ -877,10 +1038,10 @@ List directory contents. For example, @example -octave:13> ls -l -total 12 --rw-r--r-- 1 jwe users 4488 Aug 19 04:02 foo.m --rw-r--r-- 1 jwe users 1315 Aug 17 23:14 bar.m +ls -l + @print{} total 12 + @print{} -rw-r--r-- 1 jwe users 4488 Aug 19 04:02 foo.m + @print{} -rw-r--r-- 1 jwe users 1315 Aug 17 23:14 bar.m @end example The @code{dir} and @code{ls} commands are implemented by calling your @@ -917,19 +1078,22 @@ The initial shell. @end table -@deftypefn {Loadable Function} {} getpwent () +In the descriptions of the following functions, this data structure is +referred to as a @var{pw_struct}. + +@deftypefn {Loadable Function} {@var{pw_struct} = } getpwent () Return a structure containing an entry from the password database, opening it if necessary. Once the end of the data has been reached, @code{getpwent} returns 0. @end deftypefn -@deftypefn {Loadable Function} {} getpwuid (@var{uid}). +@deftypefn {Loadable Function} {@var{pw_struct} = } getpwuid (@var{uid}). Return a structure containing the first entry from the password database with the user ID @var{uid}. If the user ID does not exist in the database, @code{getpwuid} returns 0. @end deftypefn -@deftypefn {Loadable Function} {} getpwnam (@var{name}) +@deftypefn {Loadable Function} {@var{pw_struct} = } getpwnam (@var{name}) Return a structure containing the first entry from the password database with the user name @var{name}. If the user name does not exist in the database, @code{getpwname} returns 0. @@ -963,18 +1127,21 @@ The members of the group. @end table -@deftypefn {Loadable Function} {group_struct =} getgrent () +In the descriptions of the following functions, this data structure is +referred to as a @var{grp_struct}. + +@deftypefn {Loadable Function} {grp_struct =} getgrent () Return an entry from the group database, opening it if necessary. Once the end of the data has been reached, @code{getgrent} returns 0. @end deftypefn -@deftypefn {Loadable Function} {group_struct =} getgrgid (@var{gid}). +@deftypefn {Loadable Function} {grp_struct =} getgrgid (@var{gid}). Return the first entry from the group database with the group ID @var{gid}. If the group ID does not exist in the database, @code{getgrgid} returns 0. @end deftypefn -@deftypefn {Loadable Function} {group_struct =} getgrnam (@var{name}) +@deftypefn {Loadable Function} {grp_struct =} getgrnam (@var{name}) Return the first entry from the group database with the group name @var{name}. If the group name does not exist in the database, @code{getgrname} returns 0. @@ -992,12 +1159,19 @@ @section System Information @deftypefn {Built-in Function} {} computer () -Returns a string of the form @var{cpu}-@var{vendor}-@var{os} that -identifies the kind of computer Octave is running on. For example, +Print or return a string of the form @var{cpu}-@var{vendor}-@var{os} +that identifies the kind of computer Octave is running on. If invoked +with an output argument, the value is returned instead of printed. For +example, @example -octave:13> computer -sparc-sun-sunos4.1.2 +@group +computer () + @print{} i586-pc-linux-gnu + +x = computer () + @result{} x = "i586-pc-linux-gnu" +@end group @end example @end deftypefn diff --git a/doc/interpreter/tips.texi b/doc/interpreter/tips.texi --- a/doc/interpreter/tips.texi +++ b/doc/interpreter/tips.texi @@ -35,9 +35,9 @@ prefix. This helps avoid name conflicts. If you write a function that you think ought to be added to Octave under -a certain name, such as @code{twiddle-matrix}, don't call it by that name -in your program. Call it @code{mylib-twiddle-matrix} in your program, -and send mail to @samp{bug-octave@@bevo.che.wisc.edu} suggesting that it +a certain name, such as @code{fiddle_matrix}, don't call it by that name +in your program. Call it @code{mylib_fiddle_matrix} in your program, +and send mail to @email{bug-octave@@bevo.che.wisc.edu} suggesting that it be added to Octave. If and when it is, the name can be changed easily enough. @@ -50,7 +50,8 @@ @item When you encounter an error condition, call the function @code{error} -(or @code{usage}). The function @code{error} does not return. +(or @code{usage}). The @code{error} and @code{usage} functions do not +return. @xref{Errors}. @item @@ -111,6 +112,13 @@ If you are using @code{eval} as an exception handling mechanism and not because you need to execute some arbitrary text, use the @code{try} statement instead. @xref{The try Statement}. + +@item +If you are calling lots of functions but none of them will need to +change during your run, set the variable +@code{ignore_function_time_stamp} to @code{"all"} so that Octave doesn't +waste a lot of time checking to see if you have updated your function +files. @end itemize @node Documentation Tips, Comment Tips, Coding Tips, Tips diff --git a/doc/interpreter/var.texi b/doc/interpreter/var.texi --- a/doc/interpreter/var.texi +++ b/doc/interpreter/var.texi @@ -87,15 +87,15 @@ @group global x function f () -x = 1; + x = 1; endfunction f () @end group @end example @noindent -does @emph{not} set the value of the global variable @samp{x} to 1. In -order to change the value of the global variable @samp{x}, you must also +does @emph{not} set the value of the global variable @code{x} to 1. In +order to change the value of the global variable @code{x}, you must also declare it to be global within the function body, like this @example @@ -120,7 +120,7 @@ @end example @noindent -and the definition of @samp{x} as a global variable at the top level, +and the definition of @code{x} as a global variable at the top level, @example global x = 13 @@ -134,8 +134,8 @@ @end example @noindent -will display the value of @samp{x} from inside the function as @samp{0}, -but the value of @samp{x} at the top level remains unchanged, because +will display the value of @code{x} from inside the function as 0, +but the value of @code{x} at the top level remains unchanged, because the function works with a @emph{copy} of its argument. @defvr {Built-in Variable} warn_comma_in_global_decl @@ -147,8 +147,8 @@ @end example @noindent -which makes the variables @samp{a} and @samp{b} global and assigns the -value 1 to the variable @samp{a}, because in this context, the comma is +which makes the variables @code{a} and @code{b} global and assigns the +value 1 to the variable @code{a}, because in this context, the comma is not interpreted as a statement separator. The default value of @code{warn_comma_in_global_decl} is nonzero. @@ -202,9 +202,9 @@ @code{clear} is called with at least one argument, only the visible names matching the arguments are cleared. For example, suppose you have defined a function @code{foo}, and then hidden it by performing the -assignment @code{foo = 2}. Executing the command @samp{clear foo} once +assignment @code{foo = 2}. Executing the command @kbd{clear foo} once will clear the variable definition and restore the definition of -@code{foo} as a function. Executing @samp{clear foo} a second time will +@code{foo} as a function. Executing @kbd{clear foo} a second time will clear the function definition. This command may not be used within a function body. @@ -243,7 +243,7 @@ are listed. By default, only user defined functions and variables visible in the local scope are displayed. -The command @code{whos} is equivalent to @code{who -long}. +The command @kbd{whos} is equivalent to @kbd{who -long}. @end deffn @deftypefn {Built-in Function} {} exist (@var{name}) diff --git a/doc/texinfo.tex b/doc/texinfo.tex --- a/doc/texinfo.tex +++ b/doc/texinfo.tex @@ -1,5 +1,5 @@ %% TeX macros to handle Texinfo files. -%% $Id: texinfo.tex,v 1.3 1997-02-13 18:33:50 jwe Exp $ +%% $Id: texinfo.tex,v 1.4 1997-02-18 09:08:50 jwe Exp $ % Copyright (C) 1985, 86, 88, 90, 91, 92, 93, % 94, 95, 96, 97 Free Software Foundation, Inc. @@ -36,7 +36,7 @@ % This automatically updates the version number based on RCS. \def\deftexinfoversion$#1: #2 ${\def\texinfoversion{#2}} -\deftexinfoversion$Revision: 1.3 $ +\deftexinfoversion$Revision: 1.4 $ \message{Loading texinfo package [Version \texinfoversion]:} % If in a .fmt file, print the version number @@ -951,8 +951,7 @@ % At the `@end #1', redefine \E#1 to be its previous value. \def\nece{E#1}{\let\nece{E#1} = \nece{prevE#1}}% }% - \temp -} + \temp} % We need to expand lots of \csname's, but we don't want to expand the % control sequences after we've constructed them. @@ -3393,9 +3392,9 @@ \let\}=\ptexrbrace \let\.=\ptexdot \let\*=\ptexstar -\let\dots=\ptexdots -\def\endldots{\mathinner{\ldots\ldots\ldots\ldots}} -\def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi} +\let\dots=\ptexdots% +\def\endldots{\mathinner{\ldots\ldots\ldots\ldots}}% +\def\enddots{\relax\ifmmode\endldots\else$\mathsurround=0pt \endldots\,$\fi}% \def\@{@}% \let\bullet=\ptexbullet \let\b=\ptexb \let\c=\ptexc \let\i=\ptexi \let\t=\ptext diff --git a/examples/Makefile.in b/examples/Makefile.in --- a/examples/Makefile.in +++ b/examples/Makefile.in @@ -21,7 +21,7 @@ SCRIPTS = info-emacs-info info-emacs-octave-help -SOURCES = hello.cc make_int.cc +SOURCES = hello.cc oregonator.m oregonator.cc make_int.cc DISTFILES = Makefile.in $(SOURCES) $(SCRIPTS) diff --git a/examples/oregonator.cc b/examples/oregonator.cc new file mode 100644 --- /dev/null +++ b/examples/oregonator.cc @@ -0,0 +1,17 @@ +#include + +#include + +DEFUN_DLD (oregonator, args, , + "The `oregonator'.") +{ + ColumnVector dx (3); + + ColumnVector x = args(0).vector_value (); + + dx(0) = 77.27 * (x(1) - x(0)*x(1) + x(0) - 8.375e-06*pow (x(0), 2)); + dx(1) = (x(2) - x(0)*x(1) - x(1)) / 77.27; + dx(2) = 0.161*(x(0) - x(2)); + + return octave_value (dx); +} diff --git a/examples/oregonator.m b/examples/oregonator.m new file mode 100644 --- /dev/null +++ b/examples/oregonator.m @@ -0,0 +1,11 @@ +## The `oregonator'. + +function dx = oregonator (x, t) + + dx = zeros (3, 1); + + dx(1) = 77.27*(x(2) - x(1)*x(2) + x(1) - 8.375e-06*x(1)^2); + dx(2) = (x(3) - x(1)*x(2) - x(2)) / 77.27; + dx(3) = 0.161*(x(1) - x(3)); + +end diff --git a/src/ChangeLog b/src/ChangeLog --- a/src/ChangeLog +++ b/src/ChangeLog @@ -1,3 +1,7 @@ +Tue Feb 18 00:27:49 1997 John W. Eaton + + * toplev.cc (octave_config_info): Handle option argument. + Fri Feb 14 16:23:30 1997 John W. Eaton * oct-stream.cc (octave_base_stream::do_scanf): Don't forget to diff --git a/src/toplev.cc b/src/toplev.cc --- a/src/toplev.cc +++ b/src/toplev.cc @@ -846,15 +846,32 @@ return retval; } -DEFUN (octave_config_info, , , - "return a structure containing configuration information") +DEFUN (octave_config_info, args, , + "octave_config_info (OPTION)\n\ +\n\ +If OPTION is a string, return the configuration information for the\n\ +specified option.\n\ +\n\ +With no arguments, return a structure containing configuration\n\ +information.") { + octave_value retval; + +#if defined (WITH_DYNAMIC_LINKING) +#if defined (WITH_DL) || defined (WITH_SHL) + bool octave_supports_dynamic_linking = true; +#else + bool octave_supports_dynamic_linking = false; +#endif +#endif + Octave_map m; m ["default_pager"] = DEFAULT_PAGER; m ["prefix"] = OCTAVE_PREFIX; m ["exec_prefix"] = OCTAVE_EXEC_PREFIX; m ["datadir"] = OCTAVE_DATADIR; + m ["dld"] = (double) octave_supports_dynamic_linking; m ["libdir"] = OCTAVE_LIBDIR; m ["bindir"] = OCTAVE_BINDIR; m ["infodir"] = OCTAVE_INFODIR; @@ -896,7 +913,21 @@ m ["LIBDLFCN"] = LIBDLFCN; m ["DEFS"] = DEFS; - return octave_value (m); + int nargin = args.length (); + + if (nargin == 1) + { + string arg = args(0).string_value (); + + if (! error_state) + retval = octave_value (m [arg.c_str ()]); + } + else if (nargin == 0) + retval = octave_value (m); + else + print_usage ("octave_config_info"); + + return retval; } #if defined (__GNUG__) && defined (DEBUG_NEW_DELETE)