This is Info file octave.info, produced by Makeinfo-1.55 from the input
file octave.texi.

   Copyright (C) 1993, 1994, 1995 John W. Eaton.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided that
the entire resulting derived work is distributed under the terms of a
permission notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions.


File: octave.info,  Node: Ordinary Differential Equations,  Next: Differential-Algebraic Equations,  Prev: Differential Equations,  Up: Differential Equations

Ordinary Differential Equations
===============================

   The function `lsode' can be used Solve ODEs of the form

     dx
     -- = f (x, t)
     dt

using Hindmarsh's ODE solver LSODE.

     lsode (FCN, X0, T_OUT, T_CRIT)

   The first argument is the name of the function to call to compute
the vector of right hand sides.  It must have the form

     XDOT = f (X, T)

where XDOT and X are vectors and T is a scalar.

   The second argument specifies the initial condition, and the third
specifies a vector of output times at which the solution is desired,
including the time corresponding to the initial condition.

   The fourth argument is optional, and may be used to specify a set of
times that the ODE solver should not integrate past.  It is useful for
avoiding difficulties with singularities and points where there is a
discontinuity in the derivative.

   Tolerances and other options for `lsode' may be specified using the
function `lsode_options'.

   Here is an example of solving a set of two differential equations
using `lsode'.  The function

     function xdot = f (x, t)
     
       r = 0.25;
       k = 1.4;
       a = 1.5;
       b = 0.16;
       c = 0.9;
       d = 0.8;
     
       xdot(1) = r*x(1)*(1 - x(1)/k) - a*x(1)*x(2)/(1 + b*x(1));
       xdot(2) = c*a*x(1)*x(2)/(1 + b*x(1)) - d*x(2);
     
     endfunction

is integrated with the command

     x = lsode ("f", [1; 2], (t = linspace (0, 50, 200)'));

producing a set of 200 values stored in the variable X.  Note that this
example takes advantage of the fact that an assignment produces a value
to store the values of the output times in the variable T directly in
the function call   The results can then be plotted using the command

     plot (t, x)

   See Alan C. Hindmarsh, `ODEPACK, A Systematized Collection of ODE
Solvers', in Scientific Computing, R. S. Stepleman, editor, (1983) for
more information about this family of ODE solvers.


File: octave.info,  Node: Differential-Algebraic Equations,  Prev: Ordinary Differential Equations,  Up: Differential Equations

Differential-Algebraic Equations
================================

   The function `dassl' can be used Solve DAEs of the form

     0 = f (x-dot, x, t),    x(t=0) = x_0, x-dot(t=0) = x-dot_0

     dassl (FCN, X_0, XDOT_0, T_OUT, T_CRIT)

   The first argument is the name of the function to call to compute
the vector of residuals.  It must have the form

     RES = f (X, XDOT, T)

where X, XDOT, and RES are vectors, and T is a scalar.

   The second and third arguments to `dassl' specify the initial
condition of the states and their derivatives, and the fourth argument
specifies a vector of output times at which the solution is desired,
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
determining a consistent set for you, so it is best if you ensure that
the initial values result in the function evaluating to zero.

   The fifth argument is optional, and may be used to specify a set of
times that the DAE solver should not integrate past.  It is useful for
avoiding difficulties with singularities and points where there is a
discontinuity in the derivative.

   Tolerances and other options for `dassl' may be specified using the
function `dassl_options'.

   See K. E. Brenan, et al., `Numerical Solution of Initial-Value
Problems in Differential-Algebraic Equations', North-Holland (1989) for
more information about the implementation of DASSL.


File: octave.info,  Node: Optimization,  Next: Quadrature,  Prev: Differential Equations,  Up: Top

Optimization
************

* Menu:

* Quadratic Programming::
* Nonlinear Programming::
* Linear Least Squares::


File: octave.info,  Node: Quadratic Programming,  Next: Nonlinear Programming,  Prev: Optimization,  Up: Optimization

Quadratic Programming
=====================

`qpsol'
          [x, obj, info, lambda]
             = qpsol (x, H, c, lb, ub, lb, A, 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.  *Note
     Installation::.

   Tolerances and other options for `qpsol' may be specified using the
function `qpsol_options'.


File: octave.info,  Node: Nonlinear Programming,  Next: Linear Least Squares,  Prev: Quadratic Programming,  Up: Optimization

Nonlinear Programming
=====================

`npsol'
          [x, obj, info, lambda]
             = npsol (x, 'phi', lb, ub, lb, A, ub, lb, 'g', 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.  *Note
     Installation::.

     The second argument is a string containing the name of the
     objective function to call.  The objective function must be of the
     form

          y = phi (x)

     where x is a vector and y is a scalar.

   Tolerances and other options for `npsol' may be specified using the
function `npsol_options'.


File: octave.info,  Node: Linear Least Squares,  Prev: Nonlinear Programming,  Up: Optimization

Linear Least Squares
====================

`gls (Y, X, O)'
     Generalized least squares (GLS) estimation for the multivariate
     model

          Y = X * B + E,  mean(E) = 0,  cov(vec(E)) = (s^2)*O

     with

          Y an T x p matrix
          X an T x k matrix
          B an k x p matrix
          E an T x p matrix
          O an Tp x Tp matrix

     Each row of Y and X is an observation and each column a variable.

     Returns BETA, v, and, R, where BETA is the GLS estimator for B, v
     is the GLS estimator for s^2, and R = Y - X*BETA is the matrix of
     GLS residuals.

`ols (Y, X)'
     Ordinary Least Squares (OLS) estimation for the multivariate model

          Y = X*B + E,  mean (E) = 0,  cov (vec (E)) = kron (S, I)

     with

          Y an T x p matrix
          X an T x k matrix
          B an k x p matrix
          E an T x p matrix

     Each row of Y and X is an observation and each column a variable.

     Returns BETA, SIGMA, and R, where BETA is the OLS estimator for B,
     i.e.

          BETA = pinv(X)*Y,

     where pinv(X) denotes the pseudoinverse of X, SIGMA is the OLS
     estimator for the matrix S, i.e.

          SIGMA = (Y - X*BETA)'*(Y - X*BETA) / (T - rank(X))

     and R = Y - X*BETA is the matrix of OLS residuals.


File: octave.info,  Node: Quadrature,  Next: Control Theory,  Prev: Optimization,  Up: Top

Quadrature
**********

* Menu:

* Functions of one Variable::
* Orthogonal Collocation::


File: octave.info,  Node: Functions of one Variable,  Next: Orthogonal Collocation,  Prev: Quadrature,  Up: Quadrature

Functions of one Variable
=========================

`quad'
          [v, ier, nfun] = quad ("f", a, b)
          [v, ier, nfun] = quad ("f", a, b, tol)
          [v, ier, nfun] = quad ("f", a, b, tol, sing)

     Integrate a nonlinear function of one variable using Quadpack.

     Where the first argument is the name of the  function to call to
     compute the value of the integrand.  It must have the form

          y = f (x)

     where y and x are scalars.

     The second and third arguments are limits of integration.  Either
     or both may be infinite.  The optional argument tol specifies the
     desired accuracy of the result.  The optional argument SING is a
     vector of values at which the integrand is singular.

     Tolerances and other options for `quad' may be specified using the
     function `quad_options'.


File: octave.info,  Node: Orthogonal Collocation,  Prev: Functions of one Variable,  Up: Quadrature

Orthogonal Collocation
======================

`colloc'
          [r, A, B, q] = colloc (n)
          [r, A, B, q] = colloc (n, "left")
          [r, A, B, q] = colloc (n, "left", "right")

     Compute derivative and integral weight matrices for orthogonal
     collocation using the subroutines given in J. Michelsen and M. L.
     Villadsen, `Solution of Differential Equation Models by Polynomial
     Approximation'.


File: octave.info,  Node: Control Theory,  Next: Signal Processing,  Prev: Quadrature,  Up: Top

Control Theory
**************

`abcddim (A, B, C, D)'
     Check for compatibility of the dimensions of the matrices defining
     the linear system [A, B, C, D] corresponding to

          dx/dt = a x + b u
          y = c x + d u

     or a similar discrete-time system.

     If the matrices are compatibly dimensioned, then `abcddim' returns
     N = number of system states, M = number of system inputs, and P =
     number of system outputs.  Otherwise `abcddim' returns N = M = P =
     -1.

`are (A, B, C, OPT)'
     Returns the solution, X, of the algebraic Riccati equation

          a' x + x a - x b x + c = 0

     for identically dimensioned square matrices A, B, C.  If B (C) is
     not square, then the function attempts to use `B*B'' (`C'*C')
     instead.

     Solution method: apply Laub's Schur method (IEEE Transactions on
     Automatic Control, 1979) to the appropriate Hamiltonian matrix.

     OPT is an option passed to the eigenvalue balancing routine.
     Default is `"B"'.

`c2d (A, B, T)'
     Converts the continuous time system described by:

          dx/dt = a x + b u

     into a discrete time equivalent model

          x[k+1] = Ad x[k] + Bd u[k]

     via the matrix exponential assuming a zero-order hold on the input
     and sample time T.

`dare (A, B, C, R, OPT)'
     Returns the solution, X of the discrete-time algebraic Riccati
     equation

          a' x a - x + a' x b (r + b' x b)^(-1) b' x a + c = 0

     for matrices with dimensions:

          A: N by N
          B: N by M
          C: N by N, symmetric positive semidefinite
          R: M by M, symmetric positive definite (invertible)

     If C is not square, then the function attempts to use `C'*C'
     instead.

     Solution method: Laub's Schur method (IEEE Transactions on
     Automatic Control, 1979) is applied to the appropriate symplectic
     matrix.

     See also: Ran and Rodman, `Stable Hermitian Solutions of Discrete
     Algebraic Riccati Equations', Mathematics of Control, Signals and
     Systems, Volume 5, Number 2 (1992).

     OPT is an option passed to the eigenvalue balancing routine.  The
     default is `"B"'.

`dgram (A, B)'
     Returns the discrete controllability and observability gramian for
     the discrete time system described by

          x[k+1] = A x[k] + B u[k]
            y[k] = C x[k] + D u[k]

     `dgram (A, B)' returns the discrete controllability gramian and
     `dgram (A', C')' returns the observability gramian.

`dlqe (A, G, C, SIGW, SIGV [, Z])'
     Linear quadratic estimator (Kalman filter) design for the discrete
     time system

          x[k+1] = A x[k] + B u[k] + G w[k]
            y[k] = C x[k] + D u[k] + w[k]

     where W, V are zero-mean gaussian noise processes with respective
     intensities `SIGW = cov (W, W)' and `SIGV = cov (V, V)'.

     If specified, Z is `cov (W, V)'.  Otherwise `cov (W, V) = 0'.

     The observer structure is

          z[k+1] = A z[k] + B u[k] + k(y[k] - C z[k] - D u[k])

     Returns:

     L is the observer gain, `(A - A L C)' is stable.

     M is the Ricatti equation solution.

     P is the estimate error covariance after the measurement update.

     E are the closed loop poles of `(A - A L C)'.

`dlqr (A, B, Q, R [, Z])'
     Linear quadratic regulator design for the discrete time system

          x[k+1] = A x[k] + B u[k]

     to minimize the cost functional

          J = Sum [ x' Q x + u' R u ],              Z omitted

     or

          J = Sum [ x' Q x + u' R u +2 x' Z u ],    Z included

     Returns:

     K is the state feedback gain, `(A - B K)' is stable.

     P is the solution of algebraic Riccati equation.

     E are the closed loop poles of (A - B K).

`dlyap (A, B)'
     Solve the discrete-time Lyapunov equation

          a x a' - x + b = 0

     for square matrices A, B.  If B is not square, then the function
     attempts to solve either

          a x a' - x + b b' = 0

     or

          a' x a - x + b' b = 0

     whichever is appropriate.

     Uses Schur decomposition method as in Kitagawa, International
     Journal of Control (1977); column-by-column solution method as
     suggested in Hammarling, IMA Journal of Numerical Analysis, (1982).

`is_controllable (A, B, TOL)'
     If the pair (a, b) is controllable, then return value 1.
     Otherwise, returns a value of 0.

     TOL is a roundoff parameter, set to `2*eps' if omitted.

     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

                                n-1
           span ([b, a*b, ..., a^   *b]).

`is_observable (A, C, TOL)'
     Returns 1 if the pair `(a, c)' is observable.  Otherwise, returns
     a value of 0.

`lqe (A, G, C, SIGW, SIGV, Z)'
          [k, p, e] = lqe (a, g, c, sigw, sigv, z)

     Linear quadratic estimator (Kalman filter) design for the
     continuous time system

          dx
          -- = a x + b u
          dt
          
          y = c x + d u

     where W, V are zero-mean gaussian noise processes with respective
     intensities

          sigw = cov (w, w)
          sigv = cov (v, v)

     Z (if specified) is the cross-covariance `cov (W, V)'; the default
     value is `cov (W, V) = 0'.

     Observer structure is `dz/dt = A z + B u + k (y - C z - D u)'

     returns:

     K is observer gain:  `(A - K C)' is stable.

     P is solution of algebraic Riccati equation.

     E is the vector of closed loop poles of `(A - K C)'.

`lqr (A, B, Q, R, Z)'
`[K, P, E] = lqr (A, B, Q, R, Z)'
     Linear quadratic regulator design for the continuous time system

          dx
          -- = A x + B u
          dt

     to minimize the cost functional

                infinity
                /
            J = |  x' Q x + u' R u
               /
              t=0

     Z omitted or

                infinity
                /
            J = |  x' Q x + u' R u + 2 x' Z u
               /
              t=0

     Z included

     Returns:

     K is state feedback gain:  `(A - B K)' is stable.

     P is the stabilizing solution of appropriate algebraic Riccati
     equation.

     E is the vector of the closed loop poles of `(A - B K)'.

`lyap (A, B, C)'
     Solve the Lyapunov (or Sylvester) equation via the Bartels-Stewart
     algorithm (Communications of the ACM, 1972).

     If `(a, b, c)' are specified, then `lyap' returns the solution of
     the  Sylvester equation

          a x + x b + c = 0

     If only `(a, b)' are specified, then `lyap' returns the solution
     of the Lyapunov equation

          a' x + x a + b = 0

     If B is not square, then `lyap' returns the solution of either

          a' x + x a + b' b = 0

     or

          a x + x a' + b b' = 0

     whichever is appropriate.

     Solves by using the Bartels-Stewart algorithm (1972).

`tzero (A, B, C, D, BAL)'
     Compute the transmission zeros of [A, B, C, D].

     BAL = balancing option (see balance); default is `"B"'.

     Needs to incorporate `mvzero' algorithm to isolate finite zeros;
     see Hodel, `Computation of System Zeros with Balancing', Linear
     Algebra and its Applications, July 1993.


File: octave.info,  Node: Signal Processing,  Next: Sets,  Prev: Control Theory,  Up: Top

Signal Processing
*****************

   I hope that someday Octave will include more signal processing
functions.  If you would like to help improve Octave in this area,
please contact `bug-octave@che.utexas.edu'.

`fft (A)'
     Compute the FFT of A using subroutines from FFTPACK.

`fft2 (A)'
     Compute the two dimensional FFT of A.

`fftconv (A, B, N)'
     This function returns the convolution of the vectors A and B, a
     vector with length equal to the `length (a) + length (b) - 1'.  If
     A and B are the coefficient vectors of two polynomials, the
     returned value is the coefficient vector of the product polynomial.

     The computation uses the FFT by calling the function `fftfilt'.  If
     the optional argument N is specified, an N-point FFT is used.

`fftfilt (B, X, N)'
     With two arguments, `fftfilt' filters X with the FIR filter B
     using the FFT.

     Given the optional third argument, N, `fftfilt' uses the
     overlap-add method to filter X with B using an N-point FFT.

`filter (B, A, X)'
     This function returns the solution to the following linear,
     time-invariant difference equation:

             N                   M
            SUM a(k+1) y(n-k) + SUM b(k+1) x(n-k) = 0  for 1<=n<=length(x)
            k=0                 k=0

     where  N=length(a)-1 and M=length(b)-1.  An equivalent form of
     this equation is:

                    N                   M
            y(n) = SUM c(k+1) y(n-k) + SUM d(k+1) x(n-k)  for 1<=n<=length(x)
                   k=1                 k=0

     where  c = a/a(1) and d = b/a(1).

     In terms of the z-transform, y is the result of passing the
     discrete- time signal x through a system characterized by the
     following rational system function:

                       M
                      SUM d(k+1) z^(-k)
                      k=0
            H(z) = ----------------------
                         N
                    1 + SUM c(k+1) z(-k)
                        k=1

     When called as

          [y, sf] = filter (b, a, x, si)

     `filter' uses the argument SI as the initial state of the system
     and and returns the final state in SF.  The state vector is a
     column vector whose length is equal to the length of the longest
     coefficient vector minus one.  If SI is not set, the initial state
     vector is set to all zeros.

`freqz'
     Compute the frequency response of a filter.

     `[H, W] = freqz (B)' returns the complex frequency response H of
     the FIR filter with coefficients B. The response is evaluated at
     512 angular frequencies between 0 and  pi.

     The output value W is a vector containing the 512 frequencies.

     `[H, W] = freqz (B, A)' returns the complex frequency response of
     the rational IIR filter whose numerator has coefficients B and
     denominator coefficients A.

     `[H, W] = freqz (B, A, N)' returns the response evaluated at N
     angular frequencies.  For fastest computation n should factor into
     a small number of small primes.

     `[H, W] = freqz (B, A, N, "whole")' evaluates the response at n
     frequencies between 0 and  2*pi.

`ifft (A)'
     Compute the inverse FFT of A using subroutines from FFTPACK.

`ifft2'
     Compute the two dimensional inverse FFT of A.

`sinc (X)'
     Returns  sin(pi*x)/(pi*x).


File: octave.info,  Node: Sets,  Next: Statistics,  Prev: Signal Processing,  Up: Top

Sets
****

   Octave has a limited set of functions for managing sets of data,
where a set is defined as a collection unique elements.

   Given a matrix or vector of values, the function `create_set'
returns a row vector containing unique values, sorted in ascending
order.  For example, `create_set ([1, 2; 3, 4; 4, 2])' returns the
vector `[1, 2, 3, 4]'.

   The functions `union' and `intersection' take two sets as arguments
and return the union and interection, respectively.  For example,
`union ([1, 2, 3], [2, 3, 5])' returns the vector `[1, 2, 5]'.

   The function `complement (A, B)' returns the elements of set B that
are not in set A.  For example, `complement ([1, 2, 3], [2, 3, 5])'
returns the value `5'.


File: octave.info,  Node: Statistics,  Next: Plotting,  Prev: Sets,  Up: Top

Statistics
**********

   I hope that someday Octave will include more statistics functions.
If you would like to help improve Octave in this area, please contact
`bug-octave@che.utexas.edu'.

`corrcoef (X [, Y])'
     If each row of X and Y is an observation and each column is a
     variable, the (i,j)-th entry of `corrcoef (X, Y)' is the
     correlation between the i-th variable in X and the j-th variable
     in Y.  If invoked with one argument, compute `corrcoef (X, X)'.

`cov (X [, Y])'
     If each row of X and Y is an observation and each column is a
     variable, the (i,j)-th entry of `cov (X, Y)' is the covariance
     between the i-th variable in X and the j-th variable in Y.  If
     invoked with one argument, compute `cov (X, X)'.

`kurtosis (X)'
     If X is a vector of length N, return the kurtosis

          kurtosis(x) = N^(-1) std(x)^(-4) SUM_i (x(i)-mean(x))^4 - 3

     of X.  If X is a matrix, return the row vector containing the
     kurtosis of each column.

`mahalanobis (X, Y)'
     Returns Mahalanobis' D-square distance between the multivariate
     samples X and Y, which must have the same number of components
     (columns), but may have a different number of observations (rows).

`mean (A)'
     If A is a vector, compute the mean of the elements of A.  If A is
     a matrix, compute the mean for each column and return them in a
     row vector.

`median (A)'
     If A is a vector, compute the median value of the elements of A.
     If A is a matrix, compute the median value for each column and
     return them in a row vector.

`skewness (X)'
     If X is a vector of length N, return the skewness

          skewness (x) = N^(-1) std(x)^(-3) SUM_i (x(i)-mean(x))^3

     of X.  If X is a matrix, return the row vector containing the
     skewness of each column.

`std (A)'
     If A is a vector, compute the standard deviation of the elements
     of A.  If A is a matrix, compute the standard deviation for each
     column and return them in a row vector.


File: octave.info,  Node: Plotting,  Next: Image Processing,  Prev: Statistics,  Up: Top

Plotting
********

   All of Octave's plotting functions use `gnuplot' to handle the
actual graphics.  There are two low-level functions, `gplot' and
`gsplot', that behave almost exactly like the corresponding `gnuplot'
functions `plot' and `splot'.  A number of other higher level plotting
functions, patterned after the graphics functions found in MATLAB
version 3.5, are also available.  These higher level functions are all
implemented in terms of the two low-level plotting functions.

* Menu:

* Two-Dimensional Plotting::
* Three-Dimensional Plotting::
* Miscellaneous Plotting Functions::


File: octave.info,  Node: Two-Dimensional Plotting,  Next: Three-Dimensional Plotting,  Prev: Plotting,  Up: Plotting

Two-Dimensional Plotting
========================

   The syntax for Octave's two-dimensional plotting function, `gplot',
is

     gplot RANGES EXPRESSION USING TITLE STYLE

where the RANGES, USING, TITLE, and STYLE arguments are optional, and
the USING, TITLE and STYLE qualifiers may appear in any order after the
expression.  You may plot multiple expressions with a single command by
separating them with commas.  Each expression may have its own set of
qualifiers.

   The optional item RANGES has the syntax

     [ x_lo : x_up ] [ y_lo : y_up ]

and may be used to specify the ranges for the axes of the plot,
independent of the actual range of the data.  The range for the y axes
and any of the individual limits may be omitted.  A range `[:]'
indicates that the default limits should be used.  This normally means
that a range just large enough to include all the data points will be
used.

   The expression to be plotted must not contain any literal matrices
(e.g. `[ 1, 2; 3, 4 ]') since it is nearly impossible to distinguish a
plot range from a matrix of data.

   See the help for `gnuplot' for a description of the syntax for the
optional items.

   By default, the `gplot' command plots the second column of a matrix
versus the first.  If the matrix only has one column, it is taken as a
vector of y-coordinates and the x-coordinate is taken as the element
index, starting with zero.  For example,

     gplot rand (100,1) with linespoints

will plot 100 random values and connect them with lines.  When `gplot'
is used to plot a column vector, the indices of the elements are taken
as x values.

   If there are more than two columns, you can choose which columns to
plot with the USING qualifier. For example, given the data

     x = (-10:0.1:10)';
     data = [x, sin(x), cos(x)];

the command

     gplot [-11:11] [-1.1:1.1] data with lines, data using 1:3 with impulses

will plot two lines.  The first line is generated by the command `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 USING qualifier.

   The clause `using 1:3' in the second part of this plot command
specifies that the first and third columns of the matrix `data' should
be taken as the values to plot.

   In this example, the ranges have been explicitly specified to be a
bit larger than the actual range of the data so that the curves do not
touch the border of the plot.

   In addition to the basic plotting commands, the whole range of `set'
and `show' commands from `gnuplot' are available, as is `replot'.

   The `set' and `show' commands allow you to set and show `gnuplot'
parameters.  For more information about the set and show commands, see
the `gnuplot' user's guide (also available on line if you run `gnuplot'
directly, instead of running it from Octave).

   The `replot' command allows you to force the plot to be redisplayed.
This is useful if you have changed something about the plot, such as
the title or axis labels.  The `replot' command also accepts the same
arguments as `gplot' or `gsplot' (except for data ranges) so you can
add additional lines to existing plots.

   For example,

     set term tek40
     set output "/dev/plotter"
     set title "sine with lines and cosine with impulses"
     replot "sin (x) w l"

   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 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 lines with a replot command, gnuplot always redraws
the entire plot, and you probably don't want to have a completely new
plot generated every time something as minor as an axis label changes.

   Since this may not matter as much on faster terminals, you can tell
Octave to redisplay the plot each time anything about it changes by
setting the value of the builtin variable `automatic_replot' to the
value `"true"'.

   Note that NaN values in the plot data are automatically omitted, and
Inf values are converted to a very large value before calling gnuplot.

   The MATLAB-style two-dimensional plotting commands are:

`plot (ARGS)'
     This function produces two-dimensional plots.  Many different
     combinations of arguments are possible.  The simplest form is

          plot (y)

     where the argument is taken as the set of Y coordinates and the X
     coordinates are taken to be the indices of the elements, starting
     with 1.

     If more than one argument is given, they are interpreted as

          plot (x [, y] [, fmt] ...)

     where Y and FMT are optional, and any number of argument sets may
     appear.  The X and Y values are interpreted as follows:

        * If a single data argument is supplied, it is taken as the set
          of Y coordinates and the X coordinates are taken to be the
          indices of the elements, starting with 1.

        * If the first argument is a vector and the second is a matrix,
          the the vector is plotted versus the columns (or rows) of the
          matrix.  (using whichever combination matches, with columns
          tried first.)

        * If the first argument is a matrix and the second is a vector,
          the the columns (or rows) of the matrix are plotted versus
          the vector.  (using whichever combination matches, with
          columns tried first.)

        * If both arguments are vectors, the elements of Y are plotted
          versus the elements of X.

        * If both arguments are matrices, the columns of Y are plotted
          versus the columns of X.  In this case, both matrices must
          have the same number of rows and columns and no attempt is
          made to transpose the arguments to make the number of rows
          match.

          If both arguments are scalars, a single point is plotted.

     The FMT argument, if present is interpreted as follows.  If FMT is
     missing, the default gnuplot line style is assumed.

    `-'
          Set lines plot style (default).

    `.'
          Set dots plot style.

    `@'
          Set points plot style.

    `-@'
          Set linespoints plot style.

    `^'
          Set impulses plot style.

    `L'
          Set steps plot style.

    `#'
          Set boxes plot style.

    `~'
          Set errorbars plot style.

    `#~'
          Set boxerrorbars plot style.

    `n'
          Interpreted as the plot color if N is an integer in the range
          1 to 6.

    `nm'
          If NM is a two digit integer and M is an integer in the range
          1 to 6, M is interpreted as the point style.  This is only
          valid in combination with the `@' or `-@' specifiers.

    `c'
          If C is one of "R", "G", "B", "M", "C", or "W", it is
          interpreted as the plot color (red, green, blue, magenta,
          cyan, or white).

    `+'
    `*'
    `o'
    `x'
          Used in combination with the points or linespoints styles,
          set the point style.

     The color line styles have the following meanings on terminals that
     support color.

          Number  Gnuplot colors  (lines)points style
            1       red                   *
            2       green                 +
            3       blue                  o
            4       magenta               x
            5       cyan                house
            6       brown            there exists

     Here are some plot examples:

          plot (x, y, "@12", x, y2, x, y3, "4", x, y4, "+")

     This command will plot Y with points of type 2 (displayed as `+')
     and color 1 (red), Y2 with lines, Y3 with lines of color 4
     (magenta) and Y4 with points displayed as `+'.

          plot (b, "*")

     This command will plot the data in B will be plotted with points
     displayed as `*'.

`hold'
     Tell Octave to `hold' the current data on the plot when executing
     subsequent plotting commands.  This allows you to execute a series
     of plot commands and have all the lines end up on the same figure.
     The default is for each new plot command to clear the plot device
     first.  For example, the command

          hold on

     turns the hold state on.  An argument of `off' turns the hold state
     off, and `hold' with no arguments toggles the current hold state.

`ishold'
     Returns 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.

`loglog (ARGS)'
     Make a two-dimensional plot using log scales for both axes.  See
     the description of `plot' above for a description of the arguments
     that `loglog' will accept.

`semilogx (ARGS)'
     Make a two-dimensional plot using a log scale for the X axis.  See
     the description of `plot' above for a description of the arguments
     that `semilogx' will accept.

`semilogy (ARGS)'
     Make a two-dimensional plot using a log scale for the Y axis.  See
     the description of `plot' above for a description of the arguments
     that `semilogy' will accept.

`contour (Z, N, X, Y)'
     Make a contour plot of the three-dimensional surface described by
     Z.  Someone needs to improve `gnuplot''s contour routines before
     this will be very useful.

`polar (THETA, RHO)'
     Make a two-dimensional plot given polar the coordinates THETA and
     RHO.


File: octave.info,  Node: Three-Dimensional Plotting,  Next: Miscellaneous Plotting Functions,  Prev: Two-Dimensional Plotting,  Up: Plotting

Three-Dimensional Plotting
==========================

   The syntax for Octave's three-dimensional plotting function,
`gsplot', is

     gsplot RANGES EXPRESSION USING TITLE STYLE

where the RANGES, USING, TITLE, and STYLE arguments are optional, and
the USING, TITLE and STYLE qualifiers may appear in any order after the
expression.  You may plot multiple expressions with a single command by
separating them with commas.  Each expression may have its own set of
qualifiers.

   The optional item RANGES has the syntax

     [ x_lo : x_up ] [ y_lo : y_up ] [ z_lo : z_up ]

and may be used to specify the ranges for the axes of the plot,
independent of the actual range of the data.  The range for the y and z
axes and any of the individual limits may be omitted.  A range `[:]'
indicates that the default limits should be used.  This normally means
that a range just large enough to include all the data points will be
used.

   The expression to be plotted must not contain any literal matrices
(e.g.  `[ 1, 2; 3, 4 ]') since it is nearly impossible to distinguish a
plot range from a matrix of data.

   See the help for `gnuplot' for a description of the syntax for the
optional items.

   By default, the `gsplot' command plots each column of the expression
as the z value, using the row index as the x value, and the column
index as the y value.  The indices are counted from zero, not one.  For
example,

     gsplot rand (5, 2)

will plot a random surface, with the x and y values taken from the row
and column indices of the matrix.

   If parametric plotting mode is set (using the command `set
parametric', then `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 `parametric' set, it makes sense to plot a
matrix like

     1 1 3 2 1 6 3 1 9
     1 2 2 2 2 5 3 2 8
     1 3 1 2 3 4 3 3 7

but not `rand (5, 30)'.

   The MATLAB-style three-dimensional plotting commands are:

`mesh (X, Y, Z)'
     Plot a mesh given matrices `x', and Y from `meshdom' and a matrix
     Z corresponding to the X and Y coordinates of the mesh.

`meshdom (X, Y)'
     Given vectors of X and Y coordinates, return two matrices
     corresponding to the X and Y coordinates of the mesh.

     See the file `sombrero.m' for an example of using `mesh' and
     `meshdom'.


File: octave.info,  Node: Miscellaneous Plotting Functions,  Prev: Three-Dimensional Plotting,  Up: Plotting

Miscellaneous Plotting Functions
================================

`bar (X, Y)'
     Given two vectors of x-y data, `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,

          bar (x, y);

     and

          [xb, yb] = bar (x, y);
          plot (xb, yb);

     are equivalent.

`grid'
     For two-dimensional plotting, force the display of a grid on the
     plot.

`stairs (X, 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,

          stairs (x, y);

     and

          [xs, ys] = stairs (x, y);
          plot (xs, ys);

     are equivalent.

`title (STRING)'
     Specify a title for the plot.  If you already have a plot
     displayed, use the command `replot' to redisplay it with the new
     title.

`xlabel (STRING)'
`ylabel (STRING)'
     Specify x and y axis labels for the plot.  If you already have a
     plot displayed, use the command `replot' to redisplay it with the
     new labels.

`sombrero (N)'
     Display a classic three-dimensional mesh plot.  The parameter N
     allows you to increase the resolution.

`clearplot'
`clg'
     Clear the plot window and any titles or axis labels.  The name
     `clg' is aliased to `clearplot' for compatibility with MATLAB.

     The commands `gplot clear', `gsplot clear', and `replot clear' are
     equivalent to `clearplot'.  (Previously, commands like `gplot
     clear' would evaluate `clear' as an ordinary expression and clear
     all the visible variables.)

`closeplot'
     Close stream to the `gnuplot' subprocess.  If you are using X11,
     this will close the plot window.

`purge_tmp_files'
     Delete the temporary files created by the plotting commands.

     Octave creates temporary data files for `gnuplot' and then sends
     commands to `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.

`axis (LIMITS)'
     Sets the axis limits for plots.

     The argument 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 second and third specify the limits for the y
     axis, and the fourth and fifth specify the limits for the z axis.

     With no arguments, `axis' turns autoscaling on.

     If your plot is already drawn, then you need to use `replot' before
     the new axis limits will take effect.  You can get this to happen
     automatically by setting the built-in variable `automatic_replot'
     to `"true"'.  *Note User Preferences::.

`hist (Y, 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 NN and XX such that
     `bar (XX, NN)' will plot the histogram.


File: octave.info,  Node: Image Processing,  Next: Input and Output,  Prev: Plotting,  Up: Top

Image Processing
****************

   To display images using these functions, you must be using Octave
with the X Window System, and you must have either `xloadimage' or `xv'
installed.  You do not need to be running X in order to manipulate
images, however, so some of these functions may be useful even if you
are not able to view the results.

`colormap'
     Set the current colormap.

     `colormap (MAP)' sets the current colormap to MAP.  The color map
     should be an N row by 3 column matrix.  The columns contain red,
     green, and blue intensities respectively.  All entries should be
     between 0 and 1 inclusive.  The new colormap is returned.

     `colormap ("default")' restores the default colormap (a gray scale
     colormap with 64 entries).  The default colormap is returned.

     With no arguments, `colormap' returns the current color map.

`gray (N)'
     Create a gray colormap with values from 0 to N.  The argument N
     should be a scalar.  If it is omitted, 64 is assumed.

`gray2ind'
     Convert a gray scale intensity image to an Octave indexed image.

`image'
     Display an Octave image matrix.

     `image (X)' displays a matrix as a color image.  The elements of X
     are indices into the current colormap and should have values
     between 1 and the length of the colormap.

     `image (X, ZOOM)' changes the zoom factor.  The default value is 4.

`imagesc'
     Scale and display a matrix as an image.

     `imagesc (X)' displays a scaled version of the matrix X.  The
     matrix is scaled so that its entries are indices into the current
     colormap.  The scaled matrix is returned.

     `imagesc (X, ZOOM)' sets the magnification, the default value is 4.

`imshow'
     Display images.

     `imshow (X)' displays an indexed image using the current colormap.

     `imshow (X, MAP)' displays an indexed image using the specified
     colormap.

     `imshow (I, N)' displays a gray scale intensity image.

     `imshow (R, G, B)' displays an RGB image.

`ind2gray'
     Convert an Octave indexed image to a gray scale intensity image.

     `Y = ind2gray (X)' converts an indexed image to a gray scale
     intensity image.  The current colormap is used to determine the
     intensities.  The intensity values lie between 0 and 1 inclusive.

     `Y = ind2gray (X, MAP)' uses the specified colormap instead of the
     current one in the conversion process.

`ind2rgb'
     Convert an indexed image to red, green, and blue color components.

     `[R, G, B] = ind2rgb (X)' uses the current colormap for the
     conversion.

     `[R, G, B] = ind2rgb (X, MAP)' uses the specified colormap.

`loadimage'
     Load an image file.

     `[X, MAP] = loadimage (FILE)' loads an image and it's associated
     color map from the specified FILE.  The image must be stored in
     Octave's image format.

`ocean (N)'
     Create color colormap.  The argument N should be a scalar.  If it
     is omitted, 64 is assumed.

`rgb2ind'
     Convert and RGB image to an Octave indexed image.

     `[X, MAP] = rgb2ind (R, G, B)'

`saveimage'
     Save a matrix to disk in image format.

     `saveimage (FILE, X)' saves matrix X to FILE in Octave's image
     format.  The current colormap is also saved in the file.

     `saveimage (FILE, X, "img")' saves the image in the default format
     and is the same as `saveimage (FILE, X)'.

     `saveimage (FILE, X, "ppm")' saves the image in ppm format instead
     of the default Octave image format.

     `saveimage (FILE, X, "ps")' saves the image in PostScript format
     instead of the default Octave image format.  (Note: images saved
     in PostScript format can not be read back into Octave with
     loadimage.)

     `saveimage (FILE, X, FMT, MAP)' saves the image along with the
     specified colormap in the specified format.

     Note: if the colormap contains only two entries and these entries
     are black and white, the bitmap ppm and PostScript formats are
     used.  If the image is a gray scale image (the entries within each
     row of the colormap are equal) the gray scale ppm and PostScript
     image formats are used, otherwise the full color formats are used.


File: octave.info,  Node: Input and Output,  Next: Special Matrices,  Prev: Image Processing,  Up: Top

Input and Output
****************

   There are two distinct classes of input and output functions.  The
first set are modeled after the functions available in MATLAB.  The
second set are modeled after the standard I/O library used by the C
programming language.  The C-style I/O functions offer more flexibility
and control over the output, but are not quite as easy to use as the
simpler MATLAB-style I/O functions.

   When running interactively, Octave normally sends any output intended
for your terminal that is more than one screen long to a paging program,
such as `less' or `more'.  This avoids the problem of having a large
volume of output stream by before you can read it.  With `less' (and
some versions of `more') it also allows you to scan forward and
backward, and search for specific items.

   No output is displayed by the pager until just before Octave is
ready to print the top level prompt, or read from the standard input
using the `fscanf' or `scanf' functions.  This means that there may be
some delay before any output appears on your screen if you have asked
Octave to perform a significant amount of work with a single command
statement.  The function `fflush' may be used to force output to be
sent to the pager immediately.  *Note C-Style I/O Functions::.

   You can select the program to run as the pager by setting the
variable `PAGER', and you can turn paging off by setting the value of
the variable `page_screen_output' to the string `"false"'.  *Note User
Preferences::.

* Menu:

* Basic Input and Output::
* C-Style I/O Functions::

