Mercurial > hg > octave-nkf
diff doc/interpreter/numbers.txi @ 3294:bfe1573bd2ae
[project @ 1999-10-19 10:06:07 by jwe]
author | jwe |
---|---|
date | Tue, 19 Oct 1999 10:08:42 +0000 |
parents | |
children | 6923abb04e16 |
line wrap: on
line diff
new file mode 100644 --- /dev/null +++ b/doc/interpreter/numbers.txi @@ -0,0 +1,571 @@ +@c Copyright (C) 1996, 1997 John W. Eaton +@c This is part of the Octave manual. +@c For copying conditions, see the file gpl.texi. + +@node Numeric Data Types, Strings, Data Types, Top +@chapter Numeric Data Types +@cindex numeric constant +@cindex numeric value + +A @dfn{numeric constant} may be a scalar, a vector, or a matrix, and it +may contain complex values. + +The simplest form of a numeric constant, a scalar, is a single number +that can be an integer, a decimal fraction, a number in scientific +(exponential) notation, or a complex number. Note that all numeric +constants are represented within Octave in double-precision floating +point format (complex constants are stored as pairs of double-precision +floating point values). Here are some examples of real-valued numeric +constants, which all have the same value: + +@example +@group +105 +1.05e+2 +1050e-1 +@end group +@end example + +To specify complex constants, you can write an expression of the form + +@example +@group +3 + 4i +3.0 + 4.0i +0.3e1 + 40e-1i +@end group +@end example + +all of which are equivalent. The letter @samp{i} in the previous example +stands for the pure imaginary constant, defined as +@iftex +@tex + $\sqrt{-1}$. +@end tex +@end iftex +@ifinfo + @code{sqrt (-1)}. +@end ifinfo + +For Octave to recognize a value as the imaginary part of a complex +constant, a space must not appear between the number and the @samp{i}. +If it does, Octave will print an error message, like this: + +@example +@group +octave:13> 3 + 4 i + +parse error: + + 3 + 4 i + ^ +@end group +@end example + +You may also use @samp{j}, @samp{I}, or @samp{J} in place of the +@samp{i} above. All four forms are equivalent. + +@menu +* Matrices:: +* Ranges:: +* Predicates for Numeric Objects:: +@end menu + +@node Matrices, Ranges, Numeric Data Types, Numeric Data Types +@section Matrices +@cindex matrices + +@opindex [ +@opindex ] +@opindex ; +@opindex , + +It is easy to define a matrix of values in Octave. The size of the +matrix is determined automatically, so it is not necessary to explicitly +state the dimensions. The expression + +@example +a = [1, 2; 3, 4] +@end example + +@noindent +results in the matrix +@iftex +@tex +$$ a = \left[ \matrix{ 1 & 2 \cr 3 & 4 } \right] $$ +@end tex +@end iftex +@ifinfo + +@example +@group + + / \ + | 1 2 | + a = | | + | 3 4 | + \ / + +@end group +@end example +@end ifinfo + +Elements of a matrix may be arbitrary expressions, provided that the +dimensions all make sense when combining the various pieces. For +example, given the above matrix, the expression + +@example +[ a, a ] +@end example + +@noindent +produces the matrix + +@example +@group +ans = + + 1 2 1 2 + 3 4 3 4 +@end group +@end example + +@noindent +but the expression + +@example +[ a, 1 ] +@end example + +@noindent +produces the error + +@example +error: number of rows must match near line 13, column 6 +@end example + +@noindent +(assuming that this expression was entered as the first thing on line +13, of course). + +Inside the square brackets that delimit a matrix expression, Octave +looks at the surrounding context to determine whether spaces and newline +characters should be converted into element and row separators, or +simply ignored, so commands like + +@example +[ linspace (1, 2) ] +@end example + +@noindent +and + +@example +@group +a = [ 1 2 + 3 4 ] +@end group +@end example + +@noindent +will work. However, some possible sources of confusion remain. For +example, in the expression + +@example +[ 1 - 1 ] +@end example + +@noindent +the @samp{-} is treated as a binary operator and the result is the +scalar 0, but in the expression + +@example +[ 1 -1 ] +@end example + +@noindent +the @samp{-} is treated as a unary operator and the result is the +vector @code{[ 1, -1 ]}. + +Given @code{a = 1}, the expression + +@example +[ 1 a' ] +@end example + +@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 +expression + +@example +[ 1 a ' ] +@end example + +@noindent +produces the error message + +@example +error: unterminated string constant +@end example + +@noindent +because to not do so would make it impossible to correctly parse the +valid expression + +@example +[ a 'foo' ] +@end example + +For clarity, it is probably best to always use commas and semicolons to +separate matrix elements and rows. It is possible to enforce this style +by setting the built-in variable @code{whitespace_in_literal_matrix} to +@code{"ignore"}. + +@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 +@code{[m (1)]} or + +@example +[ 1, 2, + 3, 4 ] +@end example + +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 @code{[1 2]} will result in an error +instead of being treated the same as @code{[1, 2]}, and the expression + +@example +[ 1, 2, + 3, 4 ] +@end example + +@noindent +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 +example, given the matrix + +@example +m = [3 2] +@end example + +@noindent +the expression + +@example +[m (1)] +@end example + +@noindent +will be parsed as + +@example +[m, (1)] +@end example + +@noindent +and will result in + +@example +[3 2 1] +@end example + +@noindent +and the expression + +@example +[ 1, 2, + 3, 4 ] +@end example + +@noindent +will result in a matrix because the newline character is converted to a +semicolon (row separator) even though there is a comma at the end of the +first line (trailing commas or semicolons are ignored). This is +apparently how @sc{Matlab} behaves. + +Any other value for @code{whitespace_in_literal_matrix} results in behavior +that is the same as traditional, except that Octave does not +convert spaces to a comma between identifiers and @samp{(}. For +example, the expression + +@example +[m (1)] +@end example + +will produce @samp{3}. This is the way Octave has always behaved. +@end defvr + +When you type a matrix or the name of a variable whose value is a +matrix, Octave responds by printing the matrix in with neatly aligned +rows and columns. If the rows of the matrix are too large to fit on the +screen, Octave splits the matrix and displays a header before each +section to indicate which columns are being displayed. You can use the +following variables to control the format of the output. + +@defvr {Built-in Variable} output_max_field_width +This variable specifies the maximum width of a numeric output field. +The default value is 10. +@end defvr + +@defvr {Built-in Variable} output_precision +This variable specifies the minimum number of significant figures to +display for numeric output. The default value is 5. +@end defvr + +It is possible to achieve a wide range of output styles by using +different values of @code{output_precision} and +@code{output_max_field_width}. Reasonable combinations can be set using +the @code{format} function. @xref{Basic Input and Output}. + +@defvr {Built-in Variable} split_long_rows +For large matrices, Octave may not be able to display all the columns of +a given row on one line of your screen. This can result in missing +information or output that is nearly impossible to decipher, depending +on whether your terminal truncates or wraps long lines. + +If the value of @code{split_long_rows} is nonzero, Octave will display +the matrix in a series of smaller pieces, each of which can fit within +the limits of your terminal width. Each set of rows is labeled so that +you can easily see which columns are currently being displayed. +For example: + +@smallexample +@group +octave:13> rand (2,10) +ans = + + Columns 1 through 6: + + 0.75883 0.93290 0.40064 0.43818 0.94958 0.16467 + 0.75697 0.51942 0.40031 0.61784 0.92309 0.40201 + + Columns 7 through 10: + + 0.90174 0.11854 0.72313 0.73326 + 0.44672 0.94303 0.56564 0.82150 +@end group +@end smallexample + +@noindent +The default value of @code{split_long_rows} is nonzero. +@end defvr + +Octave automatically switches to scientific notation when values become +very large or very small. This guarantees that you will see several +significant figures for every value in a matrix. If you would prefer to +see all values in a matrix printed in a fixed point format, you can set +the built-in variable @code{fixed_point_format} to a nonzero value. But +doing so is not recommended, because it can produce output that can +easily be misinterpreted. + +@defvr {Built-in Variable} fixed_point_format +If the value of this variable is nonzero, Octave will scale all values +in a matrix so that the largest may be written with one leading digit. +The scaling factor is printed on the first line of output. For example, + +@example +@group +octave:1> logspace (1, 7, 5)' +ans = + + 1.0e+07 * + + 0.00000 + 0.00003 + 0.00100 + 0.03162 + 1.00000 +@end group +@end example + +@noindent +Notice that first value appears to be zero when it is actually 1. For +this reason, you should be careful when setting +@code{fixed_point_format} to a nonzero value. + +The default value of @code{fixed_point_format} is 0. +@end defvr + +@menu +* Empty Matrices:: +@end menu + +@node Empty Matrices, , Matrices, Matrices +@subsection Empty Matrices + +A matrix may have one or both dimensions zero, and operations on empty +matrices are handled as described by Carl de Boor in @cite{An Empty +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. +@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: + +@example +@group +s * [](mxn) = [](mxn) * s = [](mxn) + + [](mxn) + [](mxn) = [](mxn) + + [](0xm) * M(mxn) = [](0xn) + + M(mxn) * [](nx0) = [](mx0) + + [](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{[]}. 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 +dimensions of empty matrices are printed along with the empty matrix +symbol, @samp{[]}. For example, the expression + +@example +zeros (3, 0) +@end example + +@noindent +will print + +@example +ans = [](3x0) +@end example +@end defvr + +Empty matrices may also be used in assignment statements as a convenient +way to delete rows or columns of matrices. +@xref{Assignment Ops, ,Assignment Expressions}. + +Octave will normally issue a warning if it finds an empty matrix in the +list of elements that make up another matrix. You can use the variable +@code{empty_list_elements_ok} to suppress the warning or to treat it as +an error. + +@defvr {Built-in Variable} empty_list_elements_ok +This variable controls whether Octave ignores empty matrices in a matrix +list. + +For example, if the value of @code{empty_list_elements_ok} is +nonzero, Octave will ignore the empty matrices in the expression + +@example +a = [1, [], 3, [], 5] +@end example + +@noindent +and the variable @code{a} will be assigned the value @code{[ 1, 3, 5 ]}. + +The default value is @code{"warn"}. +@end defvr + +When Octave parses a matrix expression, it examines the elements of the +list to determine whether they are all constants. If they are, it +replaces the list with a single matrix constant. + +@defvr {Built-in Variable} propagate_empty_matrices +If the value of @code{propagate_empty_matrices} is nonzero, +functions like @code{inverse} and @code{svd} will return an empty matrix +if they are given one as an argument. The default value is 1. +@end defvr + +@node Ranges, Predicates for Numeric Objects, Matrices, Numeric Data Types +@section Ranges +@cindex range expressions +@cindex expression, range + +@opindex : + +A @dfn{range} is a convenient way to write a row vector with evenly +spaced elements. A range expression is defined by the value of the first +element in the range, an optional value for the increment between +elements, and a maximum value which the elements of the range will not +exceed. The base, increment, and limit are separated by colons (the +@samp{:} character) and may contain any arithmetic expressions and +function calls. If the increment is omitted, it is assumed to be 1. +For example, the range + +@example +1 : 5 +@end example + +@noindent +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 ]}. + +Although a range constant specifies a row vector, Octave does @emph{not} +convert range constants to vectors unless it is necessary to do so. +This allows you to write a constant like @samp{1 : 10000} without using +80,000 bytes of storage on a typical 32-bit workstation. + +Note that the upper (or lower, if the increment is negative) bound on +the range is not always included in the set of values, and that ranges +defined by floating point values can produce surprising results because +Octave uses floating point arithmetic to compute the values in the +range. If it is important to include the endpoints of a range and the +number of elements is known, you should use the @code{linspace} function +instead (@pxref{Special Utility Matrices}). + +When Octave parses a range expression, it examines the elements of the +expression to determine whether they are all constants. If they are, it +replaces the range expression with a single range constant. + +@node Predicates for Numeric Objects, , Ranges, Numeric Data Types +@section Predicates for Numeric Objects + +@deftypefn {Function File} {} is_matrix (@var{a}) +Return 1 if @var{a} is a matrix. Otherwise, return 0. +@end deftypefn + +@deftypefn {Function File} {} is_vector (@var{a}) +Return 1 if @var{a} is a vector. Otherwise, return 0. +@end deftypefn + +@deftypefn {Function File} {} is_scalar (@var{a}) +Return 1 if @var{a} is a scalar. Otherwise, return 0. +@end deftypefn + +@deftypefn {Function File} {} is_square (@var{x}) +If @var{x} is a square matrix, then return the dimension of @var{x}. +Otherwise, return 0. +@end deftypefn + +@deftypefn {Function File} {} is_symmetric (@var{x}, @var{tol}) +If @var{x} is symmetric within the tolerance specified by @var{tol}, +then return the dimension of @var{x}. Otherwise, return 0. If +@var{tol} is omitted, use a tolerance equal to the machine precision. +@end deftypefn