User manual | 5_MATLAB_Function_vol_1_(A

MATLAB
®
The Language of Technical Computing
Computation
Visualization
Programming
MATLAB Function Reference
Volume 1: A - E
Version 6
How to Contact The MathWorks:
www.mathworks.com
comp.soft-sys.matlab
Web
Newsgroup
[email protected]
Technical support
Product enhancement suggestions
Bug reports
Documentation error reports
Order status, license renewals, passcodes
Sales, pricing, and general information
508-647-7000
Phone
508-647-7001
Fax
The MathWorks, Inc.
3 Apple Hill Drive
Natick, MA 01760-2098
Mail
[email protected]
[email protected]
[email protected]
[email protected]
[email protected]
For contact information about worldwide offices, see the MathWorks Web site.
MATLAB Function Reference Volume 1: A - E
 COPYRIGHT 1984 - 2002 by The MathWorks, Inc.
The software described in this document is furnished under a license agreement. The software may be used
or copied only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form without prior written consent from The MathWorks, Inc.
FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by
or for the federal government of the United States. By accepting delivery of the Program, the government
hereby agrees that this software qualifies as "commercial" computer software within the meaning of FAR
Part 12.212, DFARS Part 227.7202-1, DFARS Part 227.7202-3, DFARS Part 252.227-7013, and DFARS Part
252.227-7014. The terms and conditions of The MathWorks, Inc. Software License Agreement shall pertain
to the government’s use and disclosure of the Program and Documentation, and shall supersede any
conflicting contractual terms or conditions. If this license fails to meet the government’s minimum needs or
is inconsistent in any respect with federal procurement law, the government agrees to return the Program
and Documentation, unused, to MathWorks.
MATLAB, Simulink, Stateflow, Handle Graphics, and Real-Time Workshop are registered trademarks, and
TargetBox is a trademark of The MathWorks, Inc.
Other product or brand names are trademarks or registered trademarks of their respective holders.
Printing History: December 1996
June 1997
October 1997
January 1999
June 1999
June 2001
July 2002
First printing
Online only
Online only
Online only
Second printing
Online only
Online only
For MATLAB 5
Revised for 5.1
Revised for 5.2
Revised for Release 11
For Release 11
Revised for 6.1
Revised for 6.5 (Release 13)
Contents
Functions – By Category
1
Development Environment . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Starting and Quitting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Command Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Getting Help . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Workspace, File, and Search Path . . . . . . . . . . . . . . . . . . . . . . .
Programming Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Performance Improvement Tools and Techniques . . . . . . . . . .
1-2
1-2
1-2
1-3
1-3
1-4
1-5
1-5
Mathematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6
Arrays and Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-7
Linear Algebra . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-9
Elementary Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-11
Data Analysis and Fourier Transforms . . . . . . . . . . . . . . . . . . 1-13
Polynomials . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-14
Interpolation and Computational Geometry . . . . . . . . . . . . . . 1-15
Coordinate System Conversion . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Nonlinear Numerical Methods . . . . . . . . . . . . . . . . . . . . . . . . . 1-16
Specialized Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Sparse Matrices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-18
Math Constants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-20
Programming and Data Types . . . . . . . . . . . . . . . . . . . . . . . .
Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Arrays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Operators and Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Programming in MATLAB . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-21
1-21
1-25
1-27
1-29
File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Filename Construction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Opening, Loading, Saving Files . . . . . . . . . . . . . . . . . . . . . . . .
Low-Level File I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Text Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
XML Documents . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-34
1-34
1-34
1-35
1-35
1-35
i
Spreadsheets . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Scientific Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Audio and Audio/Video . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-35
1-36
1-36
1-37
Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Basic Plots and Graphs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Annotating Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Specialized Plotting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Bit-Mapped Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Printing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Handle Graphics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-38
1-38
1-38
1-39
1-41
1-41
1-42
3-D Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Surface and Mesh Plots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
View Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Lighting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Transparency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Volume Visualization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1-44
1-44
1-45
1-46
1-47
1-47
Creating Graphical User Interfaces . . . . . . . . . . . . . . . . . . . .
Predefined Dialog Boxes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Deploying User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Developing User Interfaces . . . . . . . . . . . . . . . . . . . . . . . . . . . .
User Interface Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Finding Objects from Callbacks . . . . . . . . . . . . . . . . . . . . . . . .
GUI Utility Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
Controlling Program Execution . . . . . . . . . . . . . . . . . . . . . . . . .
1-48
1-48
1-49
1-49
1-49
1-49
1-49
1-50
Functions – Alphabetical List
2
Index
ii
Contents
1
Functions – By Category
The MATLAB Function Reference contains descriptions of all MATLAB commands and functions.
Select a category from the following table to see a list of related functions.
Development Environment
Startup, Command Window, help, editing and debugging, other
general functions
Mathematics
Arrays and matrices, linear algebra, data analysis, other areas of
mathematics
Programming and Data
Types
Function/expression evaluation, program control, function handles,
object oriented programming, error handling, operators, data types,
dates and times, timers
File I/O
General and low-level file I/O, plus specific file formats, like audio,
spreadsheet, HDF, images
Graphics
Line plots, annotating graphs, specialized plots, images, printing,
Handle Graphics
3-D Visualization
Surface and mesh plots, view control, lighting and transparency,
volume visualization.
Creating Graphical User
Interface
GUIDE, programming graphical user interfaces.
External Interfaces
Java, COM, Serial Port functions.
See Simulink, Stateflow, Real-Time Workshop, and the individual toolboxes for lists of their functions
1
Functions – By Category
Development Environment
General functions for working in MATLAB, including functions for startup,
Command Window, help, and editing and debugging.
“Starting and Quitting”
Startup and shutdown options
“Command Window”
Controlling Command Window
“Getting Help”
Finding information
“Workspace, File, and
Search Path”
File, search path, variable management
“Programming Tools”
Editing and debugging, source control, Notebook
“System”
Identifying current computer, license, product
version, and more
“Performance
Improvement Tools and
Techniques”
Improving and assessing performance, e.g.,
profiling and memory use
Starting and Quitting
exit
finish
matlab
matlabrc
quit
startup
Terminate MATLAB (same as quit)
MATLAB termination M-file
Start MATLAB (UNIX systems only)
MATLAB startup M-file for single user systems or
administrators
Terminate MATLAB
MATLAB startup M-file for user-defined options
Command Window
clc
diary
dos
format
home
more
notebook
system
unix
1-2
Clear Command Window
Save session to file
Execute DOS command and return result
Control display format for output
Move cursor to upper left corner of Command Window
Control paged output for Command Window
Open M-book in Microsoft Word (Windows only)
Execute operating system command and return result
Execute UNIX command and return result
Development Environment
Getting Help
doc
demo
docopt
help
helpbrowser
helpwin
info
lookfor
support
web
whatsnew
Display online documentation in MATLAB Help browser
Access product demos via Help browser
Location of help file directory for UNIX platforms
Display help for MATLAB functions in Command Window
Display Help browser for access to extensive online help
Display M-file help, with access to M-file help for all functions
Display information about The MathWorks or products
Search for specified keyword in all help entries
Open MathWorks Technical Support Web page
Point Help browser or Web browser to file or Web site
Display information about MATLAB and toolbox releases
Workspace, File, and Search Path
• “Workspace”
• “File”
• “Search Path”
Workspace
assignin
clear
evalin
exist
openvar
pack
which
who, whos
workspace
Assign value to workspace variable
Remove items from workspace, freeing up system memory
Execute string containing MATLAB expression in a workspace
Check if variable or file exists
Open workspace variable in Array Editor for graphical editing
Consolidate workspace memory
Locate functions and files
List variables in the workspace
Display Workspace browser, a tool for managing the workspace
File
cd
copyfile
delete
dir
exist
fileattrib
filebrowser
lookfor
ls
Change working directory
Copy file or directory
Delete files or graphics objects
Display directory listing
Check if a variable or file exists
Set or get attributes of file or directory
Display Current Directory browser, a tool for viewing files
Search for specified keyword in all help entries
List directory on UNIX
1-3
1
Functions – By Category
matlabroot
mkdir
movefile
pwd
rehash
rmdir
type
what
which
Return root directory of MATLAB installation
Make new directory
Move file or directory
Display current directory
Refresh function and file system caches
Remove directory
List file
List MATLAB specific files in current directory
Locate functions and files
See also “File I/O” functions.
Search Path
addpath
genpath
partialpath
path
path2rc
pathtool
rmpath
Add directories to MATLAB search path
Generate path string
Partial pathname
View or change the MATLAB directory search path
Save current MATLAB search path to pathdef.m file
Open Set Path dialog box to view and change MATLAB path
Remove directories from MATLAB search path
Programming Tools
• “Editing and Debugging”
• “Source Control”
• “Notebook”
Editing and Debugging
dbclear
dbcont
dbdown
dbquit
dbstack
dbstatus
dbstep
dbstop
dbtype
dbup
edit
keyboard
1-4
Clear breakpoints
Resume execution
Change local workspace context
Quit debug mode
Display function call stack
List all breakpoints
Execute one or more lines from current breakpoint
Set breakpoints in M-file function
List M-file with line numbers
Change local workspace context
Edit or create M-file
Invoke the keyboard in an M-file
Development Environment
Source Control
checkin
Check file into source control system
checkout
Check file out of source control system
cmopts
Get name of source control system
customverctrl Allow custom source control system
undocheckout Undo previous checkout from source control system
verctrl
Version control operations on PC platforms
Notebook
notebook
Open M-book in Microsoft Word (Windows only)
System
computer
javachk
license
prefdir
usejava
ver
version
Identify information about computer on which MATLAB is
running
Generate error message based on Java feature support
Show license number for MATLAB
Return directory containing preferences, history, and .ini files
Determine if a Java feature is supported in MATLAB
Display version information for MathWorks products
Get MATLAB version number
Performance Improvement Tools and Techniques
memory
pack
profile
profreport
rehash
sparse
zeros
Help for memory limitations
Consolidate workspace memory
Optimize performance of M-file code
Generate profile report
Refresh function and file system caches
Create sparse matrix
Create array of all zeros
1-5
1
Functions – By Category
Mathematics
Functions for working with arrays and matrices, linear algebra, data analysis,
and other areas of mathematics.
1-6
“Arrays and Matrices”
Basic array operators and operations, creation of
elementary and specialized arrays and matrices
“Linear Algebra”
Matrix analysis, linear equations, eigenvalues,
singular values, logarithms, exponentials,
factorization
“Elementary Math”
Trigonometry, exponentials and logarithms,
complex values, rounding, remainders, discrete
math
“Data Analysis and
Fourier Transforms”
Descriptive statistics, finite differences, correlation,
filtering and convolution, fourier transforms
“Polynomials”
Multiplication, division, evaluation, roots,
derivatives, integration, eigenvalue problem, curve
fitting, partial fraction expansion
“Interpolation and
Computational
Geometry”
Interpolation, Delaunay triangulation and
tessellation, convex hulls, Voronoi diagrams,
domain generation
“Coordinate System
Conversion”
Conversions between Cartesian and polar or
spherical coordinates
“Nonlinear Numerical
Methods”
Differential equations, optimization, integration
“Specialized Math”
Airy, Bessel, Jacobi, Legendre, beta, elliptic, error,
exponential integral, gamma functions
“Sparse Matrices”
Elementary sparse matrices, operations, reordering
algorithms, linear algebra, iterative methods, tree
operations
“Math Constants”
Pi, imaginary unit, infinity, Not-a-Number, largest
and smallest positive floating point numbers,
floating point relative accuracy
Mathematics
Arrays and Matrices
• “Basic Information”
• “Operators”
• “Operations and Manipulation”
• “Elementary Matrices and Arrays”
• “Specialized Matrices”
Basic Information
disp
display
isempty
isequal
islogical
isnumeric
issparse
length
ndims
numel
size
Display array
Display array
True for empty matrix
True if arrays are identical
True for logical array
True for numeric arrays
True for sparse matrix
Length of vector
Number of dimensions
Number of elements
Size of matrix
Operators
+
+
*
^
\
/
'
.'
.*
.^
.\
./
Addition
Unary plus
Subtraction
Unary minus
Matrix multiplication
Matrix power
Backslash or left matrix divide
Slash or right matrix divide
Transpose
Nonconjugated transpose
Array multiplication (element-wise)
Array power (element-wise)
Left array divide (element-wise)
Right array divide (element-wise)
Operations and Manipulation
: (colon)
blkdiag
Index into array, rearrange array
Block diagonal concatenation
1-7
1
Functions – By Category
cat
cross
cumprod
cumsum
diag
dot
end
find
fliplr
flipud
flipdim
horzcat
ind2sub
ipermute
kron
max
min
permute
prod
repmat
reshape
rot90
sort
sortrows
sum
sqrtm
sub2ind
tril
triu
vertcat
Concatenate arrays
Vector cross product
Cumulative product
Cumulative sum
Diagonal matrices and diagonals of matrix
Vector dot product
Last index
Find indices of nonzero elements
Flip matrices left-right
Flip matrices up-down
Flip matrix along specified dimension
Horizontal concatenation
Multiple subscripts from linear index
Inverse permute dimensions of multidimensional array
Kronecker tensor product
Maximum elements of array
Minimum elements of array
Rearrange dimensions of multidimensional array
Product of array elements
Replicate and tile array
Reshape array
Rotate matrix 90 degrees
Sort elements in ascending order
Sort rows in ascending order
Sum of array elements
Matrix square root
Linear index from multiple subscripts
Lower triangular part of matrix
Upper triangular part of matrix
Vertical concatenation
See also “Linear Algebra” for other matrix operations.
See also “Elementary Math” for other array operations.
Elementary Matrices and Arrays
: (colon)
blkdiag
diag
eye
freqspace
linspace
logspace
1-8
Regularly spaced vector
Construct block diagonal matrix from input arguments
Diagonal matrices and diagonals of matrix
Identity matrix
Frequency spacing for frequency response
Generate linearly spaced vectors
Generate logarithmically spaced vectors
Mathematics
meshgrid
ndgrid
ones
rand
randn
repmat
zeros
Generate X and Y matrices for three-dimensional plots
Arrays for multidimensional functions and interpolation
Create array of all ones
Uniformly distributed random numbers and arrays
Normally distributed random numbers and arrays
Replicate and tile array
Create array of all zeros
Specialized Matrices
compan
gallery
hadamard
hankel
hilb
invhilb
magic
pascal
rosser
toeplitz
vander
wilkinson
Companion matrix
Test matrices
Hadamard matrix
Hankel matrix
Hilbert matrix
Inverse of Hilbert matrix
Magic square
Pascal matrix
Classic symmetric eigenvalue test problem
Toeplitz matrix
Vandermonde matrix
Wilkinson’s eigenvalue test matrix
Linear Algebra
• “Matrix Analysis”
• “Linear Equations”
• “Eigenvalues and Singular Values”
• “Matrix Logarithms and Exponentials”
• “Factorization”
Matrix Analysis
cond
condeig
det
norm
normest
null
orth
rank
rcond
Condition number with respect to inversion
Condition number with respect to eigenvalues
Determinant
Matrix or vector norm
Estimate matrix 2-norm
Null space
Orthogonalization
Matrix rank
Matrix reciprocal condition number estimate
1-9
1
Functions – By Category
rref
subspace
trace
Reduced row echelon form
Angle between two subspaces
Sum of diagonal elements
Linear Equations
\ and /
chol
cholinc
cond
condest
funm
inv
lscov
lsqnonneg
lu
luinc
pinv
qr
rcond
Linear equation solution
Cholesky factorization
Incomplete Cholesky factorization
Condition number with respect to inversion
1-norm condition number estimate
Evaluate general matrix function
Matrix inverse
Least squares solution in presence of known covariance
Nonnegative least squares
LU matrix factorization
Incomplete LU factorization
Moore-Penrose pseudoinverse of matrix
Orthogonal-triangular decomposition
Matrix reciprocal condition number estimate
Eigenvalues and Singular Values
balance
cdf2rdf
condeig
eig
eigs
gsvd
hess
poly
polyeig
qz
rsf2csf
schur
svd
svds
Improve accuracy of computed eigenvalues
Convert complex diagonal form to real block diagonal form
Condition number with respect to eigenvalues
Eigenvalues and eigenvectors
Eigenvalues and eigenvectors of sparse matrix
Generalized singular value decomposition
Hessenberg form of matrix
Polynomial with specified roots
Polynomial eigenvalue problem
QZ factorization for generalized eigenvalues
Convert real Schur form to complex Schur form
Schur decomposition
Singular value decomposition
Singular values and vectors of sparse matrix
Matrix Logarithms and Exponentials
expm
logm
sqrtm
1-10
Matrix exponential
Matrix logarithm
Matrix square root
Mathematics
Factorization
balance
cdf2rdf
chol
cholinc
cholupdate
lu
luinc
planerot
qr
qrdelete
qrinsert
qrupdate
qz
rsf2csf
Diagonal scaling to improve eigenvalue accuracy
Complex diagonal form to real block diagonal form
Cholesky factorization
Incomplete Cholesky factorization
Rank 1 update to Cholesky factorization
LU matrix factorization
Incomplete LU factorization
Givens plane rotation
Orthogonal-triangular decomposition
Delete column or row from QR factorization
Insert column or row into QR factorization
Rank 1 update to QR factorization
QZ factorization for generalized eigenvalues
Real block diagonal form to complex diagonal form
Elementary Math
• “Trigonometric”
• “Exponential”
• “Complex”
• “Rounding and Remainder”
• “Discrete Math (e.g., Prime Factors)”
Trigonometric
acos
acosh
acot
acoth
acsc
acsch
asec
asech
asin
asinh
atan
atanh
atan2
cos
cosh
cot
coth
Inverse cosine
Inverse hyperbolic cosine
Inverse cotangent
Inverse hyperbolic cotangent
Inverse cosecant
Inverse hyperbolic cosecant
Inverse secant
Inverse hyperbolic secant
Inverse sine
Inverse hyperbolic sine
Inverse tangent
Inverse hyperbolic tangent
Four-quadrant inverse tangent
Cosine
Hyperbolic cosine
Cotangent
Hyperbolic cotangent
1-11
1
Functions – By Category
csc
csch
sec
sech
sin
sinh
tan
tanh
Cosecant
Hyperbolic cosecant
Secant
Hyperbolic secant
Sine
Hyperbolic sine
Tangent
Hyperbolic tangent
Exponential
exp
log
log2
log10
nextpow2
pow2
reallog
realpow
realsqrt
sqrt
Exponential
Natural logarithm
Base 2 logarithm and dissect floating-point numbers into
exponent and mantissa
Common (base 10) logarithm
Next higher power of 2
Base 2 power and scale floating-point number
Natural logarithm for nonnegative real arrays
Array power for real-only output
Square root for nonnegative real arrays
Square root
Complex
abs
angle
complex
conj
cplxpair
i
imag
isreal
j
real
unwrap
Absolute value
Phase angle
Construct complex data from real and imaginary parts
Complex conjugate
Sort numbers into complex conjugate pairs
Imaginary unit
Complex imaginary part
True for real array
Imaginary unit
Complex real part
Unwrap phase angle
Rounding and Remainder
fix
floor
ceil
round
mod
rem
sign
1-12
Round towards zero
Round towards minus infinity
Round towards plus infinity
Round towards nearest integer
Modulus after division
Remainder after division
Signum
Mathematics
Discrete Math (e.g., Prime Factors)
factor
factorial
gcd
isprime
lcm
nchoosek
perms
primes
rat, rats
Prime factors
Factorial function
Greatest common divisor
True for prime numbers
Least common multiple
All combinations of N elements taken K at a time
All possible permutations
Generate list of prime numbers
Rational fraction approximation
Data Analysis and Fourier Transforms
• “Basic Operations”
• “Finite Differences”
• “Correlation”
• “Filtering and Convolution”
• “Fourier Transforms”
Basic Operations
cumprod
cumsum
cumtrapz
max
mean
median
min
prod
sort
sortrows
std
sum
trapz
var
Cumulative product
Cumulative sum
Cumulative trapezoidal numerical integration
Maximum elements of array
Average or mean value of arrays
Median value of arrays
Minimum elements of array
Product of array elements
Sort elements in ascending order
Sort rows in ascending order
Standard deviation
Sum of array elements
Trapezoidal numerical integration
Variance
Finite Differences
del2
diff
gradient
Discrete Laplacian
Differences and approximate derivatives
Numerical gradient
1-13
1
Functions – By Category
Correlation
corrcoef
cov
subspace
Correlation coefficients
Covariance matrix
Angle between two subspaces
Filtering and Convolution
conv
conv2
convn
deconv
detrend
filter
filter2
Convolution and polynomial multiplication
Two-dimensional convolution
N-dimensional convolution
Deconvolution and polynomial division
Linear trend removal
Filter data with infinite impulse response (IIR) or finite
impulse response (FIR) filter
Two-dimensional digital filtering
Fourier Transforms
abs
angle
fft
fft2
fftn
fftshift
ifft
ifft2
ifftn
ifftshift
nextpow2
unwrap
Absolute value and complex magnitude
Phase angle
One-dimensional discrete Fourier transform
Two-dimensional discrete Fourier transform
N-dimensional discrete Fourier Transform
Shift DC component of discrete Fourier transform to center of
spectrum
Inverse one-dimensional discrete Fourier transform
Inverse two-dimensional discrete Fourier transform
Inverse multidimensional discrete Fourier transform
Inverse fast Fourier transform shift
Next power of two
Correct phase angles
Polynomials
conv
deconv
poly
polyder
polyeig
polyfit
polyint
polyval
polyvalm
residue
1-14
Convolution and polynomial multiplication
Deconvolution and polynomial division
Polynomial with specified roots
Polynomial derivative
Polynomial eigenvalue problem
Polynomial curve fitting
Analytic polynomial integration
Polynomial evaluation
Matrix polynomial evaluation
Convert between partial fraction expansion and polynomial
Mathematics
roots
coefficients
Polynomial roots
Interpolation and Computational Geometry
• “Interpolation”
• “Delaunay Triangulation and Tessellation”
• “Convex Hull”
• “Voronoi Diagrams”
• “Domain Generation”
Interpolation
dsearch
dsearchn
griddata
griddata3
griddatan
interp1
interp2
interp3
interpft
interpn
meshgrid
mkpp
ndgrid
pchip
ppval
spline
tsearchn
unmkpp
Search for nearest point
Multidimensional closest point search
Data gridding
Data gridding and hypersurface fitting for three-dimensional
data
Data gridding and hypersurface fitting (dimension >= 2)
One-dimensional data interpolation (table lookup)
Two-dimensional data interpolation (table lookup)
Three-dimensional data interpolation (table lookup)
One-dimensional interpolation using fast Fourier transform
method
Multidimensional data interpolation (table lookup)
Generate X and Y matrices for three-dimensional plots
Make piecewise polynomial
Generate arrays for multidimensional functions and
interpolation
Piecewise Cubic Hermite Interpolating Polynomial (PCHIP)
Piecewise polynomial evaluation
Cubic spline data interpolation
Multidimensional closest simplex search
Piecewise polynomial details
Delaunay Triangulation and Tessellation
delaunay
delaunay3
delaunayn
dsearch
dsearchn
Delaunay triangulation
Three-dimensional Delaunay tessellation
Multidimensional Delaunay tessellation
Search for nearest point
Multidimensional closest point search
1-15
1
Functions – By Category
tetramesh
trimesh
triplot
trisurf
tsearch
tsearchn
Tetrahedron mesh plot
Triangular mesh plot
Two-dimensional triangular plot
Triangular surface plot
Search for enclosing Delaunay triangle
Multidimensional closest simplex search
Convex Hull
convhull
convhulln
patch
plot
trisurf
Convex hull
Multidimensional convex hull
Create patch graphics object
Linear two-dimensional plot
Triangular surface plot
Voronoi Diagrams
dsearch
patch
plot
voronoi
voronoin
Search for nearest point
Create patch graphics object
Linear two-dimensional plot
Voronoi diagram
Multidimensional Voronoi diagrams
Domain Generation
meshgrid
ndgrid
Generate X and Y matrices for three-dimensional plots
Generate arrays for multidimensional functions and
interpolation
Coordinate System Conversion
Cartesian
cart2sph
cart2pol
pol2cart
sph2cart
Transform Cartesian to spherical coordinates
Transform Cartesian to polar coordinates
Transform polar to Cartesian coordinates
Transform spherical to Cartesian coordinates
Nonlinear Numerical Methods
• “Ordinary Differential Equations (IVP)”
• “Delay Differential Equations”
• “Boundary Value Problems”
1-16
Mathematics
• “Partial Differential Equations”
• “Optimization”
• “Numerical Integration (Quadrature)”
Ordinary Differential Equations (IVP)
deval
ode113
ode15s
ode23
ode23s
ode23t
ode23tb
ode45
odeget
odeset
Evaluate solution of differential equation problem
Solve non-stiff differential equations, variable order method
Solve stiff ODEs and DAEs Index 1, variable order method
Solve non-stiff differential equations, low order method
Solve stiff differential equations, low order method
Solve moderately stiff ODEs and DAEs Index 1, trapezoidal
rule
Solve stiff differential equations, low order method
Solve non-stiff differential equations, medium order method
Get ODE options parameters
Create/alter ODE options structure
Delay Differential Equations
dde23
ddeget
ddeset
Solve delay differential equations with constant delays
Get DDE options parameters
Create/alter DDE options structure
Boundary Value Problems
bvp4c
bvpget
bvpset
deval
Solve two-point boundary value problems for ODEs by
collocation
Get BVP options parameters
Create/alter BVP options structure
Evaluate solution of differential equation problem
Partial Differential Equations
pdepe
pdeval
Solve initial-boundary value problems for parabolic-elliptic
PDEs
Evaluates by interpolation solution computed by pdepe
Optimization
fminbnd
fminsearch
fzero
lsqnonneg
Scalar bounded nonlinear function minimization
Multidimensional unconstrained nonlinear minimization, by
Nelder-Mead direct search method
Scalar nonlinear zero finding
Linear least squares with nonnegativity constraints
1-17
1
Functions – By Category
optimset
optimget
Create or alter optimization options structure
Get optimization parameters from options structure
Numerical Integration (Quadrature)
quad
quadl
dblquad
triplequad
Numerically evaluate integral, adaptive Simpson quadrature
(low order)
Numerically evaluate integral, adaptive Lobatto quadrature
(high order)
Numerically evaluate double integral
Numerically evaluate triple integral
Specialized Math
airy
besselh
besseli
besselj
besselk
bessely
beta
betainc
betaln
ellipj
ellipke
erf
erfc
erfcinv
erfcx
erfinv
expint
gamma
gammainc
gammaln
legendre
psi
Airy functions
Bessel functions of third kind (Hankel functions)
Modified Bessel function of first kind
Bessel function of first kind
Modified Bessel function of second kind
Bessel function of second kind
Beta function
Incomplete beta function
Logarithm of beta function
Jacobi elliptic functions
Complete elliptic integrals of first and second kind
Error function
Complementary error function
Inverse complementary error function
Scaled complementary error function
Inverse error function
Exponential integral
Gamma function
Incomplete gamma function
Logarithm of gamma function
Associated Legendre functions
Psi (polygamma) function
Sparse Matrices
• “Elementary Sparse Matrices”
• “Full to Sparse Conversion”
• “Working with Sparse Matrices”
1-18
Mathematics
• “Reordering Algorithms”
• “Linear Algebra”
• “Linear Equations (Iterative Methods)”
• “Tree Operations”
Elementary Sparse Matrices
spdiags
speye
sprand
sprandn
sprandsym
Sparse matrix formed from diagonals
Sparse identity matrix
Sparse uniformly distributed random matrix
Sparse normally distributed random matrix
Sparse random symmetric matrix
Full to Sparse Conversion
find
full
sparse
spconvert
Find indices of nonzero elements
Convert sparse matrix to full matrix
Create sparse matrix
Import from sparse matrix external format
Working with Sparse Matrices
issparse
nnz
nonzeros
nzmax
spalloc
spfun
spones
spparms
spy
True for sparse matrix
Number of nonzero matrix elements
Nonzero matrix elements
Amount of storage allocated for nonzero matrix elements
Allocate space for sparse matrix
Apply function to nonzero matrix elements
Replace nonzero sparse matrix elements with ones
Set parameters for sparse matrix routines
Visualize sparsity pattern
Reordering Algorithms
colamd
colmmd
colperm
dmperm
randperm
symamd
symmmd
symrcm
Column approximate minimum degree permutation
Column minimum degree permutation
Column permutation
Dulmage-Mendelsohn permutation
Random permutation
Symmetric approximate minimum degree permutation
Symmetric minimum degree permutation
Symmetric reverse Cuthill-McKee permutation
1-19
1
Functions – By Category
Linear Algebra
cholinc
condest
eigs
luinc
normest
sprank
svds
Incomplete Cholesky factorization
1-norm condition number estimate
Eigenvalues and eigenvectors of sparse matrix
Incomplete LU factorization
Estimate matrix 2-norm
Structural rank
Singular values and vectors of sparse matrix
Linear Equations (Iterative Methods)
bicg
bicgstab
cgs
gmres
lsqr
minres
pcg
qmr
spaugment
symmlq
BiConjugate Gradients method
BiConjugate Gradients Stabilized method
Conjugate Gradients Squared method
Generalized Minimum Residual method
LSQR implementation of Conjugate Gradients on Normal
Equations
Minimum Residual method
Preconditioned Conjugate Gradients method
Quasi-Minimal Residual method
Form least squares augmented system
Symmetric LQ method
Tree Operations
etree
etreeplot
gplot
symbfact
treelayout
treeplot
Elimination tree
Plot elimination tree
Plot graph, as in “graph theory”
Symbolic factorization analysis
Lay out tree or forest
Plot picture of tree
Math Constants
eps
i
Inf
j
NaN
pi
realmax
realmin
1-20
Floating-point relative accuracy
Imaginary unit
Infinity, ∞
Imaginary unit
Not-a-Number
Ratio of a circle’s circumference to its diameter, π
Largest positive floating-point number
Smallest positive floating-point number
Programming and Data Types
Programming and Data Types
Functions to store and operate on data at either the MATLAB command line or
in programs and scripts. Functions to write, manage, and execute MATLAB
programs.
“Data Types”
Numeric, character, structures, cell arrays,
and data type conversion
“Arrays”
Basic array operations and manipulation
“Operators and Operations”
Special characters and arithmetic, bit-wise,
relational, logical, set, date and time
operations
“Programming in MATLAB”
M-files, function/expression evaluation,
program control, function handles, object
oriented programming, error handling
Data Types
• “Numeric”
• “Characters and Strings”
• “Structures”
• “Cell Arrays”
• “Data Type Conversion”
• “Determine Data Type”
Numeric
[ ]
Array constructor
cat
Concatenate arrays
class
Return object’s class name (e.g., numeric)
find
Find indices and values of nonzero array elements
ipermute
Inverse permute dimensions of multidimensional array
isa
Detect object of given class (e.g., numeric)
isequal
Determine if arrays are numerically equal
isequalwithequalnansTest for equality, treating NaNs as equal
isnumeric
Determine if item is numeric array
isreal
Determine if all array elements are real numbers
permute
Rearrange dimensions of multidimensional array
1-21
1
Functions – By Category
reshape
squeeze
zeros
Reshape array
Remove singleton dimensions from array
Create array of all zeros
Characters and Strings
Description of Strings in MATLAB
strings
Describes MATLAB string handling
Creating and Manipulating Strings
blanks
char
cellstr
datestr
deblank
lower
sprintf
sscanf
strcat
strjust
strread
strrep
strvcat
upper
Create string of blanks
Create character array (string)
Create cell array of strings from character array
Convert to date string format
Strip trailing blanks from the end of string
Convert string to lower case
Write formatted data to string
Read string under format control
String concatenation
Justify character array
Read formatted data from string
String search and replace
Vertical concatenation of strings
Convert string to upper case
Comparing and Searching Strings
class
findstr
isa
iscellstr
ischar
isletter
isspace
regexp
regexpi
regexprep
strcmp
strcmpi
strfind
strmatch
strncmp
1-22
Return object’s class name (e.g., char)
Find string within another, longer string
Detect object of given class (e.g., char)
Determine if item is cell array of strings
Determine if item is character array
Detect array elements that are letters of the alphabet
Detect elements that are ASCII white spaces
Match regular expression
Match regular expression, ignoring case
Replace string using regular expression
Compare strings
Compare strings, ignoring case
Find one string within another
Find possible matches for string
Compare first n characters of strings
Programming and Data Types
strncmpi
strtok
Compare first n characters of strings, ignoring case
First token in string
Evaluating String Expressions
eval
evalc
evalin
Execute string containing MATLAB expression
Evaluate MATLAB expression with capture
Execute string containing MATLAB expression in workspace
Structures
cell2struct
class
deal
fieldnames
isa
isequal
isfield
isstruct
orderfields
rmfield
struct
struct2cell
Cell array to structure array conversion
Return object’s class name (e.g., struct)
Deal inputs to outputs
Field names of structure
Detect object of given class (e.g., struct)
Determine if arrays are numerically equal
Determine if item is structure array field
Determine if item is structure array
Order fields of a structure array
Remove structure fields
Create structure array
Structure to cell array conversion
Cell Arrays
{ }
cell
cellfun
cellstr
cell2mat
cell2struct
celldisp
cellplot
class
deal
isa
iscell
iscellstr
isequal
mat2cell
num2cell
struct2cell
Construct cell array
Construct cell array
Apply function to each element in cell array
Create cell array of strings from character array
Convert cell array of matrices into single matrix
Cell array to structure array conversion
Display cell array contents
Graphically display structure of cell arrays
Return object’s class name (e.g., cell)
Deal inputs to outputs
Detect object of given class (e.g., cell)
Determine if item is cell array
Determine if item is cell array of strings
Determine if arrays are numerically equal
Divide matrix up into cell array of matrices
Convert numeric array into cell array
Structure to cell array conversion
1-23
1
Functions – By Category
Data Type Conversion
Numeric
double
int8
int16
int32
int64
single
uint8
uint16
uint32
uint64
Convert to double-precision
Convert to signed 8-bit integer
Convert to signed 16-bit integer
Convert to signed 32-bit integer
Convert to signed 64-bit integer
Convert to single-precision
Convert to unsigned 8-bit integer
Convert to unsigned 16-bit integer
Convert to unsigned 32-bit integer
Convert to unsigned 64-bit integer
String to Numeric
base2dec
bin2dec
hex2dec
hex2num
str2double
str2num
Convert base N number string to decimal number
Convert binary number string to decimal number
Convert hexadecimal number string to decimal number
Convert hexadecimal number string to double number
Convert string to double-precision number
Convert string to number
Numeric to String
char
dec2base
dec2bin
dec2hex
int2str
mat2str
num2str
Convert to character array (string)
Convert decimal to base N number in string
Convert decimal to binary number in string
Convert decimal to hexadecimal number in string
Convert integer to string
Convert a matrix to string
Convert number to string
Other Conversions
cell2mat
cell2struct
datestr
func2str
logical
mat2cell
num2cell
str2func
struct2cell
1-24
Convert cell array of matrices into single matrix
Convert cell array to structure array
Convert serial date number to string
Convert function handle to function name string
Convert numeric to logical array
Divide matrix up into cell array of matrices
Convert a numeric array to cell array
Convert function name string to function handle
Convert structure to cell array
Programming and Data Types
Determine Data Type
is*
isa
iscell
iscellstr
ischar
isfield
isjava
islogical
isnumeric
isobject
isstruct
Detect state
Detect object of given MATLAB class or Java class
Determine if item is cell array
Determine if item is cell array of strings
Determine if item is character array
Determine if item is character array
Determine if item is Java object
Determine if item is logical array
Determine if item is numeric array
Determine if item is MATLAB OOPs object
Determine if item is MATLAB structure array
Arrays
• “Array Operations”
• “Basic Array Information”
• “Array Manipulation”
• “Elementary Arrays”
Array Operations
[ ]
,
;
:
end
+
.*
./
.\
.^
.'
Array constructor
Array row element separator
Array column element separator
Specify range of array elements
Indicate last index of array
Addition or unary plus
Subtraction or unary minus
Array multiplication
Array right division
Array left division
Array power
Array (nonconjugated) transpose
Basic Array Information
disp
Display text or array
display
Overloaded method to display text or array
isempty
Determine if array is empty
isequal
Determine if arrays are numerically equal
isequalwithequalnansTest for equality, treating NaNs as equal
1-25
1
Functions – By Category
isnumeric
islogical
length
ndims
numel
size
Determine if item is numeric array
Determine if item is logical array
Length of vector
Number of array dimensions
Number of elements in matrix or cell array
Array dimensions
Array Manipulation
:
blkdiag
cat
circshift
find
fliplr
flipud
flipdim
horzcat
ind2sub
ipermute
permute
repmat
reshape
rot90
shiftdim
sort
sortrows
squeeze
sub2ind
vertcat
Specify range of array elements
Construct block diagonal matrix from input arguments
Concatenate arrays
Shift array circularly
Find indices and values of nonzero elements
Flip matrices left-right
Flip matrices up-down
Flip array along specified dimension
Horizontal concatenation
Subscripts from linear index
Inverse permute dimensions of multidimensional array
Rearrange dimensions of multidimensional array
Replicate and tile array
Reshape array
Rotate matrix 90 degrees
Shift dimensions
Sort elements in ascending order
Sort rows in ascending order
Remove singleton dimensions
Single index from subscripts
Horizontal concatenation
Elementary Arrays
:
blkdiag
eye
linspace
logspace
meshgrid
ndgrid
ones
rand
randn
zeros
1-26
Regularly spaced vector
Construct block diagonal matrix from input arguments
Identity matrix
Generate linearly spaced vectors
Generate logarithmically spaced vectors
Generate X and Y matrices for three-dimensional plots
Generate arrays for multidimensional functions and
interpolation
Create array of all ones
Uniformly distributed random numbers and arrays
Normally distributed random numbers and arrays
Create array of all zeros
Programming and Data Types
Operators and Operations
• “Special Characters”
• “Arithmetic Operations”
• “Bit-wise Operations”
• “Relational Operations”
• “Logical Operations”
• “Set Operations”
• “Date and Time Operations”
Special Characters
:
( )
[ ]
{ }
.
...
,
;
%
!
=
Specify range of array elements
Pass function arguments, or prioritize operations
Construct array
Construct cell array
Decimal point, or structure field separator
Continue statement to next line
Array row element separator
Array column element separator
Insert comment line into code
Command to operating system
Assignment
Arithmetic Operations
+
.
=
*
/
\
^
'
.*
./
.\
.^
.'
Plus
Minus
Decimal point
Assignment
Matrix multiplication
Matrix right division
Matrix left division
Matrix power
Matrix transpose
Array multiplication (element-wise)
Array right division (element-wise)
Array left division (element-wise)
Array power (element-wise)
Array transpose
1-27
1
Functions – By Category
Bit-wise Operations
bitand
bitcmp
bitor
bitmax
bitset
bitshift
bitget
bitxor
Bit-wise AND
Bit-wise complement
Bit-wise OR
Maximum floating-point integer
Set bit at specified position
Bit-wise shift
Get bit at specified position
Bit-wise XOR
Relational Operations
<
<=
>
>=
==
~=
Less than
Less than or equal to
Greater than
Greater than or equal to
Equal to
Not equal to
Logical Operations
&&
||
&
|
~
all
any
false
find
is*
isa
iskeyword
isvarname
logical
true
xor
Logical AND
Logical OR
Logical AND for arrays
Logical OR for arrays
Logical NOT
Test to determine if all elements are nonzero
Test for any nonzero elements
False array
Find indices and values of nonzero elements
Detect state
Detect object of given class
Determine if string is MATLAB keyword
Determine if string is valid variable name
Convert numeric values to logical
True array
Logical EXCLUSIVE OR
Set Operations
intersect
ismember
setdiff
issorted
1-28
Set intersection of two vectors
Detect members of set
Return set difference of two vectors
Determine if set elements are in sorted order
Programming and Data Types
setxor
union
unique
Set exclusive or of two vectors
Set union of two vectors
Unique elements of vector
Date and Time Operations
calendar
clock
cputime
date
datenum
datestr
datevec
eomday
etime
now
tic, toc
weekday
Calendar for specified month
Current time as date vector
Elapsed CPU time
Current date string
Serial date number
Convert serial date number to string
Date components
End of month
Elapsed time
Current date and time
Stopwatch timer
Day of the week
Programming in MATLAB
• “M-File Functions and Scripts”
• “Evaluation of Expressions and Functions”
• “Timer Functions”
• “Variables and Functions in Memory”
• “Control Flow”
• “Function Handles”
• “Object-Oriented Programming”
• “Error Handling”
• “MEX Programming”
M-File Functions and Scripts
( )
%
...
depfun
depdir
function
input
Pass function arguments
Insert comment line into code
Continue statement to next line
List dependent functions of M-file or P-file
List dependent directories of M-file or P-file
Function M-files
Request user input
1-29
1
Functions – By Category
inputname
Input argument name
mfilename
Name of currently running M-file
namelengthmax Return maximum identifier length
nargin
Number of function input arguments
nargout
Number of function output arguments
nargchk
Check number of input arguments
nargoutchk
Validate number of output arguments
pcode
Create preparsed pseudocode file (P-file)
script
Describes script M-file
varargin
Accept variable number of arguments
varargout
Return variable number of arguments
Evaluation of Expressions and Functions
builtin
cellfun
eval
evalc
evalin
feval
iskeyword
isvarname
pause
run
script
symvar
tic, toc
Execute builtin function from overloaded method
Apply function to each element in cell array
Interpret strings containing MATLAB expressions
Evaluate MATLAB expression with capture
Evaluate expression in workspace
Evaluate function
Determine if item is MATLAB keyword
Determine if item is valid variable name
Halt execution temporarily
Run script that is not on current path
Describes script M-file
Determine symbolic variables in expression
Stopwatch timer
Timer Functions
delete
disp
get
isvalid
set
start
startat
stop
timer
timerfind
wait
Delete timer object from memory
Display information about timer object
Retrieve information about timer object properties
Determine if timer object is valid
Display or set timer object properties
Start a timer
Start a timer at a specific timer
Stop a timer
Create a timer object
Return an array of all timer object in memory
Block command line until timer completes
Variables and Functions in Memory
assignin
1-30
Assign value to workspace variable
Programming and Data Types
global
Define global variables
inmem
Return names of functions in memory
isglobal
Determine if item is global variable
mislocked
True if M-file cannot be cleared
mlock
Prevent clearing M-file from memory
munlock
Allow clearing M-file from memory
namelengthmax Return maximum identifier length
pack
Consolidate workspace memory
persistent
Define persistent variable
rehash
Refresh function and file system caches
Control Flow
break
case
catch
continue
else
elseif
end
error
for
if
otherwise
return
switch
try
while
Terminate execution of for loop or while loop
Case switch
Begin catch block
Pass control to next iteration of for or while loop
Conditionally execute statements
Conditionally execute statements
Terminate conditional statements, or indicate last index
Display error messages
Repeat statements specific number of times
Conditionally execute statements
Default part of switch statement
Return to invoking function
Switch among several cases based on expression
Begin try block
Repeat statements indefinite number of times
Function Handles
class
Return object’s class name (e.g. function_handle)
feval
Evaluate function
function_handle
functions
func2str
isa
isequal
str2func
Describes function handle data type
Return information about function handle
Constructs function name string from function handle
Detect object of given class (e.g. function_handle)
Determine if function handles are equal
Constructs function handle from function name string
1-31
1
Functions – By Category
Object-Oriented Programming
MATLAB Classes and Objects
class
fieldnames
inferiorto
isa
isobject
loadobj
methods
methodsview
saveobj
subsasgn
subsindex
subsref
substruct
superiorto
Create object or return class of object
List public fields belonging to object,
Establish inferior class relationship
Detect object of given class
Determine if item is MATLAB OOPs object
User-defined extension of load function for user objects
Display method names
Displays information on all methods implemented by class
User-defined extension of save function for user objects
Overloaded method for A(I)=B, A{I}=B, and A.field=B
Overloaded method for X(A)
Overloaded method for A(I), A{I} and A.field
Create structure argument for subsasgn or subsref
Establish superior class relationship
Java Classes and Objects
cell
class
clear
depfun
exist
fieldnames
im2java
import
inmem
isa
isjava
javaArray
javaMethod
javaObject
methods
methodsview
which
Convert Java array object to cell array
Return class name of Java object
Clear Java packages import list
List Java classes used by M-file
Detect if item is Java class
List public fields belonging to object
Convert image to instance of Java image object
Add package or class to current Java import list
List names of Java classes loaded into memory
Detect object of given class
Determine whether object is Java object
Constructs Java array
Invokes Java method
Constructs Java object
Display methods belonging to class
Display information on all methods implemented by class
Display package and class name for method
Error Handling
catch
error
ferror
1-32
Begin catch block of try/catch statement
Display error message
Query MATLAB about errors in file input or output
Programming and Data Types
lasterr
lasterror
lastwarn
rethrow
try
warning
Return last error message generated by MATLAB
Last error message and related information
Return last warning message issued by MATLAB
Reissue error
Begin try block of try/catch statement
Display warning message
MEX Programming
dbmex
inmem
mex
mexext
Enable MEX-file debugging
Return names of currently loaded MEX-files
Compile MEX-function from C or Fortran source code
Return MEX-filename extension
1-33
1
Functions – By Category
File I/O
Functions to read and write data to files of different format types.
“Filename Construction”
Get path, directory, filename
information; construct filenames
“Opening, Loading, Saving Files”
Open files; transfer data between files
and MATLAB workspace
“Low-Level File I/O”
Low-level operations that use a file
identifier (e.g., fopen, fseek, fread)
“Text Files”
Delimited or formatted I/O to text files
“XML Documents”
Documents written in Extensible
Markup Language
“Spreadsheets”
Excel and Lotus 123 files
“Scientific Data”
CDF, FITS, HDF formats
“Audio and Audio/Video”
General audio functions; SparcStation,
Wave, AVI files
“Images”
Graphics files
To see a listing of file formats that are readable from MATLAB, go to file
formats.
Filename Construction
fileparts
filesep
fullfile
tempdir
tempname
Return parts of filename
Return directory separator for this platform
Build full filename from parts
Return name of system's temporary directory
Return unique string for use as temporary filename
Opening, Loading, Saving Files
importdata
load
open
save
winopen
1-34
Load data from various types of files
Load all or specific data from MAT or ASCII file
Open files of various types using appropriate editor or program
Save all or specific data to MAT or ASCII file
Open file in appropriate application (Windows only)
File I/O
Low-Level File I/O
fclose
feof
ferror
fgetl
fgets
fopen
fprintf
fread
frewind
fscanf
fseek
ftell
fwrite
Close one or more open files
Test for end-of-file
Query MATLAB about errors in file input or output
Return next line of file as string without line terminator(s)
Return next line of file as string with line terminator(s)
Open file or obtain information about open files
Write formatted data to file
Read binary data from file
Rewind open file
Read formatted data from file
Set file position indicator
Get file position indicator
Write binary data to file
Text Files
csvread
csvwrite
dlmread
dlmwrite
textread
Read numeric data from text file, using comma delimiter
Write numeric data to text file, using comma delimiter
Read numeric data from text file, specifying your own delimiter
Write numeric data to text file, specifying your own delimiter
Read data from text file, specifying format for each value
XML Documents
xmlread
xmlwrite
xslt
Parse XML document
Serialize XML Document Object Model node
Transform XML document using XSLT engine
Spreadsheets
Microsoft Excel Functions
xlsfinfo
xlsread
Determine if file contains Microsoft Excel (.xls) spreadsheet
Read Microsoft Excel spreadsheet file (.xls)
Lotus123 Functions
wk1read
wk1write
Read Lotus123 WK1 spreadsheet file into matrix
Write matrix to Lotus123 WK1 spreadsheet file
1-35
1
Functions – By Category
Scientific Data
Common Data Format (CDF)
cdfinfo
cdfread
Return information about CDF file
Read CDF file
Flexible Image Transport System
fitsinfo
fitsread
Return information about FITS file
Read FITS file
Hierarchical Data Format (HDF)
hdf
hdfinfo
hdfread
Interface to HDF files
Return information about HDF or HDF-EOS file
Read HDF file
Audio and Audio/Video
General
audioplayer Create audio player object
audiorecorder Perform real-time audio capture
beep
Produce beep sound
lin2mu
Convert linear audio signal to mu-law
mu2lin
Convert mu-law audio signal to linear
sound
Convert vector into sound
soundsc
Scale data and play as sound
SPARCstation-Specific Sound Functions
auread
auwrite
Read NeXT/SUN (.au) sound file
Write NeXT/SUN (.au) sound file
Microsoft WAVE Sound Functions
wavplay
wavread
wavrecord
wavwrite
1-36
Play sound on PC-based audio output device
Read Microsoft WAVE (.wav) sound file
Record sound using PC-based audio input device
Write Microsoft WAVE (.wav) sound file
File I/O
Audio Video Interleaved (AVI) Functions
addframe
avifile
aviinfo
aviread
close
movie2avi
Add frame to AVI file
Create new AVI file
Return information about AVI file
Read AVI file
Close AVI file
Create AVI movie from MATLAB movie
Images
im2java
imfinfo
imread
imwrite
Convert image to instance of Java image object
Return information about graphics file
Read image from graphics file
Write image to graphics file
1-37
1
Functions – By Category
Graphics
2-D graphs, specialized plots (e.g., pie charts, histograms, and contour plots),
function plotters, and Handle Graphics functions.
Basic Plots and Graphs
Linear line plots, log and semilog plots
Annotating Plots
Titles, axes labels, legends, mathematical
symbols
Specialized Plotting
Bar graphs, histograms, pie charts, contour plots,
function plotters
Bit-Mapped Images
Display image object, read and write graphics file,
convert to movie frames
Printing
Printing and exporting figures to standard
formats
Handle Graphics
Creating graphics objects, setting properties,
finding handles
Basic Plots and Graphs
box
errorbar
hold
LineSpec
loglog
polar
plot
plot3
plotyy
semilogx
semilogy
subplot
Axis box for 2-D and 3-D plots
Plot graph with error bars
Hold current graph
Line specification syntax
Plot using log-log scales
Polar coordinate plot
Plot vectors or matrices.
Plot lines and points in 3-D space
Plot graphs with Y tick labels on the left and right
Semi-log scale plot
Semi-log scale plot
Create axes in tiled positions
Annotating Plots
clabel
datetick
gtext
legend
texlabel
1-38
Add contour labels to contour plot
Date formatted tick labels
Place text on 2-D graph using mouse
Graph legend for lines and patches
Produce the TeX format from character string
Graphics
title
xlabel
ylabel
zlabel
Titles for 2-D and 3-D plots
X-axis labels for 2-D and 3-D plots
Y-axis labels for 2-D and 3-D plots
Z-axis labels for 3-D plots
Specialized Plotting
• “Area, Bar, and Pie Plots”
• “Contour Plots”
• “Direction and Velocity Plots”
• “Discrete Data Plots”
• “Function Plots”
• “Histograms”
• “Polygons and Surfaces”
• “Scatter Plots”
• “Animation”
Area, Bar, and Pie Plots
area
bar
barh
bar3
bar3h
pareto
pie
pie3
Area plot
Vertical bar chart
Horizontal bar chart
Vertical 3-D bar chart
Horizontal 3-D bar chart
Pareto char
Pie plot
3-D pie plot
Contour Plots
contour
contour3
contourc
contourf
ezcontour
ezcontourf
Contour (level curves) plot
3-D contour plot
Contour computation
Filled contour plot
Easy to use contour plotter
Easy to use filled contour plotter
Direction and Velocity Plots
comet
comet3
Comet plot
3-D comet plot
1-39
1
Functions – By Category
compass
feather
quiver
quiver3
Compass plot
Feather plot
Quiver (or velocity) plot
3-D quiver (or velocity) plot
Discrete Data Plots
stem
stem3
stairs
Plot discrete sequence data
Plot discrete surface data
Stairstep graph
Function Plots
ezcontour
ezcontourf
ezmesh
ezmeshc
ezplot
ezplot3
ezpolar
ezsurf
ezsurfc
fplot
Easy to use contour plotter
Easy to use filled contour plotter
Easy to use 3-D mesh plotter
Easy to use combination mesh/contour plotter
Easy to use function plotter
Easy to use 3-D parametric curve plotter
Easy to use polar coordinate plotter
Easy to use 3-D colored surface plotter
Easy to use combination surface/contour plotter
Plot a function
Histograms
hist
histc
rose
Plot histograms
Histogram count
Plot rose or angle histogram
Polygons and Surfaces
convhull
cylinder
delaunay
dsearch
ellipsoid
fill
fill3
inpolygon
pcolor
polyarea
ribbon
slice
sphere
1-40
Convex hull
Generate cylinder
Delaunay triangulation
Search Delaunay triangulation for nearest point
Generate ellipsoid
Draw filled 2-D polygons
Draw filled 3-D polygons in 3-space
True for points inside a polygonal region
Pseudocolor (checkerboard) plot
Area of polygon
Ribbon plot
Volumetric slice plot
Generate sphere
Graphics
tsearch
voronoi
waterfall
Search for enclosing Delaunay triangle
Voronoi diagram
Waterfall plot
Scatter Plots
plotmatrix
scatter
scatter3
Scatter plot matrix
Scatter plot
3-D scatter plot
Animation
frame2im
getframe
im2frame
movie
noanimate
Convert movie frame to indexed image
Capture movie frame
Convert image to movie frame
Play recorded movie frames
Change EraseMode of all objects to normal
Bit-Mapped Images
frame2im
image
imagesc
imfinfo
imformats
im2frame
im2java
imread
imwrite
ind2rgb
Convert movie frame to indexed image
Display image object
Scale data and display image object
Information about graphics file
Manage file format registry
Convert image to movie frame
Convert image to instance of Java image object
Read image from graphics file
Write image to graphics file
Convert indexed image to RGB image
Printing
frameedit
orient
pagesetupdlg
print
printdlg
printopt
printpreview
saveas
Edit print frame for Simulink and Stateflow diagram
Hardcopy paper orientation
Page position dialog box
Print graph or save graph to file
Print dialog box
Configure local printer defaults
Preview figure to be printed
Save figure to graphic file
1-41
1
Functions – By Category
Handle Graphics
• Finding and Identifying Graphics Objects
• Object Creation Functions
• Figure Windows
• Axes Operations
Finding and Identifying Graphics Objects
allchild
copyobj
delete
findall
figflag
findfigs
findobj
gca
gcbo
gcbf
gco
get
ishandle
set
Find all children of specified objects
Make copy of graphics object and its children
Delete files or graphics objects
Find all graphics objects (including hidden handles)
Test if figure is on screen
Display off-screen visible figure windows
Find objects with specified property values
Get current Axes handle
Return object whose callback is currently executing
Return handle of figure containing callback object
Return handle of current object
Get object properties
True if value is valid object handle
Set object properties
Object Creation Functions
axes
Create axes object
figure
Create figure (graph) windows
image
Create image (2-D matrix)
light
Create light object (illuminates Patch and Surface)
line
Create line object (3-D polylines)
patch
Create patch object (polygons)
rectangle
Create rectangle object (2-D rectangle)
rootobject
List of root properties
surface
Create surface (quadrilaterals)
text
Create text object (character strings)
uicontextmenu Create context menu (popup associated with object)
Figure Windows
capture
clc
clf
1-42
Screen capture of the current figure
Clear figure window
Clear figure
Graphics
close
closereq
drawnow
figflag
gcf
hgload
hgsave
newplot
opengl
refresh
saveas
Close specified window
Default close request function
Complete any pending drawing
Test if figure is on screen
Get current figure handle
Load graphics object hierarchy from a FIG-file
Save graphics object hierarchy to a FIG-file
Graphics M-file preamble for NextPlot property
Change automatic selection mode of OpenGL rendering
Refresh figure
Save figure or model to desired output format
Axes Operations
axis
box
cla
gca
grid
ishold
Plot axis scaling and appearance
Display axes border
Clear Axes
Get current Axes handle
Grid lines for 2-D and 3-D plots
Get the current hold state
1-43
1
Functions – By Category
3-D Visualization
Create and manipulate graphics that display 2-D matrix and 3-D volume data,
controlling the view, lighting and transparency.
Surface and Mesh Plots
Plot matrices, visualize functions of two variables,
specify colormap
View Control
Control the camera viewpoint, zooming, rotation,
aspect ratio, set axis limits
Lighting
Add and control scene lighting
Transparency
Specify and control object transparency
Volume Visualization
Visualize gridded volume data
Surface and Mesh Plots
• Creating Surfaces and Meshes
• Domain Generation
• Color Operations
• Colormaps
Creating Surfaces and Meshes
hidden
meshc
mesh
peaks
surf
surface
surfc
surfl
tetramesh
trimesh
triplot
trisurf
Mesh hidden line removal mode
Combination mesh/contourplot
3-D mesh with reference plane
A sample function of two variables
3-D shaded surface graph
Create surface low-level objects
Combination surf/contourplot
3-D shaded surface with lighting
Tetrahedron mesh plot
Triangular mesh plot
2-D triangular plot
Triangular surface plot
Domain Generation
griddata
meshgrid
1-44
Data gridding and surface fitting
Generation of X and Y arrays for 3-D plots
3-D Visualization
Color Operations
brighten
Brighten or darken color map
caxis
Pseudocolor axis scaling
colormapeditorStart colormap editor
colorbar
Display color bar (color scale)
colordef
Set up color defaults
colormap
Set the color look-up table (list of colormaps)
ColorSpec
Ways to specify color
graymon
Graphics figure defaults set for grayscale monitor
hsv2rgb
Hue-saturation-value to red-green-blue conversion
rgb2hsv
RGB to HSVconversion
rgbplot
Plot color map
shading
Color shading mode
spinmap
Spin the colormap
surfnorm
3-D surface normals
whitebg
Change axes background color for plots
Colormaps
autumn
bone
contrast
cool
copper
flag
gray
hot
hsv
jet
lines
prism
spring
summer
winter
Shades of red and yellow color map
Gray-scale with a tinge of blue color map
Gray color map to enhance image contrast
Shades of cyan and magenta color map
Linear copper-tone color map
Alternating red, white, blue, and black color map
Linear gray-scale color map
Black-red-yellow-white color map
Hue-saturation-value (HSV) color map
Variant of HSV
Line color colormap
Colormap of prism colors
Shades of magenta and yellow color map
Shades of green and yellow colormap
Shades of blue and green color map
View Control
• Controlling the Camera Viewpoint
• Setting the Aspect Ratio and Axis Limits
• Object Manipulation
• Selecting Region of Interest
1-45
1
Functions – By Category
Controlling the Camera Viewpoint
camdolly
camlookat
camorbit
campan
campos
camproj
camroll
camtarget
camup
camva
camzoom
view
viewmtx
Move camera position and target
View specific objects
Orbit about camera target
Rotate camera target about camera position
Set or get camera position
Set or get projection type
Rotate camera about viewing axis
Set or get camera target
Set or get camera up-vector
Set or get camera view angle
Zoom camera in or out
3-D graph viewpoint specification.
Generate view transformation matrices
Setting the Aspect Ratio and Axis Limits
daspect
pbaspect
xlim
ylim
zlim
Set or get data aspect ratio
Set or get plot box aspect ratio
Set or get the current x-axis limits
Set or get the current y-axis limits
Set or get the current z-axis limits
Object Manipulation
reset
Reset axis or figure
rotate
Rotate objects about specified origin and direction
rotate3d
Interactively rotate the view of a 3-D plot
selectmoveresizeInteractively select, move, or resize objects
zoom
Zoom in and out on a 2-D plot
Selecting Region of Interest
dragrect
rbbox
Drag XOR rectangles with mouse
Rubberband box
Lighting
camlight
light
lightangle
lighting
material
1-46
Cerate or position Light
Light object creation function
Position light in sphereical coordinates
Lighting mode
Material reflectance mode
3-D Visualization
Transparency
alpha
alphamap
alim
Set or query transparency properties for objects in current axes
Specify the figure alphamap
Set or query the axes alpha limits
Volume Visualization
coneplot
Plot velocity vectors as cones in 3-D vector field
contourslice Draw contours in volume slice plane
curl
Compute curl and angular velocity of vector field
divergence
Compute divergence of vector field
flow
Generate scalar volume data
interpstreamspeedInterpolate streamline vertices from vector-field
magnitudes
isocaps
Compute isosurface end-cap geometry
isocolors
Compute colors of isosurface vertices
isonormals
Compute normals of isosurface vertices
isosurface
Extract isosurface data from volume data
reducepatch Reduce number of patch faces
reducevolume Reduce number of elements in volume data set
shrinkfaces Reduce size of patch faces
slice
Draw slice planes in volume
smooth3
Smooth 3-D data
stream2
Compute 2-D stream line data
stream3
Compute 3-D stream line data
streamline
Draw stream lines from 2- or 3-D vector data
streamparticlesDraws stream particles from vector volume data
streamribbon Draws stream ribbons from vector volume data
streamslice Draws well-spaced stream lines from vector volume data
streamtube
Draws stream tubes from vector volume data
surf2patch
Convert surface data to patch data
subvolume
Extract subset of volume data set
volumebounds Return coordinate and color limits for volume (scalar and
vector)
1-47
1
Functions – By Category
Creating Graphical User Interfaces
Predefined dialog boxes and functions to control GUI programs.
Predefined Dialog Boxes
Dialog boxes for error, user input, waiting, etc.
Deploying User
Interfaces
Launching GUIs, creating the handles structure
Developing User
Interfaces
Starting GUIDE, managing application data,
getting user input
User Interface Objects
Creating GUI components
Finding Objects from
Callbacks
Finding object handles from within callbacks
functions
GUI Utility Functions
Moving objects, text wrapping
Controlling Program
Execution
Wait and resume based on user input
Predefined Dialog Boxes
dialog
errordlg
helpdlg
inputdlg
listdlg
msgbox
pagedlg
printdlg
questdlg
uigetdir
uigetfile
uiputfile
uisetcolor
uisetfont
waitbar
warndlg
1-48
Create dialog box
Create error dialog box
Display help dialog box
Create input dialog box
Create list selection dialog box
Create message dialog box
Display page layout dialog box
Display print dialog box
Create question dialog box
Display dialog box to retrieve name of directory
Display dialog box to retrieve name of file for reading
Display dialog box to retrieve name of file for writing
Set ColorSpec using dialog box
Set font using dialog box
Display wait bar
Create warning dialog box
Creating Graphical User Interfaces
Deploying User Interfaces
guidata
guihandles
movegui
openfig
Store or retrieve application data
Create a structure of handles
Move GUI figure onscreen
Open or raise GUI figure
Developing User Interfaces
guide
inspect
Open GUI Layout Editor
Display Property Inspector
Working with Application Data
getappdata
isappdata
rmappdata
setappdata
Get value of application data
True if application data exists
Remove application data
Specify application data
Interactive User Input
ginput
Graphical input from a mouse or cursor
waitfor
Wait for conditions before resuming execution
waitforbuttonpressWait for key/buttonpress over figure
User Interface Objects
menu
Generate menu of choices for user input
uicontextmenu Create context menu
uicontrol
Create user interface control
uimenu
Create user interface menu
Finding Objects from Callbacks
findall
findfigs
findobj
gcbf
gcbo
Find all graphics objects
Display off-screen visible figure windows
Find specific graphics object
Return handle of figure containing callback object
Return handle of object whose callback is executing
GUI Utility Functions
selectmoveresizeSelect, move, resize, or copy axes and uicontrol graphics
textwrap
objects
Return wrapped string matrix for given uicontrol
1-49
1
Functions – By Category
Controlling Program Execution
uiresume
uiwait
1-50
Resumes program execution halted with uiwait
Halts program execution, restart with uiresume
2
Functions – Alphabetical
List
2
Functions – Alphabetical List
Arithmetic Operators + - * / \ ^ ' . . . . . . . . . . . . . . . . . . . . . . .
Relational Operators < > <= >= == ~= . . . . . . . . . . . . . .
Logical Operators, Element-wise & | ~ . . . . . . . . . . . . . . . . . .
Logical Operators, Short-circuit && || . . . . . . . . . . . . . . . . . .
Special Characters [ ] ( ) {} = ' . ... , ; % ! . . . . . . . . . . . . . . . . . .
Colon : . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
acos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
acosh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
acot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
acoth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
acsc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
acsch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
actxcontrol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
actxserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
addframe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
addpath . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
addproperty (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
airy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
alim . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
all . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
allchild . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
alpha . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
alphamap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
angle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ans . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
any . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
area . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
asec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
asech . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
asin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
asinh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
assignin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atan2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
atanh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
audiodevinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-2
2-11
2-19
2-20
2-22
2-24
2-27
2-29
2-30
2-32
2-34
2-36
2-38
2-40
2-42
2-46
2-48
2-50
2-52
2-53
2-55
2-56
2-58
2-59
2-62
2-64
2-65
2-66
2-68
2-70
2-72
2-74
2-76
2-78
2-80
2-82
2-84
2-86
audioplayer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-88
audiorecorder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-92
auread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-97
auwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-98
avifile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-99
aviinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-102
aviread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-104
axes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-105
Axes Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-117
axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-138
balance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-144
bar, barh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-147
bar3, bar3h . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-151
base2dec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-155
beep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-156
besselh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-157
besseli . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-161
besselk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-164
besselj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-167
bessely . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-170
beta . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-173
betainc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-175
betaln . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-176
bicg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-177
bicgstab . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-184
bin2dec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-189
bitand . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-190
bitcmp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-191
bitget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-192
bitmax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-193
bitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-194
bitset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-195
bitshift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-196
bitxor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-197
blanks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-198
blkdiag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-199
box . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-200
2-3
2
Functions – Alphabetical List
break . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
brighten . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
builtin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bvp4c . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bvpget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bvpinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bvpset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
bvpval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
calendar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
camdolly . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
camlight . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
camlookat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
camorbit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
campan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
campos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
camproj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
camroll . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
camtarget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
camup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
camva . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
camzoom . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
capture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cart2pol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cart2sph . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
catch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
caxis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cdf2rdf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cdfepoch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cdfinfo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cdfread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cdfwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ceil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cell2mat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-4
2-201
2-202
2-204
2-205
2-212
2-213
2-215
2-218
2-219
2-220
2-222
2-224
2-226
2-228
2-229
2-231
2-232
2-233
2-235
2-237
2-239
2-240
2-241
2-242
2-243
2-244
2-245
2-246
2-250
2-251
2-253
2-254
2-258
2-260
2-263
2-264
2-266
cell2struct . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
celldisp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cellfun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cellplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cellstr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cgs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
char . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
checkin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
checkout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
chol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cholinc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cholupdate . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
circshift . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cla . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clabel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
class . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clear (serial) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clipboard . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
closereq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cmopts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
colamd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
colmmd . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
colorbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
colordef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
colormap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
colormapeditor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ColorSpec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
colperm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
comet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
comet3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
compan . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-268
2-269
2-270
2-272
2-273
2-274
2-278
2-280
2-282
2-285
2-287
2-294
2-297
2-298
2-299
2-301
2-303
2-304
2-308
2-309
2-310
2-311
2-312
2-314
2-315
2-316
2-317
2-319
2-322
2-324
2-326
2-330
2-346
2-348
2-349
2-350
2-351
2-5
2
Functions – Alphabetical List
compass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
complex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
computer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cond . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
condeig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
condest . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
coneplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
conj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
continue . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
contour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
contour3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
contourc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
contourf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
contourslice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
contrast . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
conv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
conv2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
convhull . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
convhulln . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
convn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
copyfile . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
copyobj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
corrcoef . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cosh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
coth . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cov . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cplxpair . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cputime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cross . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
csc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
csch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
csvread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
csvwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cumprod . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cumsum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-6
2-352
2-354
2-356
2-357
2-358
2-359
2-360
2-365
2-366
2-367
2-371
2-373
2-375
2-377
2-380
2-381
2-382
2-386
2-388
2-390
2-391
2-393
2-395
2-398
2-400
2-402
2-404
2-406
2-407
2-408
2-409
2-410
2-412
2-414
2-416
2-417
2-418
cumtrapz . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
curl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
customverctrl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
cylinder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
daspect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
datenum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
datestr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
datetick . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
datevec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbclear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbcont . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbdown . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dblquad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbmex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbquit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbstack . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbstatus . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbstep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbstop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbtype . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dbup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dde23 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ddeadv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ddeexec . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ddeget . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ddeinit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ddepoke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ddereq . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ddeset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ddeterm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ddeunadv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
deal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
deblank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dec2base . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dec2bin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dec2hex . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-419
2-421
2-424
2-425
2-428
2-431
2-432
2-434
2-437
2-440
2-442
2-444
2-445
2-446
2-448
2-449
2-450
2-451
2-452
2-453
2-457
2-458
2-459
2-463
2-465
2-466
2-467
2-468
2-470
2-472
2-475
2-476
2-477
2-479
2-480
2-481
2-482
2-7
2
Functions – Alphabetical List
deconv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
del2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
delaunay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
delaunay3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
delaunayn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
delete (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
delete (serial) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
delete (timer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
deleteproperty (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
demo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
depdir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
depfun . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
det . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
detrend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
deval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
diag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
diary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
diff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
disp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
disp (serial) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
disp (timer) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
divergence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dlmread . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dlmwrite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dmperm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
doc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
docopt . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
docroot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
double . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dragrect . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
drawnow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-8
2-483
2-484
2-487
2-492
2-495
2-498
2-499
2-501
2-502
2-503
2-504
2-507
2-508
2-512
2-513
2-515
2-517
2-519
2-520
2-521
2-523
2-525
2-526
2-527
2-529
2-531
2-533
2-534
2-535
2-536
2-537
2-538
2-539
2-541
2-542
2-543
2-544
dsearch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
dsearchn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
echo . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
edit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
eig . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
eigs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ellipj . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ellipke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ellipsoid . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
else . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
elseif . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
end . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
eomday . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
eps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
erf, erfc, erfcx, erfinv, erfcinv . . . . . . . . . . . . . . . . . . . . . . . . .
error . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
errorbar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
errordlg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
etime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
etree . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
etreeplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
eval . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
evalc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
evalin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
eventlisteners (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
events (COM) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
exist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
exit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
exp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
expint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
expm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
eye . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ezcontour . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ezcontourf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ezmesh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ezmeshc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ezplot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-545
2-546
2-547
2-548
2-550
2-554
2-562
2-564
2-566
2-567
2-568
2-570
2-572
2-573
2-574
2-576
2-578
2-580
2-582
2-583
2-584
2-585
2-587
2-588
2-590
2-592
2-594
2-596
2-597
2-598
2-599
2-601
2-602
2-605
2-608
2-610
2-612
2-9
2
Functions – Alphabetical List
ezplot3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ezpolar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ezsurf . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
ezsurfc . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
2-10
2-614
2-616
2-618
2-621
Arithmetic Operators + - * / \ ^ '
Purpose
Syntax
Description
2Arithmetic Operators + - * / \ ^ '
Matrix and array arithmetic
A+B
A-B
A∗B
A/B
A\B
A^B
A'
A.∗B
A./B
A.\B
A.^B
A.'
MATLAB has two different types of arithmetic operations. Matrix arithmetic
operations are defined by the rules of linear algebra. Array arithmetic
operations are carried out element-by-element, and can be used with
multidimensional arrays. The period character (.) distinguishes the array
operations from the matrix operations. However, since the matrix and array
operations are the same for addition and subtraction, the character pairs .+
and .- are not used.
+
Addition or unary plus. A+B adds A and B. A and B must have the same
size, unless one is a scalar. A scalar can be added to a matrix of any size.
-
Subtraction or unary minus. A-B subtracts B from A. A and B must have
the same size, unless one is a scalar. A scalar can be subtracted from a
matrix of any size.
*
Matrix multiplication. C = A∗B is the linear algebraic product of the
matrices A and B. More precisely,
n
C ( i, j ) =
∑
A ( i, k )B ( k, j )
k=1
For nonscalar A and B, the number of columns of A must equal the
number of rows of B. A scalar can multiply a matrix of any size.
.∗
Array multiplication. A.∗B is the element-by-element product of the
arrays A and B. A and B must have the same size, unless one of them is a
scalar.
/
Slash or matrix right division. B/A is roughly the same as B∗inv(A).
More precisely, B/A = (A'\B')'. See \.
2-11
Arithmetic Operators + - * / \ ^ '
./
Array right division. A./B is the matrix with elements A(i,j)/B(i,j).
A and B must have the same size, unless one of them is a scalar.
\
Backslash or matrix left division. If A is a square matrix, A\B is roughly
the same as inv(A)∗B, except it is computed in a different way. If A is
an n-by-n matrix and B is a column vector with n components, or a
matrix with several such columns, then X = A\B is the solution to the
equation AX = B computed by Gaussian elimination (see “Algorithm” on
page 2-15 for details). A warning message prints if A is badly scaled or
nearly singular.
If A is an m-by-n matrix with m ~= n and B is a column vector with m
components, or a matrix with several such columns, then X = A\B is the
solution in the least squares sense to the under- or overdetermined
system of equations AX = B. The effective rank, k, of A, is determined
from the QR decomposition with pivoting (see “Algorithm” for details).
A solution X is computed which has at most k nonzero components per
column. If k < n, this is usually not the same solution as pinv(A)∗B,
which is the least squares solution with the smallest norm, X .
.\
Array left division. A.\B is the matrix with elements B(i,j)/A(i,j). A
and B must have the same size, unless one of them is a scalar.
^
Matrix power. X^p is X to the power p, if p is a scalar. If p is an integer,
the power is computed by repeated squaring. If the integer is negative,
X is inverted first. For other values of p, the calculation involves
eigenvalues and eigenvectors, such that if [V,D] = eig(X), then
X^p = V∗D.^p/V.
If x is a scalar and P is a matrix, x^P is x raised to the matrix power P
using eigenvalues and eigenvectors. X^P, where X and P are both
matrices, is an error.
2-12
.^
Array power. A.^B is the matrix with elements A(i,j) to the B(i,j)
power. A and B must have the same size, unless one of them is a scalar.
'
Matrix transpose. A' is the linear algebraic transpose of A. For complex
matrices, this is the complex conjugate transpose.
.'
Array transpose. A.' is the array transpose of A. For complex matrices,
this does not involve conjugation.
Arithmetic Operators + - * / \ ^ '
Remarks
Examples
The arithmetic operators have M-file function equivalents, as shown:
Binary addition
A+B
plus(A,B)
Unary plus
+A
uplus(A)
Binary subtraction
A-B
minus(A,B)
Unary minus
-A
uminus(A)
Matrix multiplication
A*B
mtimes(A,B)
Array-wise multiplication
A.*B
times(A,B)
Matrix right division
A/B
mrdivide(A,B)
Array-wise right division
A./B
rdivide(A,B)
Matrix left division
A\B
mldivide(A,B)
Array-wise left division
A.\B
ldivide(A,B)
Matrix power
A^B
mpower(A,B)
Array-wise power
A.^B
power(A,B)
Complex transpose
A'
ctranspose(A)
Matrix transpose
A.'
transpose(A)
Here are two vectors, and the results of various matrix and array operations on
them, printed with format rat.
Matrix Operations
Array Operations
x
1
2
3
x'
1
x+y
5
7
9
2
3
y
4
5
6
y'
4
x-y
5
6
-3
-3
-3
2-13
Arithmetic Operators + - * / \ ^ '
Matrix Operations
2-14
Array Operations
x + 2
3
4
5
x-2
-1
0
1
x ∗ y
Error
x.∗y
4
10
18
x'∗y
32
x'.∗y
Error
x∗y'
4
8
12
x.∗y'
Error
x∗2
2
4
6
x.∗2
2
4
6
x\y
16/7
x.\y
4
5/2
2
2\x
1/2
1
3/2
2./x
2
1
2/3
x/y
0
0
0
x./y
1/4
2/5
1/2
x/2
1/2
1
3/2
x./2
1/2
1
3/2
x^y
Error
x.^y
1
32
729
x^2
Error
x.^2
1
4
9
5
10
15
0
0
0
6
12
18
1/6
1/3
1/2
Arithmetic Operators + - * / \ ^ '
Matrix Operations
Algorithm
Array Operations
2^x
Error
2.^x
(x+i∗y)'
1 - 4i
2 - 5i
3 - 6i
(x+i∗y).'
1 + 4i
2 + 5i
3 + 6i
2
4
8
The specific algorithm used for solving the simultaneous linear equations
denoted by X = A\B and X = B/A depends upon the structure of the coefficient
matrix A. To determine the structure of A and select the appropriate algorithm,
MATLAB follows this precedence:
1 If A is sparse, square, and banded, then banded solvers are used. Band
density is (# nonzeros in the band)/(# nonzeros in a full band).
Band density = 1.0 if there are no zeros on any of the three diagonals.
- If A is real and tridiagonal, i.e., band density = 1.0, and B is real with only
one column, X is computed quickly using Gaussian elimination without
pivoting.
- If the tridiagonal solver detects a need for pivoting, or if A or B is not real,
or if B has more than one column, but A is banded with band density
greater than the spparms parameter 'bandden' (default = 0.5), then X is
computed using LAPACK.
2 If A is an upper or lower triangular matrix, then X is computed quickly
with a backsubstitution algorithm for upper triangular matrices, or a
forward substitution algorithm for lower triangular martrices. The check for
triangularity is done for full matrices by testing for zero elements and for
sparse matrices by accessing the sparse data structure.
3 If A is a permutation of a triangular matrix, then X is computed with a
permuted backsubstitution algorithm.
4 If A is symmetric, or Hermitian, and has positive diagonal elements,
then a Cholesky factorization is attempted (see chol). If A is found to be
positive definite, the Cholesky factorization attempt is successful and
requires less than half the time of a general factorization. Nonpositive
definite matrices are usually detected almost immediately, so this check
also requires little time. If successful, the Cholesky factorization is
2-15
Arithmetic Operators + - * / \ ^ '
A = R'∗R
where R is upper triangular. The solution X is computed by solving two
triangular systems,
X = R\(R'\B)
If A is sparse, a symmetric minimum degree preordering is applied (see
symmmd and spparms). The algorithm is:
perm = symmmd(A);
R = chol(A(perm,perm));
Y = R'\B(perm);
X(perm,:) = R\Y;
%
%
%
%
Symmetric minimum degree reordering
Cholesky factorization
Lower triangular solve
Upper triangular solve
5 If A is Hessenberg, but not sparse, it is reduced to an upper triangular
matrix and that system is solved via substitution.
6 If A is square, and does not satisfy criteria 1 through 5, then a general
triangular factorization is computed by Gaussian elimination with partial
pivoting (see lu). This results in
A = L∗U
where L is a permutation of a lower triangular matrix and U is an upper
triangular matrix. Then X is computed by solving two permuted triangular
systems.
X = U\(L\B)
If A is sparse, then UMFPACK is used to compute X. The computations
result in
P*A*Q = L*U
where P is a row permutaion matrix and Q is a column reordering matrix.
Then X = Q*(U\L\(P*B)).
7 If A is not square, then Householder reflections are used to compute an
orthogonal-triangular factorization.
A∗P = Q∗R
where P is a permutation, Q is orthogonal and R is upper triangular (see qr).
The least squares solution X is computed with
2-16
Arithmetic Operators + - * / \ ^ '
X = P∗(R\(Q'∗B))
If A is sparse, then MATLAB computes a least squares solution using the
sparse qr factorization of A.
Note For sparse matrices, to see information about choice of algorithm and
storage allocation, set the spparms parameter 'spumoni' = 1.
Note Backslash is not implemented for sparse matrices A that are complex
but not square.
MATLAB uses LAPACK routines to compute these matrix factorizations:
Matrix
Real
Complex
Sparse square banded with band
density > 'bandden'.
DGBTRF, DGBTRS
ZGBTRF,
ZGBTRS
Full square, symmetric (Hermitian)
positive definite
DLANGE, DPOTRF,
DPOTRS, DPOCON
ZLANGE, ZPOTRF,
ZPOTRS ZPOCON
Full square, general case
DLANGE, DGESV,
DGECON
ZLANGE, ZGESV,
ZGECON
Full non-square
DGEQP3, DORMQR,
DTRTRS
ZGEQP3, ZORMQR,
ZTRTRS
For other cases (sparse, triangular and Hessenberg) MATLAB does not use
LAPACK.
Diagnostics
• From matrix division, if a square A is singular:
Warning: Matrix is singular to working precision.
• From element-wise division, if the divisor has zero elements:
2-17
Arithmetic Operators + - * / \ ^ '
Warning: Divide by zero.
Matrix division and element-wise division may produce NaNs or Infs where
appropriate.
• If the inverse was found, but is not reliable:
Warning: Matrix is close to singular or badly scaled.
Results may be inaccurate. RCOND = xxx
• From matrix division, if a nonsquare A is rank deficient:
Warning: Rank deficient, rank = xxx tol = xxx
See Also
chol, det, inv, lu, orth, permute, ipermute, qr, rref
References
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra,
J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen,
LAPACK User’s Guide
(http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition,
SIAM, Philadelphia, 1999.
[2] Davis, T.A., UMFPACK Version 4.0 User Guide
(http://www.cise.ufl.edu/research/sparse/umfpack/v4.0/UserGuide.pdf),
Dept. of Computer and Information Science and Engineering, Univ. of Florida,
Gainesville, FL, 2002.
2-18
Relational Operators <
Purpose
2Relational Operators <
> <=
> <=
>= == ~=
>= == ~=
Relational operations
Syntax
A
A
A
A
A
A
Description
The relational operators are <, >, <=, >=, ==, and ~=. Relational operators
perform element-by-element comparisons between two arrays. They return a
logical array of the same size, with elements set to true (1) where the relation
is true, and elements set to false (0) where it is not.
< B
> B
<= B
>= B
== B
~= B
The operators <, >, <=, and >= use only the real part of their operands for the
comparison. The operators == and ~= test real and imaginary parts.
To test if two strings are equivalent, use strcmp, which allows vectors of
dissimilar length to be compared.
Examples
If one of the operands is a scalar and the other a matrix, the scalar expands to
the size of the matrix. For example, the two pairs of statements:
X = 5; X >= [1 2 3; 4 5 6; 7 8 10]
X = 5∗ones(3,3); X >= [1 2 3; 4 5 6; 7 8 10]
produce the same result:
ans =
1
1
0
See Also
1
1
0
1
0
0
all, any, find, strcmp
The logical operators &, |, ~
2-19
Logical Operators, Element-wise & | ~
Purpose
2Logical Operators, Element-wise & | ~
Element-wise logical operations on arrays
Syntax
A & B
A | B
~A
Description
The symbols &, |, and ~ are the logical array operators AND, OR, and NOT. They
work element-by-element on arrays, with 0 representing logical false (F), and
anything nonzero representing logical true (T). The logical operators return a
logical array with elements set to true (1) or false (0), as appropriate.
The & operator does a logical AND, the | operator does a logical OR, and ~A
complements the elements of A. The function xor(A,B) implements the
exclusive OR operation. The truth table for these operators and functions is
shown below.
Inputs
A
B
and
A & B
or
A | B
not
~A
xor
xor(A,B)
0
0
0
0
1
0
0
1
0
1
1
1
1
0
0
1
0
1
1
1
1
1
0
0
The precedence for the logical operators with respect to each other is
2-20
Operator
Operation
Priority
~
NOT
Highest
&
Element-wise AND
|
Element-wise OR
&&
Short-circuit AND
||
Short-circuit OR
Lowest
Logical Operators, Element-wise & | ~
Remarks
MATLAB always gives the & operator precedence over the | operator. Although
MATLAB typically evaluates expressions from left to right, the expression
a|b&c is evaluated as a|(b&c). It is a good idea to use parentheses to explicitly
specify the intended precedence of statements containing combinations of &
and |.
These logical operators have M-file function equivalents, as shown.
Examples
Logical Operation
Equivalent Function
A & B
and(A,B)
A | B
or(A,B)
~A
not(A)
This example shows the logical OR of the elements in the vector u with the
corresponding elements in the vector v:
u = [0 0 1 1 0 1];
v = [0 1 1 0 0 1];
u | v
ans =
0
See Also
1
1
1
0
1
all, any, find, logical, xor, true, false
Logical Operators, Short-circuit: &&, ||
Relational Operators: <, <=, >, >=, ==, ~=
2-21
Logical Operators, Short-circuit && ||
Purpose
2Logical Operators, Short-circuit && ||
Logical operations, with short-circuiting capability
Syntax
A && B
A || B
Description
The symbols && and || are the logical AND and OR operators used to evaluate
logical expressions. Use && and || in the evaluation of compound expressions
of the form
expression_1 && expression_2
where expression_1 and expression_2 each evaluate to a scalar, logical
result.
The && and || operators support short-circuiting. This means that the second
operand is evaluated only when the result is not fully determined by the first
operand. See “Short-circuit Operators” in the MATLAB documentation for a
discussion on short-circuiting with && and ||.
Note Always use the && and || operators when short-circuiting is required.
Using the element-wise operators (& and |) for short-circuiting may yield
unexpected results.
Examples
In the following statement, it doesn’t make sense to evaluate the relation on
the right if the divisor, b, is zero. The test on the left is put in to avoid
generating a warning under these circumstances:
x = (b ~= 0) && (a/b > 18.5)
By definition, if any operands of an AND expression are false, the entire
expression must be false. So, if (b ~= 0) evaluates to false, MATLAB
assumes the entire expression to be false and terminates its evaluation of the
expression early. This avoids the warning that would be generated if MATLAB
were to evaluate the operand on the right.
2-22
Logical Operators, Short-circuit && ||
See Also
all, any, find, logical, xor, true, false
Logical operators, Element-wise: &, |, ~
Relational Operators: <, <=, >, >=, ==, ~=
2-23
Special Characters [ ] ( ) {} = ' . ... , ; % !
Purpose
Syntax
2Special Characters [ ] ( ) {} = ' . ... , ; % !
Special characters
[ ] ( ) {} = ' . ... , ; % !
Description
2-24
[ ]
Brackets are used to form vectors and matrices. [6.9 9.64 sqrt(-1)]
is a vector with three elements separated by blanks. [6.9, 9.64, i]
is the same thing. [1+j 2-j 3] and [1 +j 2 -j 3] are not the same.
The first has three elements, the second has five.
[11 12 13; 21 22 23] is a 2-by-3 matrix. The semicolon ends the
first row.
Vectors and matrices can be used inside [ ] brackets. [A B;C] is
allowed if the number of rows of A equals the number of rows of B and
the number of columns of A plus the number of columns of B equals the
number of columns of C. This rule generalizes in a hopefully obvious
way to allow fairly complicated constructions.
A = [ ] stores an empty matrix in A. A(m,:) = [ ] deletes row m of A.
A(:,n) = [ ] deletes column n of A. A(n) = [ ] reshapes A into a
column vector and deletes the third element.
[A1,A2,A3...] = function assigns function output to multiple
variables.
For the use of [ and ] on the left of an “=” in multiple assignment
statements, see lu, eig, svd, and so on.
{ }
Curly braces are used in cell array assignment statements. For
example,
A(2,1) = {[1 2 3; 4 5 6]}, or A{2,2} = ('str'). See help paren
for more information about { }.
Special Characters [ ] ( ) {} = ' . ... , ; % !
( )
Parentheses are used to indicate precedence in arithmetic expressions
in the usual way. They are used to enclose arguments of functions in
the usual way. They are also used to enclose subscripts of vectors and
matrices in a manner somewhat more general than usual. If X and V
are vectors, then X(V) is [X(V(1)), X(V(2)), ..., X(V(n))]. The
components of V must be integers to be used as subscripts. An error
occurs if any such subscript is less than 1 or greater than the size of X.
Some examples are
• X(3) is the third element of X.
• X([1 2 3]) is the first three elements of X.
See help paren for more information about ( ).
If X has n components, X(n:–1:1) reverses them. The same indirect
subscripting works in matrices. If V has m components and W has n
components, then A(V,W) is the m-by-n matrix formed from the
elements of A whose subscripts are the elements of V and W. For
example, A([1,5],:) = A([5,1],:) interchanges rows 1 and 5 of A.
=
Used in assignment statements. B = A stores the elements of A in B.
== is the relational equals operator. See the Relational Operators
page.
'
Matrix transpose. X' is the complex conjugate transpose of X. X.' is
the nonconjugate transpose.
Quotation mark. 'any text' is a vector whose components are the
ASCII codes for the characters. A quotation mark within the text is
indicated by two quotation marks.
.
Decimal point. 314/100, 3.14 and .314e1 are all the same.
Element-by-element operations. These are obtained using .∗ , .^ , ./,
or .\. See the Arithmetic Operators page.
.
Field access. A.(field) and A(i).field, when A is a structure, access
the contents of field.
..
Parent directory. See cd.
...
Continuation. Three or more points at the end of a line indicate
continuation.
2-25
Special Characters [ ] ( ) {} = ' . ... , ; % !
Remarks
See Also
,
Comma. Used to separate matrix subscripts and function arguments.
Used to separate statements in multistatement lines. For
multi-statement lines, the comma can be replaced by a semicolon to
suppress printing.
;
Semicolon. Used inside brackets to end rows. Used after an expression
or statement to suppress printing or to separate statements.
%
Percent. The percent symbol denotes a comment; it indicates a logical
end of line. Any following text is ignored. MATLAB displays the first
contiguous comment lines in a M-file in response to a help command.
!
Exclamation point. Indicates that the rest of the input line is issued
as a command to the operating system. On the PC, adding & to the end
of the ! command line, as in !dir &, causes the output to appear in a
separate window.
Some uses of special characters have M-file function equivalents, as shown:
Horizontal concatenation
[A,B,C...]
horzcat(A,B,C...)
Vertical concatenation
[A;B;C...]
vertcat(A,B,C...)
Subscript reference
A(i,j,k...)
subsref(A,S). See help
subsref.
Subscript assignment
A(i,j,k...)= B
subsasgn(A,S,B). See help
subsasgn.
The arithmetic operators +, –, *, /, \, ^, '
The relational operators <, <=, >, >=, ==, ~=
The logical operators &, |, ~
2-26
Colon :
Purpose
2Colon :
Description
The colon is one of the most useful operators in MATLAB. It can create vectors,
subscript arrays, and specify for iterations.
Create vectors, array subscripting, and for loop iterations
The colon operator uses the following rules to create regularly spaced vectors:
j:k
is the same as [j,j+1,...,k]
j:k
is empty if j > k
j:i:k
is the same as [j,j+i,j+2i, ...,k]
j:i:k
is empty if i > 0 and j > k or if i < 0 and j < k
where i,j, and k are all scalars.
Below are the definitions that govern the use of the colon to pick out selected
rows, columns, and elements of vectors, matrices, and higher-dimensional
arrays:
A(:,j)
is the j-th column of A
A(i,:)
is the i-th row of A
A(:,:)
is the equivalent two-dimensional array. For matrices this is
the same as A.
A(j:k)
is A(j), A(j+1),...,A(k)
A(:,j:k)
is A(:,j), A(:,j+1),...,A(:,k)
A(:,:,k)
is the kth page of three-dimensional array A.
A(i,j,k,:)
is a vector in four-dimensional array A. The vector includes
A(i,j,k,1), A(i,j,k,2), A(i,j,k,3), and so on.
A(:)
is all the elements of A, regarded as a single column. On the
left side of an assignment statement, A(:) fills A, preserving
its shape from before. In this case, the right side must contain
the same number of elements as A.
2-27
Colon :
Examples
Using the colon with integers,
D = 1:4
results in
D =
1
2
3
4
Using two colons to create a vector with arbitrary real increments between the
elements,
E = 0:.1:.5
results in
E =
0
0.1000
0.2000
0.3000
0.4000
0.5000
The command
A(:,:,2) = pascal(3)
generates a three-dimensional array whose first page is all zeros.
See Also
2-28
A(:,:,1) =
0
0
0
0
0
0
0
0
0
A(:,:,2) =
1
1
1
2
1
3
1
3
6
for, linspace, logspace, reshape
abs
Purpose
2abs
Absolute value and complex magnitude
Syntax
Y = abs(X)
Description
abs(X) returns an array Y such that each element of Y is the absolute value of
the corresponding element of X.
If X is complex, abs(X) returns the complex modulus (magnitude), which is the
same as
sqrt(real(X).^2 + imag(X).^2)
Examples
abs(-5)
ans =
5
abs(3+4i)
ans =
5
See Also
angle, sign, unwrap
2-29
acos
Purpose
2acos
Inverse cosine
Syntax
Y = acos(X)
Description
Y = acos(X) returns the inverse cosine (arccosine) for each element of X. For
real elements of X in the domain [ – 1, 1 ] , acos(X) is real and in the range
[ 0, π ] . For real elements of X outside the domain [ – 1, 1 ] , acos(X) is complex.
The acos function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse cosine function over the domain – 1 ≤ x ≤ 1 .
x = -1:.05:1;
plot(x,acos(x)), grid on
3.5
3
2.5
2
1.5
1
0.5
0
−1
Definition
0
0.5
The inverse cosine can be defined as
–1
cos ( z)
2-30
−0.5
1
--2 2
= – i log z + i ( 1 – z )
1
acos
Algorithm
acos uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
See Also
acosh, cos
2-31
acosh
Purpose
2acosh
Inverse hyperbolic cosine
Syntax
Y = acosh(X)
Description
Y = acosh(X) returns the inverse hyperbolic cosine for each element of X.
The acosh function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse hyperbolic cosine function over the domain 1 ≤ x ≤ π .
x = 1:pi/40:pi;
plot(x,acosh(x)), grid on
2
1.8
1.6
1.4
1.2
1
0.8
0.6
0.4
0.2
0
1
Definition
1.5
2
2.5
3.5
The hyperbolic inverse cosine can be defined as
–1
2
cosh ( z ) = log z + ( z – 1 )
Algorithm
3
1
--2
acosh uses FDLIBM, which was developed at SunSoft, a Sun Microsystems,
Inc. business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-32
acosh
See Also
acos, cosh
2-33
acot
Purpose
2acot
Inverse cotangent
Syntax
Y = acot(X)
Description
Y = acot(X) returns the inverse cotangent (arccotangent) for each element of X.
The acot function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse cotangent over the domains – 2π ≤ x < 0 and 0 < x ≤ 2π .
x1 = -2*pi:pi/30:-0.1;
x2 = 0.1:pi/30:2*pi;
plot(x1,acot(x1),x2,acot(x2)), grid on
1.5
1
0.5
0
−0.5
−1
−1.5
−8
Definition
−6
−4
−2
0
2
4
6
8
The inverse cotangent can be defined as
1
cot– 1 ( z ) = tan– 1  --- 
 z
Algorithm
acot uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-34
acot
See Also
cot, acoth
2-35
acoth
Purpose
2acoth
Inverse hyperbolic cotangent
Syntax
Y = acoth(X)
Description
Y = acoth(X) returns the inverse hyperbolic cotangent for each element of X.
The acoth function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse hyperbolic cotangent over the domains – 30 ≤ x < – 1 and
1 < x ≤ 30 .
x1 = -30:0.1:-1.1;
x2 = 1.1:0.1:30;
plot(x1,acoth(x1),x2,acoth(x2)), grid on
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
−30
Definition
−20
−10
10
20
30
The hyperbolic inverse cotangent can be defined as
1
coth– 1 ( z ) = tanh– 1  --- 
 z
2-36
0
acoth
Algorithm
acoth uses FDLIBM, which was developed at SunSoft, a Sun Microsystems,
Inc. business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
See Also
acot, coth
2-37
acsc
Purpose
2acsc
Inverse cosecant
Syntax
Y = acsc(X)
Description
Y = acsc(X) returns the inverse cosecant (arccosecant) for each element of X.
The acsc function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse cosecant over the domains – 10 ≤ x < – 1 and 1 < x ≤ 10 .
x1 = -10:0.01:-1.01;
x2 = 1.01:0.01:10;
plot(x1,acsc(x1),x2,acsc(x2)), grid on
1.5
1
0.5
0
−0.5
−1
−1.5
−10
Definition
−5
0
5
10
The inverse cosecant can be defined as
1
csc– 1 ( z ) = sin– 1  --- 
 z
Algorithm
acsc uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-38
acsc
See Also
csc, acsch
2-39
acsch
Purpose
2acsch
Inverse cosecant and inverse hyperbolic cosecant
Syntax
Y = acsch(X)
Description
Y = acsch(X) returns the inverse hyperbolic cosecant for each element of X.
The acsch function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse hyperbolic cosecant over the domains – 20 ≤ x ≤ – 1 and
1 ≤ x ≤ 20 .
x1 = -20:0.01:-1;
x2 = 1:0.01:20;
plot(x1,acsch(x1),x2,acsch(x2)), grid on
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
−20
Definition
−15
−10
−5
5
10
15
The hyperbolic inverse cosecant can be defined as
1
csch– 1 ( z ) = sinh– 1  --- 
z
2-40
0
20
acsch
Algorithm
acsc uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
See Also
acsc, csch
2-41
actxcontrol
Purpose
2actxcontrol
Create a COM control in a figure window
Syntax
h = actxcontrol (progid [, position [, fig_handle ...
[, callback | {event1 eventhandler1; event2 eventhandler2; ...}
[, filename]]]])
Arguments
progid
String that is the name of the control to create. The control vendor provides this
string.
position
Position vector containing the x and y location and the xsize and ysize of the
control, expressed in pixel units as [x y xsize ysize]. Defaults to [20 20 60
60].
fig_handle
Handle Graphics handle of the figure window in which the control is to be
created. If the control should be invisible, use the handle of an invisible figure
window. Defaults to gcf.
callback
Name of an M-function that accepts a variable number of arguments. This
function will be called whenever the control triggers an event. Each argument
is converted to a MATLAB string. See the section, “Writing Event Handlers” in
the External Interfaces documentation for more information on handling
control events.
event
Triggered event specified by either number or name.
eventhandler
Name of an M-function that accepts a variable number of arguments. This
function will be called whenever the control triggers the event associated with
it. See “Writing Event Handlers” in the External Interfaces documentation for
more information on handling control events.
filename
The name of a file to which a previously created control has been saved. When
you specify filename, MATLAB creates a new control using the position,
handle, and event/eventhandler arguments, and then initializes the control
from the specified file. The progid argument in actxcontrol must match the
progid of the saved control.
2-42
actxcontrol
Description
Create a COM control at a particular location within a figure window. If the
parent figure window is invisible, the control will be invisible. The returned
COM object represents the default interface for the control. This interface must
be released through a call to release when it is no longer needed to free the
memory and resources used by the interface. Note that releasing the interface
does not delete the control itself (use the delete command to delete the
control.)
The strings specified in the callback, event, and eventhandler arguments are
not case sensitive.
Note There are two ways to handle events. You can create a single handler
(callback) for all events, or you can specify a cell array that contains pairs of
events and event handlers. In the cell array format, specify events by name in
a quoted string. There is no limit to the number of pairs that can be specified
in the cell array. Although using the single callback method may be easier in
some cases, using the cell array technique creates more efficient code that
results in better performance.
For an example callback event handler, see the file sampev.m in the
toolbox\matlab\winfun\comcli directory.
Examples
Basic Control Methods
Create a control that runs Microsoft’s Calendar application:
f = figure('pos',[300 300 500 500]);
cal = actxcontrol('mscal.calendar', [0 0 500 500], f)
cal =
COM.mscal.calendar
Call the get method on cal to list all properties of the Calendar:
get(cal)
BackColor:
Day:
DayFont:
Value:
.
2.1475e+009
23
[1x1 Interface.mscal.calendar.DayFont]
'8/20/2001'
2-43
actxcontrol
.
Read just one property to record today’s date:
date = get(cal, 'Value')
date =
8/23/2001
Set the Day property to a new value:
set(cal, 'Day', 5);
date = get(cal, 'Value')
date =
8/5/2001
Calling invoke with no arguments lists all available methods:
meth = invoke(cal)
meth =
NextDay:
NextMonth:
NextWeek:
NextYear:
.
.
'HRESULT
'HRESULT
'HRESULT
'HRESULT
NextDay(handle)'
NextMonth(handle)'
NextWeek(handle)'
NextYear(handle)'
Invoke the NextWeek method to advance the current date by one week:
NextWeek(cal);
date = get(cal, 'Value')
date =
8/12/2001
Call events to list all Calendar events that can be triggered:
events(cal)
ans =
Click = void Click()
DblClick = void DblClick()
KeyDown = void KeyDown(int16 KeyCode, int16 Shift)
KeyPress = void KeyPress(int16 KeyAscii)
KeyUp = void KeyUp(int16 KeyCode, int16 Shift)
BeforeUpdate = void BeforeUpdate(int16 Cancel)
AfterUpdate = void AfterUpdate()
2-44
actxcontrol
NewMonth = void NewMonth()
NewYear = void NewYear()
Set Up Event Handling
See the section, Sample Event Handlers in the External Interfaces
documentation for examples of event handler functions and how to register
them with MATLAB.
See Also
actxserver, release, delete, save, load
2-45
actxserver
Purpose
2actxserver
Create a COM Automation server and return a COM object for the server’s
default interface
Syntax
h = actxserver (progid [, machinename])
Arguments
progid
This is a string that is the name of the control to instantiate. This string is
provided by the control or server vendor and should be obtained from the
vendor’s documentation. For example, the progid for MATLAB is
matlab.application.
machinename
This is the name of a remote machine on which the server is to be run. This
argument is optional and is used only in environments that support
Distributed Component Object Model (DCOM) — see “Using MATLAB As a
DCOM Server Client” in the External Interfaces documentation. This can be
an IP address or a DNS name.
Description
Create a COM Automation server and return a COM object that represents the
server’s default interface. Local/Remote servers differ from controls in that
they are run in a separate address space (and possibly on a separate machine)
and are not part of the MATLAB process. Additionally, any user interface that
they display will be in a separate window and will not be attached to the
MATLAB process. Examples of local servers are Microsoft Excel and Microsoft
Word. There is currently no support for events generated from automation
servers.
Examples
Launch Microsoft Excel and make the main frame window visible:
e = actxserver ('Excel.Application')
e =
COM.excel.application
set(e, 'Visible', 1);
2-46
actxserver
Call the get method on the excel object to list all properties of the application:
get(e)
ans =
Application: [1x1 Interface.excel.application.Application]
Creator: 'xlCreatorCode'
Parent: [1x1 Interface.Excel.Application.Parent]
Workbooks: [1x1 Interface.excel.application.Workbooks]
UsableHeight: 666.7500
.
.
Create an interface:
eWorkbooks = get(e, 'Workbooks')
eWorkbooks =
Interface.excel.application.Workbooks
List all methods for that interface by calling invoke with just the handle
argument:
invoke(eWorkbooks)
ans =
Add: 'handle Add(handle, [Optional]Variant)'
Close: 'void Close(handle)'
Item: 'handle Item(handle, Variant)'
Open: 'handle Open(handle, string, [Optional]Variant)'
OpenText: 'void OpenText(handle, string, [Optional]Variant)'
Invoke the Add method on workbooks to add a new workbook, also creating a
new interface:
w = Add(eWorkbooks)
w =
Interface.Excel.Application.Workbooks.Add
Quit the application and delete the object:
Quit(e);
delete(e);
See Also
actxcontrol, release, delete, save, load
2-47
addframe
Purpose
2addframe
Add a frame to an Audio Video Interleaved (AVI) file.
Syntax
aviobj
aviobj
aviobj
aviobj
Description
aviobj = addframe(aviobj,frame) appends the data in frame to the AVI file
identified by aviobj, which was created by a previous call to avifile. frame
can be either an indexed image (m-by-n) or a truecolor image (m-by-n-by-3) of
double or uint8 precision. If frame is not the first frame added to the AVI file,
=
=
=
=
addframe(aviobj,frame)
addframe(aviobj,frame1,frame2,frame3,...)
addframe(aviobj,mov)
addframe(aviobj,h)
it must be consistent with the dimensions of the previous frames.
addframe returns a handle to the updated AVI file object, aviobj. For example,
addframe updates the TotalFrames property of the AVI file object each time it
adds a frame to the AVI file.
aviobj = addframe(aviobj,frame1,frame2,frame3,...) adds multiple
frames to an AVI file.
aviobj = addframe(aviobj,mov) appends the frame(s) contained in the
MATLAB movie, mov, to the AVI file, aviobj. MATLAB movies that store
frames as indexed images use the colormap in the first frame as the colormap
for the AVI file, unless the colormap has been previously set.
aviobj = addframe(aviobj,h) captures a frame from the figure or axis handle
h, and appends this frame to the AVI file. addframe renders the figure into an
offscreen array before appending it to the AVI file. This ensures that the figure
is written correctly to the AVI file even if the figure is obscured on the screen
by another window or screen saver.
Note If an animation uses XOR graphics, you must use getframe to capture
the graphics into a frame of a MATLAB movie. You can then add the frame to
an AVI movie using the addframe syntax, aviobj = addframe(aviobj,mov).
See the example for an illustration.
Example
2-48
This example calls addframe to add frames to the AVI file object, aviobj.
addframe
fig=figure;
set(fig,'DoubleBuffer','on');
set(gca,'xlim',[-80 80],'ylim',[-80 80],...
'nextplot','replace','Visible','off')
aviobj = avifile('example.avi')
x = -pi:.1:pi;
radius = 0:length(x);
for i=1:length(x)
h = patch(sin(x)*radius(i),cos(x)*radius(i),...
[abs(cos(x(i))) 0 0]);
set(h,'EraseMode','xor');
frame = getframe(gca);
aviobj = addframe(aviobj,frame);
end
aviobj = close(aviobj);
See Also
avifile, close, movie2avi
2-49
addpath
Purpose
2addpath
Graphical
Interface
As an alternative to the addpath function, use the Set Path dialog box. To open
it, select Set Path from the File menu in the MATLAB desktop.
Syntax
addpath('directory')
addpath('dir','dir2','dir3' ...)
addpath('dir','dir2','dir3' ...'-flag')
addpath dir1 dir2 dir3 ... -flag
Description
addpath('directory') prepends the specified directory to the current
Add directories to MATLAB search path
MATLAB search path, that is, it adds them to the top of the path. Use the full
pathname for directory.
addpath('dir','dir2','dir3' ...) prepends all the specified directories to
the path. Use the full pathname for each dir.
addpath('dir','dir2','dir3' ...'-flag') either prepends or appends the
specified directories to the path depending on the value of flag.
flag Argument
Result
0 or begin
Prepend specified directories
1 or end
Append specified directories (add to bottom/end)
addpath dir1 dir2 dir3 ... -flag is the unquoted form of the syntax.
Examples
For the current path, viewed by typing path,
MATLABPATH
c:\matlab\toolbox\general
c:\matlab\toolbox\ops
c:\matlab\toolbox\strfun
you can add c:/matlab/mymfiles to the front of the path by typing
addpath('c:/matlab/mymfiles')
2-50
addpath
Verify that the files were added to the path by typing
path
and MATLAB returns
MATLABPATH
c:\matlab\mymfiles
c:\matlab\toolbox\general
c:\matlab\toolbox\ops
c:\matlab\toolbox\strfun
See Also
path, pathtool, genpath, rehash, rmpath
2-51
addproperty (COM)
Purpose
2addproperty (COM)
Add custom property to COM object
Syntax
addproperty(h, 'propertyname')
Arguments
h
Handle for a COM object previously returned from actxcontrol, actxserver,
get, or invoke.
propertyname
A string specifying the name of the custom property to add to the object or
interface.
Description
Add a custom property, propertyname, to the object or interface, h. You can
assign a value to that property using set.
Examples
Create an mwsamp control and add a new property named Position to it. Assign
an array value to the property:
f = figure('pos', [100 200 200 200]);
h = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200], f);
get(h)
Label: 'Label'
Radius: 20
addproperty(h, 'Position');
set(h, 'Position', [200 120]);
get(h)
Label: 'Label'
Radius: 20
Position: [200 120]
get(h, 'Position')
ans =
200
120
See Also
2-52
deleteproperty, get, set, inspect
airy
Purpose
2airy
Airy functions
Syntax
W = airy(Z)
W = airy(k,Z)
[W,ierr] = airy(k,Z)
Definition
The Airy functions form a pair of linearly independent solutions to
2
d W
d Z2
– ZW = 0
The relationship between the Airy and modified Bessel functions is
1
Ai ( Z ) = --- Z ⁄ 3
π
Bi ( Z ) =
K 1 ⁄ 3(ζ)
Z ⁄ 3 [ I –1 ⁄ 3 ( ζ ) + I 1 ⁄ 3 ( ζ ) ]
where
2 3⁄2
ζ = --- Z
3
Description
W = airy(Z) returns the Airy function, Ai ( Z ) , for each element of the complex
array Z.
W = airy(k,Z) returns different results depending on the value of k.
k
Returns
0
The same result as airy(Z)
1
The derivative, Ai′ ( Z )
2
The Airy function of the second kind, Bi ( Z )
3
The derivative, Bi′ ( Z )
2-53
airy
[W,ierr] = airy(k,Z) also returns completion flags in an array the same size
as W.
ierr
Description
0
airy succesfully computed the Airy function for this element.
1
Illegal arguments
2
Overflow. Returns Inf
3
Some loss of accuracy in argument reduction
4
Unacceptable loss of accuracy, Z too large
5
No convergence. Returns NaN
See Also
besseli, besselj, besselk, bessely
References
[1] Amos, D. E., “A Subroutine Package for Bessel Functions of a Complex
Argument and Nonnegative Order,” Sandia National Laboratory Report,
SAND85-1018, May, 1985.
[2] Amos, D. E., “A Portable Package for Bessel Functions of a Complex
Argument and Nonnegative Order,” Trans. Math. Software, 1986.
2-54
alim
Purpose
2alim
Set or query the axes alpha limits
Syntax
alpha_limits = alim
alim([amin amax])
alim_mode = alim('mode')
alim('alim_mode')
alim(axes_handle,...)
Description
alpha_limits = alim returns the alpha limits (the axes ALim property) of the
current axes.
alim([amin amax]) sets the alpha limits to the specified values. amin is the
value of the data mapped to the first alpha value in the alphamap, and amax is
the value of the data mapped to the last alpha value in the alphamap. Data
values in between are linearly interpolated across the alphamap, while data
values outside are clamped to either the first or last alphamap value,
whichever is closest.
alim_mode = alim('mode') returns the alpha limits mode (the axes ALimMode
property) of the current axes.
alim('alim_mode') sets the alpha limits mode on the current axes. alim_mode
can be:
• auto – MATLAB automatically sets the alpha limits based on the alpha data
of the objects in the axes.
• manual – MATLAB does not change the alpha limits.
alim(axes_handle,...) operates on the specified axes.
See Also
alpha, alphamap, caxis
Axes ALim and ALimMode properties
Patch FaceVertexAlphaData property
Image and surface AlphaData properties
Transparency for related functions
Transparency in 3-D Visualization for examples
2-55
all
Purpose
2all
Test to determine if all elements are nonzero
Syntax
B = all(A)
B = all(A,dim)
Description
B = all(A) tests whether all the elements along various dimensions of an
array are nonzero or logical true (1).
If A is a vector, all(A) returns logical true (1) if all of the elements are nonzero,
and returns logical false (0) if one or more elements are zero.
If A is a matrix, all(A) treats the columns of A as vectors, returning a row
vector of 1s and 0s.
If A is a multidimensional array, all(A) treats the values along the first
non-singleton dimension as vectors, returning a logical condition for each
vector.
B = all(A,dim) tests along the dimension of A specified by scalar dim.
Examples
1 1 1
1 1 0
1 1 0
1
0
A
all(A,1)
all(A,2)
Given,
A = [0.53 0.67 0.01 0.38 0.07 0.42 0.69]
then B = (A < 0.5) returns logical true (1) only where A is less than one half:
0
0
1
1
1
1
0
The all function reduces such a vector of logical conditions to a single
condition. In this case, all(B) yields 0.
This makes all particularly useful in if statements,
if all(A < 0.5)
do something
end
2-56
all
where code is executed depending on a single condition, not a vector of possibly
conflicting conditions.
Applying the all function twice to a matrix, as in all(all(A)), always reduces
it to a scalar condition.
all(all(eye(3)))
ans =
0
See Also
any, logical operators, relational operators, colon
Other functions that collapse an array’s dimensions include:
max, mean, median, min, prod, std, sum, trapz
2-57
allchild
Purpose
2allchild
Find all children of specified objects
Syntax
child_handles = allchild(handle_list)
Description
child_handles = allchild(handle_list) returns the list of all children
(including ones with hidden handles) for each handle. If handle_list is a
single element, allchild returns the output in a vector. Otherwise, the output is
a cell array.
Examples
Compare the results returned by these two statements.
get(gca,'Children')
allchild(gca)
See Also
2-58
findall, findobj
alpha
Purpose
2alpha
Set transparency properties for objects in current axes
Syntax
alpha(face_alpha)
alpha(alpha_data)
alpha(alpha_data_mapping)
alpha(object_handle,...)
Description
alpha sets one of three transparency properties, depending on what arguments
you specify with the call to this function.
FaceAlpha
alpha(face_alpha) set the FaceAlpha property of all image, patch, and
surface objects in the current axes. You can set face_alpha to:
• a scalar – set the FaceAlpha property to the specified value (for images, set
the AlphaData property to the specified value)
• 'flat' – set the FaceAlpha property to flat
• 'interp' – set the FaceAlpha property to interp
• 'texture' – set the FaceAlpha property to texture
• 'opaque' – set the FaceAlpha property to 1
• 'clear' – set the FaceAlpha property to 0
See Specifying a Single Transparency Value for more information.
AlphaData (Surface Objects)
alpha(alpha_data) sets the AlphaData property of all surface objects in the
current axes. You can set alpha_data to:
• a matrix the same size as CData – sets the AlphaData property to the
specified values
• 'x' – set the AlphaData property to be the same as XData
• 'y' – set the AlphaData property to be the same as YData
• 'z' – set the AlphaData property to be the same as ZData
• 'color' – set the AlphaData property to be the same as CData
2-59
alpha
• 'rand' – set the AlphaData property to a matrix of random values equal in
size to CData
AlphaData (Image Objects)
alpha(alpha_data) sets the AlphaData property of all image objects in the
current axes. You can set alpha_data to:
• a matrix the same size as CData – sets the AlphaData property to the
specified value
• 'x' – ignored
• 'y' – ignored
• 'z' – ignored
• 'color' – set the AlphaData property to be the same as CData
• 'rand' – set the AlphaData property to a matrix of random values equal in
size to CData
FaceVertexAlphaData (Patch Objects)
alpha(alpha_data) sets the FaceVertexAlphaData property of all patch
objects in the current axes. You can set alpha_data to:
• a matrix the same size as FaceVertexCData – sets the FaceVertexAlphaData
property to the specified value
• 'x' – set the FaceVertexAlphaData property to be the same as
Vertices(:,1)
• 'y' – set the FaceVertexAlphaData property to be the same as
Vertices(:,2)
• 'z' – set the FaceVertexAlphaData property to be the same as
Vertices(:,3)
• 'color' – set the FaceVertexAlphaData property to be the same as
FaceVertexCData
• 'rand' – set the FaceVertexAlphaData property to random values
See Mapping Data to Transparency for more information.
2-60
alpha
AlphaDataMapping
alpha(alpha_data_mapping) sets the AlphaDataMapping property of all
image, patch, and surface objects in the current axes. You can set
alpha_data_mapping to:
• 'scaled' – set the AlphaDataMapping property to scaled
• 'direct' – set the AlphaDataMapping property to direct
• 'none' – set the AlphaDataMapping property to none
alpha(object_handle,value) set the transparency property only on the
object identified by object_handle
See Also
alim, alphamap
Image: AlphaData, AlphaDataMapping
Patch: FaceAlpha, FaceVertexAlphaData, AlphaDataMapping
Surface: FaceAlpha, AlphaData, AlphaDataMapping
Transparency for related functions
Transparency in 3-D Visualization for examples
2-61
alphamap
Purpose
2alphamap
Specify the figure alphamap (transparency)
Syntax
alphamap(alpha_map)
alphamap('parameter')
alphamap('parameter',length)
alphamap('parameter’,delta)
alphamap(figure_handle,...)
alpha_map = alphamap
alpha_map = alphamap(figure_handle)
alpha_map = alphamap(’parameter’)
Description
alphamap enables you to set or modify a figure’s Alphamap property. Unless you
specify a figure handle as the first argument, alphamap operates on the current
figure.
alphamap(alpha_map) set the AlphaMap of the current figure to the specified
m-by-1 array of alpha values.
alphamap('parameter') create a new or modify the current alphamap. You
can specify the following parameters:
• default – set the AlphaMap property to the figure’s default alphamap
• rampup – create a linear alphamap with increasing opacity (default length
equals the current alphamap length)
• rampdown – create a linear alphamap with decreasing opacity (default length
equals the current alphamap length)
• vup – create an alphamap that is opaque in the center and becomes more
transparent linearly towards the beginning and end (default length equals
the current alphamap length)
• vdown – create an alphamap that is transparent in the center and becomes
more opaque linearly towards the beginning and end (default length equals
the current alphamap length)
• increase – modify the alphamap making it more opaque (default delta is .1,
which is added to the current values)
• decrease – modify the alphamap making it more transparent (default delta
is .1, which is subtracted from the current values)
2-62
alphamap
• spin – rotate the current alphamap (default delta is 1; note that delta must
be an integer)
alphamap('parameter',length) creates a new alphamap with the length
specified by length (used with parameters: rampup, rampdown, vup, vdown)
alphamap('parameter',delta) modifies the existing alphamap using the
value specified by delta (used with parameters: increase, decrease, spin).
alphamap(figure_handle,...) performs the operation on the alphamap of the
figure identified by figure_handle.
alpha_map = alphamap return the current alphamap.
alpha_map = alphamap(figure_handle) returns the current alphamap from
the figure identified by figure_handle.
alpha_map = alphamap(’parameter’) retruns the alphamap modified by the
parameter, but does not set the AlphaMap property.
See Also
alim, alpha
Image: AlphaData, AlphaDataMapping
Patch: FaceAlpha, AlphaData, AlphaDataMapping
Surface: FaceAlpha, AlphaData, AlphaDataMapping
Transparency for related functions
Transparency in 3-D Visualization for examples
2-63
angle
Purpose
2angle
Phase angle
Syntax
P = angle(Z)
Description
P = angle(Z) returns the phase angles, in radians, for each element of
complex array Z. The angles lie between ± π .
For complex Z, the magnitude R and phase angle theta are given by
R = abs(Z)
theta = angle(Z)
and the statement
Z = R.*exp(i*theta)
converts back to the original complex Z.
Examples
Z = [ 1
1
1
1
+
+
1i
2i
3i
4i
2
2
2
2
+
+
-
1i
2i
3i
4i
3
3
3
3
+
+
1i
2i
3i
4i
4
4
4
4
+
+
-
1i
2i
3i
4i ]
P = angle(Z)
P =
-0.7854
1.1071
-1.2490
1.3258
0.4636
-0.7854
0.9828
-1.1071
-0.3218
0.5880
-0.7854
0.9273
0.2450
-0.4636
0.6435
-0.7854
Algorithm
The angle function can be expressed as angle(z) = imag(log(z)) =
atan2(imag(z),real(z)).
See Also
abs, atan2, unwrap
2-64
ans
Purpose
2ans
The most recent answer
Syntax
ans
Description
MATLAB creates the ans variable automatically when you specify no output
argument.
Examples
The statement
2+2
is the same as
ans = 2+2
See Also
display
2-65
any
Purpose
2any
Test for any nonzeros
Syntax
B = any(A)
B = any(A,dim)
Description
B = any(A) tests whether any of the elements along various dimensions of an
array are nonzero or logical true (1).
If A is a vector, any(A) returns logical true (1) if any of the elements of A are
nonzero, and returns logical false (0) if all the elements are zero.
If A is a matrix, any(A) treats the columns of A as vectors, returning a row
vector of 1s and 0s.
If A is a multidimensional array, any(A) treats the values along the first
non-singleton dimension as vectors, returning a logical condition for each
vector.
B = any(A,dim) tests along the dimension of A specified by scalar dim.
Examples
1 0 1
0 0 0
1 0 1
1
0
A
any(A,1)
any(A,2)
Given,
A = [0.53 0.67 0.01 0.38 0.07 0.42 0.69]
then B = (A < 0.5) returns logical true (1) only where A is less than one half:
0
0
1
1
1
1
0
The any function reduces such a vector of logical conditions to a single
condition. In this case, any(B) yields 1.
This makes any particularly useful in if statements,
if any(A < 0.5)
do something
end
2-66
any
where code is executed depending on a single condition, not a vector of possibly
conflicting conditions.
Applying the any function twice to a matrix, as in any(any(A)), always reduces
it to a scalar condition.
any(any(eye(3)))
ans =
1
See Also
all, logical operators, relational operators, colon
Other functions that collapse an array’s dimensions include:
max, mean, median, min, prod, std, sum, trapz
2-67
area
Purpose
2area
Area fill of a two-dimensional plot
Syntax
area(Y)
area(X,Y)
area(...,ymin)
area(...,'PropertyName',PropertyValue,...)
h = area(...)
Description
An area plot displays elements in Y as one or more curves and fills the area
beneath each curve. When Y is a matrix, the curves are stacked showing the
relative contribution of each row element to the total height of the curve at each
x interval.
area(Y) plots the vector Y or the sum of each column in matrix Y. The x-axis
automatically scales depending on length(Y) when Y is a vector and on
size(Y,1)when Y is a matrix.
area(X,Y) plots Y at the corresponding values of X. If X is a vector, length(X)
must equal length(Y) and X must be monotonic. If X is a matrix, size(X) must
equal size(Y) and each column in X must be monotonic. To make a vector or
matrix monotonic, use sort.
area(...,ymin) specifies the lower limit in the y direction for the area fill. The
default ymin is 0.
area(...,'PropertyName',PropertyValue,...) specifies property name and
property value pairs for the patch graphics object created by area.
h = area(...) returns handles of patch graphics objects. area creates one
patch object per column in Y.
Remarks
area creates one curve from all elements in a vector or one curve per column in
a matrix. The colors of the curves are selected from equally spaced intervals
throughout the entire range of the colormap.
Examples
Plot the values in Y as a stacked area plot.
Y = [
2-68
1, 5, 3;
3, 2, 7;
area
1, 5, 3;
2, 6, 1];
area(Y)
grid on
colormap summer
set(gca,'Layer','top')
title 'Stacked Area Plot'
Stacked Area Plot
12
10
8
6
4
2
0
1
See Also
1.5
2
2.5
3
3.5
4
plot
“Area, Bar, and Pie Plots” for related functions
Area Graphs for more examples
2-69
asec
Purpose
2asec
Inverse secant
Syntax
Y = asec(X)
Description
Y = asec(X) returns the inverse secant (arcsecant) for each element of X.
The asec function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse secant over the domains 1 ≤ x ≤ 5 and – 5 ≤ x ≤ – 1 .
x1 = -5:0.01:-1;
x2 = 1:0.01:5;
plot(x1,asec(x1),x2,asec(x2)), grid on
3.5
3
2.5
2
1.5
1
0.5
0
−5
Definition
0
5
The inverse secant can be defined as
1
sec– 1 ( z ) = cos– 1  --- 
 z
Algorithm
asec uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-70
asec
See Also
asech, sec
2-71
asech
Purpose
2asech
Inverse hyperbolic secant
Syntax
Y = asech(X)
Description
Y = asech(X) returns the inverse hyperbolic secant for each element of X.
The asech function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse hyperbolic secant over the domain 0.01 ≤ x ≤ 1 .
x = 0.01:0.001:1;
plot(x,asech(x)), grid on
6
5
4
3
2
1
0
0
Definition
0.2
0.4
0.6
0.8
1
The hyperbolic inverse secant can be defined as
1
sech– 1 ( z ) = cosh– 1  --- 
 z
Algorithm
asech uses FDLIBM, which was developed at SunSoft, a Sun Microsystems,
Inc. business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-72
asech
See Also
asec, sech
2-73
asin
Purpose
2asin
Inverse sine
Syntax
Y = asin(X)
Description
Y = asin(X) returns the inverse sine (arcsine) for each element of X. For real
elements of X in the domain [ – 1, 1 ] , asin(X) is in the range [ – π ⁄ 2, π ⁄ 2 ] . For
real elements of x outside the range [ – 1, 1 ] , asin(X) is complex.
The asin function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse sine function over the domain – 1 ≤ x ≤ 1 .
x = -1:.01:1;
plot(x,asin(x)), grid on
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
−1
Definition
0
0.5
The inverse sine can be defined as
–1
sin ( z)
2-74
−0.5
1
--2 2
= – i log iz + ( 1 – z )
1
asin
Algorithm
asin uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
See Also
sin, asinh
2-75
asinh
Purpose
2asinh
Inverse hyperbolic sine
Syntax
Y = asinh(X)
Description
Y = asinh(X) returns the inverse hyperbolic sine for each element of X.
The asinh function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse hyperbolic sine function over the domain – 5 ≤ x ≤ 5 .
x = -5:.01:5;
plot(x,asinh(x)), grid on
2.5
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
−2.5
−5
Definition
0
The hyperbolic inverse sine can be defined as
–1
2
sinh ( z ) = log z + ( z + 1 )
2-76
5
1
--2
asinh
Algorithm
asinh uses FDLIBM, which was developed at SunSoft, a Sun Microsystems,
Inc. business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
See Also
asin, sinh
2-77
assignin
Purpose
2assignin
Assign a value to a workspace variable
Syntax
assignin(ws,'var',val)
Description
assignin(ws,'var',val) assigns the value val to the variable var in the
workspace ws. var is created if it doesn’t exist. ws can have a value of 'base' or
'caller' to denote the MATLAB base workspace or the workspace of the caller
function.
The assignin function is particularly useful for these tasks:
• Exporting data from a function to the MATLAB workspace
• Within a function, changing the value of a variable that is defined in the
workspace of the caller function (such as a variable in the function argument
list)
Remarks
The MATLAB base workspace is the workspace that is seen from the MATLAB
command line (when not in the debugger). The caller workspace is the
workspace of the function that called the M-file. Note the base and caller
workspaces are equivalent in the context of an M-file that is invoked from the
MATLAB command line.
Examples
This example creates a dialog box for the image display function, prompting a
user for an image name and a colormap name. The assignin function is used
to export the user–entered values to the MATLAB workspace variables imfile
and cmap.
prompt = {'Enter image name:','Enter colormap name:'};
title = 'Image display - assignin example';
lines = 1;
def = {'my_image','hsv'};
answer = inputdlg(prompt,title,lines,def);
assignin('base','imfile',answer{1});
assignin('base','cmap',answer{2});
2-78
assignin
See Also
evalin
2-79
atan
Purpose
2atan
Inverse tangent
Syntax
Y = atan(X)
Description
Y = atan(X) returns the inverse tangent (arctangent) for each element of X.
For real elements of X, atan(X) is in the range [ – π ⁄ 2, π ⁄ 2 ] .
The atan function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Examples
Graph the inverse tangent function over the domain – 20 ≤ x ≤ 20 .
x = -20:0.01:20;
plot(x,atan(x)), grid on
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
−20
Definition
−15
−10
−5
0
5
10
15
20
The inverse tangent can be defined as
i
i+z
tan– 1 ( z ) = ---- log  ----------- 
i– z
2
Algorithm
atan uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-80
atan
See Also
atan2, tan, atanh
2-81
atan2
Purpose
2atan2
Four-quadrant inverse tangent
Syntax
P = atan2(Y,X)
Description
P = atan2(Y,X) returns an array P the same size as X and Y containing the
element-by-element, four-quadrant inverse tangent (arctangent) of the real
parts of Y and X. Any imaginary parts are ignored.
Elements of P lie in the closed interval [-pi,pi], where pi is the MATLAB
floating-point representation of π . atan uses sign(Y) and sign(X) to
determine the specific quadrant.
y
π/2
π
–π
0
x
–π/2
atan2(Y,X) contrasts with atan(Y/X), whose results are limited to the interval
[ – π ⁄ 2, π ⁄ 2 ] , or the right side of this diagram.
Examples
Any complex number z = x + iy is converted to polar coordinates with
r = abs(z)
theta = atan2(imag(z),real(z))
For example,
z = 4 + 3i;
r = abs(z)
theta = atan2(imag(z),real(z))
r =
5
2-82
atan2
theta =
0.6435
This is a common operation, so MATLAB provides a function, angle(z), that
computes theta = atan2(imag(z),real(z)).
To convert back to the original complex number
z = r *exp(i *theta)
z =
4.0000 + 3.0000i
Algorithm
atan2 uses FDLIBM, which was developed at SunSoft, a Sun Microsystems,
Inc. business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
See Also
angle, atan, atanh
2-83
atanh
Purpose
2atanh
Inverse hyperbolic tangent
Syntax
Y = atanh(X)
Description
The atanh function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Y = atanh(X) returns the inverse hyperbolic tangent for each element of X.
Examples
Graph the inverse hyperbolic tangent function over the domain – 1 < x < 1 .
x = -0.99:0.01:0.99;
plot(x,atanh(x)), grid on
3
2
1
0
−1
−2
−3
−1
Definition
−0.5
0
0.5
1
The hyperbolic inverse tangent can be defined as
1+z
1
tanh– 1 ( z ) = --- log  ------------ 
1– z
2
Algorithm
atanh uses FDLIBM, which was developed at SunSoft, a Sun Microsystems,
Inc. business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-84
atanh
See Also
atan2, atan, tanh
2-85
audiodevinfo
Purpose
2audiodevinfo
Obtain information on installed audio devices
Syntax
d = audiodevinfo
audiodevinfo(io)
audiodevinfo(io,ID)
audiodevinfo(io,ID,'DriverVersion')
audiodevinfo(io,name)
audiodevinfo(io,rate,bits,chans)
audiodevinfo(io,ID,rate,bits,chans)
Description
Note This function is for use only with 32-bit, Windows-based machines.
d = audiodevinfo returns a structure, d with an input field and an output
field. Each field is an array of structures that contains information about the
system’s audio input and output devices. Each array contains these fields: a
string with the name of the device, a string with the version of the installed
driver (DriverVersion), and the device’s numeric ID.
audiodevinfo(io) returns the number of input (io=1) or output (io=0) audio
devices on the system.
audiodevinfo(io,ID) returns the name of the audio device specified by its ID.
audiodevinfo(io,ID,'DriverVersion') returns a string containing the
driver version of the specified audio device.
audiodevinfo(io,name) returns the device ID specified by name. You can enter
a partial name, but the case must match. If no device with the specified name is
found, -1 is returned.
audiodevinfo(io,rate,bits,chans) returns the device ID of the first audio
device that supports the specified sample rate, number of bits, and number of
channels, chans. If no matching device is found, -1 is returned.
audiodevinfo(io,ID,rate,bits,chans) returns 1 if the device, specified by
its ID, supports the specified sample rate, number of bits, and number of
channels, chans. If the device does not support the specified parameters, 0 is
returned.
2-86
audiodevinfo
See Also
audioplayer, audiorecorder
2-87
audioplayer
Purpose
2audioplayer
Create an audio player object
Syntax
y
y
y
y
Description
Note audioplayer is available only on Windows-based machines. On 32-bit,
Windows-based machines with an installed 24-bit audio device, audioplayer
supports 24-bit playback.
=
=
=
=
audioplayer(x,Fs)
audioplayer(x,Fs,nbits)
audioplayer(r)
audioplayer(r,id)
To use all of the audioplayer features, your system needs a properly installed
and configured sound card with 8- and 16-bit I/O, two channels, and support
for sampling rates of up to 48 kHz.
y = audioplayer(x,Fs) returns a handle to an audio player object y using
input audio signal x. The input signal x can be a vector or two-dimensional
array containing single, double, int8, uint8, or int16 MATLAB data types.
The input sample values for single and double data must be between -1 and
1. For int8, uint8, and int16 data, the ranges of sample values are -128 to 127,
0 to 255, and -32768 to 32767, respectively.
Fs is the sampling rate in Hz to use for playback. Valid values for Fs depend on
the specific audio hardware installed. Typical values supported by most sound
cards are 8000, 11025, 22050, and 44100 Hz.
y = audioplayer(x,Fs,nbits) returns a handle to an audio player object
where nbits is the bit quantization to use for single or double data types. This
is an optional parameter with a default value of 16. Valid values for nbits are
8 and 16 (and 24, if a 24-bit device is installed). You do not need to specify nbits
for int8, uint8 or int16 data because the quantization is set automatically to
8 or 16, respectively.
y = audioplayer(r) returns a handle to an audio player object from an
audiorecorder object r.
y = audioplayer(r,id) returns a handle to an audio player object from an
audiorecorder object r, using the specified audio device id for output.
2-88
audioplayer
After you create an audio player object, you can use the methods listed below
on that object. y represents the name of the returned audio player.
Method
Description
play(y)
play(y,start)
play(y,[start stop])
play(y,range)
Starts playback from the beginning
and plays to the end, or from start
sample to the end, or from start
sample to stop sample. The values of
start and stop can be specified in a
two-element vector range.
playblocking(y)
playblocking(y,start)
playblocking(y,[start stop])
playblocking(y,range)
Same as play, but does not return
control until playback completes.
stop(y)
Stops playback.
pause(y)
Pauses playback.
resume(y)
Restarts playback from where
playback was paused.
isplaying(y)
Indicates whether playback is in
progress. If 0, playback is not in
progress. If 1, playback is in progress.
display(y)
disp(y)
get(y)
Displays all property information
about audio player y.
Audio player objects have the properties listed below. To set a user-settable
property use this syntax:
set(y, 'property1', value,'property2',value,...)
To view a read-only property
get(y,’property’)
% Displays ‘property’ setting.
2-89
audioplayer
Property
Description
Type
Type
Name of the object’s class
read-only
SampleRate
Sampling frequency in Hz
user-settable
BitsPerSample
Number of bits per sample
read-only
NumberOfChannels
Number of channels
read-only
TotalSamples
Total length, in samples, of the
audio data
read-only
Running
Status of the audio player ('on' or
'off')
read-only
CurrentSample
Current sample being played by
the audio output device (If it is
not playing, currentsample is
the next sample to be played with
play or resume.)
read-only
UserData
User data of any type
user-settable
Tag
User-specified object label string
user-settable
For information on using the following four properties, see Creating Timer
Callback Functions in the MATLAB documentation. Note that for audio
object callbacks, eventStruct (event) is currently empty ([]).
2-90
TimerFcn
Name of, or handle to,
user-specified function to be
called during playback
user-settable
TimerPeriod
Time, in seconds, between
TimerFcn callbacks
user-settable
audioplayer
Example
Property
Description
Type
StartFcn
Name of, or handle to, the
function to be called once when
playback starts
user-settable
StopFcn
Name of or handle to the function
to be called once when playback
stops
user-settable
Load a sample audio file, create an audio player object, and play the audio at a
higher sampling rate. x contains the audio samples and Fs is the sampling rate.
You can use any of the audioplayer functions listed above on the player.
load handel;
player=audioplayer(y,Fs);
play(player,[1 (get(player,'SampleRate')*3)]);
To stop the playback, use this command:
stop(player);
See Also
% Equivalent to player.stop
audiorecorder, sound, wavplay, wavwrite, wavread, get, set, methods
2-91
audiorecorder
Purpose
2audiorecorder
Create an audio recorder object
Syntax
y = audiorecorder
y = audiorecorder(Fs,nbits,channels)
y = audiorecorder(Fs,nbits,channels,id)
Description
Note To use all of the audio recorder object features, your system must have
a properly installed and configured sound card with 8- and 16-bit I/O and
support for sampling rates of up to 48 kHz.
On 32-bit, Windows-based machines with an installed 24-bit audio device,
audiorecorder supports 24-bit recording.
y = audiorecorder returns a handle to an 8-kHz, 8-bit, mono audio recorder
object.
y = audiorecorder(Fs,nbits,channels) returns a handle to an audio
recorder object using the sampling rate, Fs ( in Hz), the sample size of nbits,
and the number of channels. Fs can be any sampling rate supported by the
audio hardware. Common sampling rates are 8000, 11025, 22050, and 44000.
The value of nbits must be 8 or 16 (or 24, if a 24-bit device is installed). For
mono or stereo, channels must be 1 or 2, respectively.
y = audiorecorder(Fs,nbits,channels,id) returns a handle to an audio
recorder object using the audio device specified by its id for input.
After you create an audio recorder object, you can use the methods listed below
on that object. y represents the name of the returned audio recorder.
2-92
Method
Description
record(y)
record(y,length)
Starts recording.
Records for length number of seconds.
recordblocking(y,length)
Same as record, but does not return
control until recording completes.
stop(y)
Stops recording.
audiorecorder
Method
Description
pause(y)
Pauses recording.
resume(y)
Restarts recording from where
recording was paused.
isrecording(y)
Indicates the status of recording. If 0,
recording is not in progress. If 1,
recording is in progress.
play(y)
Creates an audioplayer, plays the
recorded audio data, and returns a
handle to the created audioplayer.
getplayer(y)
Creates an audioplayer and returns a
handle to the created audioplayer.
getaudiodata(y)
getaudiodata(y,'type')
Returns the recorded audio data to the
MATLAB workspace. type is a string
containing the desired data type.
Supported data types are double,
single, int16, int8, or uint8. If type
is omitted, it defaults to 'double'.
For double and single, the array
contains values between -1 and 1. For
int8, values are between -128 to 127.
For uint8, values are from 0 to 255.
For int16, values are from -32768 to
32767. If the recording is in mono, the
returned array has one column. If it is
in stereo, the array has two columns—
one for each channel.
display(y)
disp(y)
get(y)
Displays all property information
about audio recorder y.
2-93
audiorecorder
Audio recorder objects have the properties listed below. To set a user-settable
property use this syntax:
set(y, 'property1', value,'property2',value,...)
To view a read-only property
get(y,’property’)
2-94
%displays ‘property’ setting.
Property
Description
Type
Type
Name of the object’s class
read-only
SampleRate
Sampling frequency in Hz
read-only
BitsPerSample
Number of bits per recorded
sample
read-only
NumberOfChannels
Number of channels of recorded
audio
read-only
TotalSamples
Total length, in samples, of the
recording
read-only
Running
Status of the audio recorder ('on'
or 'off')
read-only
CurrentSample
Current sample being recorded
by the audio output device (If it is
not recording, currentsample is
the next sample to be recorded
with record or resume.)
read-only
UserData
User data of any type
user-settable
audiorecorder
Property
Description
Type
For information on using the following four properties, see Creating Timer
Callback Functions in the MATLAB documentation. Note that for audio
object callbacks, eventStruct (event) is currently empty ([]).
Examples
TimerFcn
Name of or handle to
user-specified function to be
called during recording
user-settable
TimerPeriod
Time, in seconds, between
TimerFcn callbacks
user-settable
StartFcn
Name of or handle to the function
to be called a single time when
recording starts
user-settable
StopFcn
Name of or handle to the function
to be called a single time when
recording stops
user-settable
NumberOfBuffers
Number of buffers used for
recording (You should adjust this
only if you have skips, dropouts,
etc. in your recording.)
user-settable
BufferLength
Length in seconds of buffer (You
should adjust this only if you
have skips, dropouts, etc. in your
recording.)
user-settable
Tag
User-specified object label string
user-settable
Example 1
Using a microphone, record 3.5 seconds of 44.1-kHz, 16-bit, stereo data, and
then return the data to the MATLAB workspace as a double array.
recorder = audiorecorder(44100,16,2);
recordblocking(recorder,3.5);
audioarray = getaudiodata(recorder);
2-95
audiorecorder
Example 2
Using a microphone, record 8-bit, 22-kHz mono data, play it back, record again
and return the data to the MATLAB workspace as a uint8 array.
micrecorder = audiorecorder(22050,8,1);
record(micrecorder);
% Now, speak into microphone
stop(micrecorder);
speechplayer = play(micrecorder);
% Now, listen to the recording
stop(speechplayer);
speechdata = getaudiodata(micrecorder, 'uint8');
Remarks
The current implementation of AudioRecorder is not intended for long, high
sample rate recording because it uses system memory for storage and does not
use disk buffering. When large recordings are attempted, MATLAB
performance may degrade.
See Also
audioplayer, wavread, wavrecord, wavwrite, get, set, methods
2-96
auread
Purpose
2auread
Graphical
Interface
As an alternative to auread, use the Import Wizard. To activate the Import
Wizard, select Import data from the File menu.
Syntax
y = auread('aufile')
[y,Fs,bits] = auread('aufile')
[...] = auread('aufile',N)
[...] = auread('aufile',[N1,N2])
siz = auread('aufile','size')
Description
y = auread('aufile') loads a sound file specified by the string aufile,
returning the sampled data in y. The .au extension is appended if no extension
is given. Amplitude values are in the range [–1,+1]. auread supports
Read NeXT/SUN (.au) sound file
multi-channel data in the following formats:
• 8-bit mu-law
• 8-, 16-, and 32-bit linear
• floating-point
[y,Fs,bits] = auread('aufile') returns the sample rate (Fs) in Hertz and
the number of bits per sample (bits) used to encode the data in the file.
[...] = auread('aufile',N) returns only the first N samples from each
channel in the file.
[...] = auread('aufile',[N1 N2]) returns only samples N1 through N2
from each channel in the file.
siz = auread('aufile','size') returns the size of the audio data contained
in the file in place of the actual audio data, returning the vector siz =
[samples channels].
See Also
auwrite, wavread
2-97
auwrite
Purpose
2auwrite
Write NeXT/SUN (.au) sound file
Syntax
auwrite(y,'aufile')
auwrite(y,Fs,'aufile')
auwrite(y,Fs,N,'aufile')
auwrite(y,Fs,N,'method','aufile')
Description
auwrite(y,'aufile') writes a sound file specified by the string aufile. The
data should be arranged with one channel per column. Amplitude values
outside the range [–1,+1] are clipped prior to writing. auwrite supports
multi-channel data for 8-bit mu-law, and 8- and 16-bit linear formats.
auwrite(y,Fs,'aufile') specifies the sample rate of the data in Hertz.
auwrite(y,Fs,N,'aufile') selects the number of bits in the encoder.
Allowable settings are N = 8 and N = 16.
auwrite(y,Fs,N,'method','aufile') allows selection of the encoding
method, which can be either mu or linear. Note that mu-law files must be 8-bit.
By default, method = 'mu'.
See Also
2-98
auread, wavwrite
avifile
Purpose
2avifile
Create a new Audio Video Interleaved (AVI) file
Syntax
aviobj = avifile(filename)
aviobj =
avifile(filename,'PropertyName',value,'PropertyName',value,...)
Description
aviobj = avifile(filename) creates an AVI file, giving it the name specified
in filename, using default values for all AVI file object properties. If filename
does not include an extension, avifile appends .avi to the filename. AVI is a
file format for storing audio and video data.
avifile returns a handle to an AVI file object, aviobj. You use this object to
refer to the AVI file in other functions. An AVI file object supports properties
and methods that control aspects of the AVI file created.
creates
an AVI file with the specified parameter settings. This table lists available
parameters.
aviobj = avifile(filename,'Param',Value,'Param',Value,...)
Parameter
Value
Default
'colormap'
An m-by-3 matrix defining the colormap
to be used for indexed AVI movies,
where m must be no greater than 256
(236 if using Indeo compression). You
must set this parameter before calling
addframe, unless you are using
addframe with the MATLAB movie
syntax.
There is no
default
colormap.
'compression'
A text string specifying which
compression codec to use.
On Windows:
'Indeo3'
'Indeo5'
'Cinepak'
'MSVC'
'None'
On Unix:
'None'
'Indeo3',
on
Windows.
'None' on
Unix.
2-99
avifile
Parameter
Value
Default
To use a custom compression codec,
specify the four-character code that
identifies the codec (typically included
in the codec documentation). The
addframe function reports an error if it
can not find the specified custom
compressor.
'fps'
A scalar value specifying the speed of
the AVI movie in frames per second
(fps).
15 fps
'keyframe'
For compressors that support temporal
compression, this is the number of key
frames per second.
2 key
frames per
second.
'name'
A descriptive name for the video
stream. This parameter must be no
greater than 64 characters long.
The default
is the
filename.
'quality'
A number between 0 and 100. This
parameter has no effect on
uncompressed movies. Higher quality
numbers result in higher video quality
and larger file sizes. Lower quality
numbers result in lower video quality
and smaller file sizes.
75
You can also use structure syntax to set AVI file object properties. For
example, to set the quality property to 100 use the following syntax:
aviobj = avifile(filename);
aviobj.Quality = 100;
Example
This example shows how to use the avifile function to create the AVI file
example.avi.
fig=figure;
set(fig,'DoubleBuffer','on');
2-100
avifile
set(gca,'xlim',[-80 80],'ylim',[-80 80],...
'NextPlot','replace','Visible','off')
mov = avifile('example.avi')
x = -pi:.1:pi;
radius = 0:length(x);
for k=1:length(x)
h = patch(sin(x)*radius(k),cos(x)*radius(k),...
[abs(cos(x(k))) 0 0]);
set(h,'EraseMode','xor');
F = getframe(gca);
mov = addframe(mov,F);
end
mov = close(mov);
See Also
addframe, close, movie2avi
2-101
aviinfo
Purpose
2aviinfo
Return information about an Audio Video Interleaved (AVI) file
Syntax
fileinfo = aviinfo(filename)
Description
fileinfo = aviinfo(filename) returns a structure whose fields contain
information about the AVI file specified in the string, filename. If filename
does not include an extension, then .avi is used. The file must be in the current
working directory or in a directory on the MATLAB path.
The set of fields in the fileinfo structure are shown below.
2-102
Field Name
Description
AudioFormat
A string containing the name of the format used
to store the audio data, if audio data is present
AudioRate
An integer indicating the sample rate in Hertz of
the audio stream, if audio data is present
Filename
A string specifying the name of the file
FileModDate
A string containing the modification date of the
file
FileSize
An integer indicating the size of the file in bytes
FramesPerSecond
An integer indicating the desired frames per
second
Height
An integer indicating the height of the AVI movie
in pixels
ImageType
A string indicating the type of image. Either
'truecolor' for a truecolor (RGB) image, or
'indexed' for an indexed image.
NumAudioChannels
An integer indicating the number of channels in
the audio stream, if audio data is present
NumFrames
An integer indicating the total number of frames
in the movie
aviinfo
See also
Field Name
Description
NumColormapEntries
An integer specifying the number of colormap
entries
Quality
A number between 0 and 100 indicating the video
quality in the AVI file. Higher quality numbers
indicate higher video quality; lower quality
numbers indicate lower video quality. This value
is not always set in AVI files and therefore may be
inaccurate.
VideoCompression
A string containing the compressor used to
compress the AVI file. If the compressor is not
Microsoft Video 1, Run Length Encoding (RLE),
Cinepak, or Intel Indeo, aviinfo returns a
four-character code.
Width
An integer indicating the width of the AVI movie
in pixels
avifile, aviread
2-103
aviread
Purpose
2aviread
Read an Audio Video Interleaved (AVI) file.
Syntax
mov = aviread(filename)
mov = aviread(filename,index)
Description
mov = aviread(filename) reads the AVI movie filename into the MATLAB
movie structure mov. If filename does not include an extension, then .avi is
used. Use the movie function to view the movie, mov. On UNIX, filename must
be an uncompressed AVI file.
mov has two fields, cdata and colormap. The content of these fields varies
depending on the type of image.
Image Type
mov.cdata Field
mov.colormap Field
Truecolor
height-by-width-by-3
array
Empty
Indexed
height-by-width array
m-by-3 array
mov = aviread(filename,index) reads only the frame(s) specified by index.
index can be a single index or an array of indices into the video stream. In AVI
files, the first frame has the index value 1, the second frame has the index
value 2, and so on.
See also
2-104
aviinfo, avifile, movie
axes
Purpose
2axes
Create axes graphics object
Syntax
axes
axes('PropertyName',PropertyValue,...)
axes(h)
h = axes(...)
Description
axes is the low-level function for creating axes graphics objects.
axes creates an axes graphics object in the current figure using default
property values.
axes('PropertyName',PropertyValue,...) creates an axes object having the
specified property values. MATLAB uses default values for any properties that
you do not explicitly define as arguments.
axes(h) makes existing axes h the current axes. It also makes h the first axes
listed in the figure’s Children property and sets the figure’s CurrentAxes
property to h. The current axes is the target for functions that draw image, line,
patch, surface, and text graphics objects.
h = axes(...) returns the handle of the created axes object.
Remarks
MATLAB automatically creates an axes, if one does not already exist, when
you issue a command that draws image, light, line, patch, surface, or text
graphics objects.
The axes function accepts property name/property value pairs, structure
arrays, and cell arrays as input arguments (see the set and get commands for
examples of how to specify these data types). These properties, which control
various aspects of the axes object, are described in the “Axes Properties”
section.
Use the set function to modify the properties of an existing axes or the get
function to query the current values of axes properties. Use the gca command
to obtain the handle of the current axes.
The axis (not axes) function provides simplified access to commonly used
properties that control the scaling and appearance of axes.
2-105
axes
While the basic purpose of an axes object is to provide a coordinate system for
plotted data, axes properties provide considerable control over the way
MATLAB displays data.
Stretch-to-Fill
By default, MATLAB stretches the axes to fill the axes position rectangle (the
rectangle defined by the last two elements in the Position property). This
results in graphs that use the available space in the rectangle. However, some
3-D graphs (such as a sphere) appear distorted because of this stretching, and
are better viewed with a specific three-dimensional aspect ratio.
Stretch-to-fill is active when the DataAspectRatioMode,
PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto (the
default). However, stretch-to-fill is turned off when the DataAspectRatio,
PlotBoxAspectRatio, or CameraViewAngle is user-specified, or when one or
more of the corresponding modes is set to manual (which happens
automatically when you set the corresponding property value).
This picture shows the same sphere displayed both with and without the
stretch-to-fill. The dotted lines show the axes Position rectangle.
1
1
8
0.8
6
0.6
4
0.4
2
0.2
0
0
2
−0.2
4
−0.4
6
−0.6
8
−0.8
1
−1
−0.8
−0.6
−0.4
−0.2
0
0.2
0.4
Stretch-to-fill active
0.6
0.8
1
−1
−1
−0.5
0
0.5
1
Stretch-to-fill disabled
When stretch-to-fill is disabled, MATLAB sets the size of the axes to be as large
as possible within the constraints imposed by the Position rectangle without
introducing distortion. In the picture above, the height of the rectangle
constrains the axes size.
2-106
axes
Examples
Zooming
Zoom in using aspect ratio and limits:
sphere
set(gca,'DataAspectRatio',[1 1 1],...
'PlotBoxAspectRatio',[1 1 1],'ZLim',[−0.6 0.6])
Zoom in and out using the CameraViewAngle:
sphere
set(gca,'CameraViewAngle',get(gca,'CameraViewAngle')−5)
set(gca,'CameraViewAngle',get(gca,'CameraViewAngle')+5)
Note that both examples disable the MATLAB stretch-to-fill behavior.
Positioning the Axes
The axes Position property enables you to define the location of the axes
within the figure window. For example,
h = axes('Position',position_rectangle)
creates an axes object at the specified position within the current figure and
returns a handle to it. Specify the location and size of the axes with a rectangle
defined by a four-element vector,
position_rectangle = [left, bottom, width, height];
The left and bottom elements of this vector define the distance from the
lower-left corner of the figure to the lower-left corner of the rectangle. The
width and height elements define the dimensions of the rectangle. You specify
these values in units determined by the Units property. By default, MATLAB
uses normalized units where (0,0) is the lower-left corner and (1.0,1.0) is the
upper-right corner of the figure window.
You can define multiple axes in a single figure window:
axes('position',[.1 .1
mesh(peaks(20));
axes('position',[.1 .7
pcolor([1:10;1:10]);
.8
.6])
.8
.2])
2-107
axes
In this example, the first plot occupies the bottom two-thirds of the figure, and
the second occupies the top third.
2
1.5
1
1
2
3
4
5
6
7
8
9
10
10
5
0
−5
−10
20
15
20
15
10
10
5
0
See Also
5
0
axis, cla, clf, figure, gca, grid, subplot, title, xlabel, ylabel, zlabel,
view
“Axes Operations” for related functions
Axes Properties for more examples
2-108
axes
Object
Hierarchy
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Rectangle
Surface
Text
Setting Default Properties
You can set default axes properties on the figure and root levels:
set(0,'DefaultAxesPropertyName',PropertyValue,...)
set(gcf,'DefaultAxesPropertyName',PropertyValue,...)
where PropertyName is the name of the axes property and PropertyValue is
the value you are specifying. Use set and get to access axes properties.
Property List
Property Name
The following table lists all axes properties and provides a brief description of
each. The property name links take you an expanded description of the
properties.
Property Description
Property Value
Controlling Style and Appearance
Box
Toggle axes plot box on and off
Clipping
This property has no effect; axes are
always clipped to the figure window
GridLineStyle
Line style used to draw axes grid
lines
Values: on, off
Default: off
Values: −, −−, :, -., none
Default: : (dotted line)
2-109
axes
Property Name
Property Description
Property Value
MinorGridLineStyle
Line style used to draw axes minor
grid lines
Values: −, −−, :, -., none
Default: : (dotted line)
Layer
Draw axes above or below graphs
Values: bottom, top
Default: bottom
LineStyleOrder
Sequence of line styles used for
multiline plots
Values: LineSpec
Default: − (solid line for)
LineWidth
Width of axis lines, in points (1/72"
per point)
Values: number of points
Default: 0.5 points
SelectionHighlight
Highlight axes when selected
(Selected property set to on)
Values: on, off Default: on
TickDir
Direction of axis tick marks
Values: in, out
Default: in (2-D), out (3-D)
TickDirMode
Use MATLAB or user-specified tick
mark direction
Values: auto, manual
Default: auto
TickLength
Length of tick marks normalized to
axis line length, specified as
two-element vector
Values: [2-D 3-D]
Default: [0.01 0.025}
Visible
Make axes visible or invisible
Values: on, off
Default: on
XGrid, YGrid, ZGrid
Toggle grid lines on and off in
respective axis
Values: on, off
Default: off
General Information About the Axes
Children
Handles of the images, lights, lines,
patches, surfaces, and text objects
displayed in the axes
Values: vector of handles
CurrentPoint
Location of last mouse button click
defined in the axes data units
Values: a 2-by-3 matrix
2-110
axes
Property Name
Property Description
Property Value
HitTest
Specify whether axes can become
the current object (see figure
CurrentObject property)
Values: on, off
Default: on
Parent
Handle of the figure window
containing the axes
Values: scalar figure handle
Position
Location and size of axes within the
figure
Values: [left bottom width
height]
Default: [0.1300 0.1100
0.7750 0.8150] in
normalized Units
Selected
Indicate whether axes is in a
“selected” state
Values: on, off
Default: on
Tag
User-specified label
Values: any string
Default: '' (empty string)
Type
The type of graphics object (read
only)
Value: the string 'axes'
Units
Units used to interpret the
Position property
Values: inches,
centimeters, characters,
normalized, points, pixels
Default: normalized
UserData
User-specified data
Values: any matrix
Default: [] (empty matrix)
FontAngle
Select italic or normal font
Values: normal, italic,
oblique
Default: normal
FontName
Font family name (e.g., Helvetica,
Courier)
Values: a font supported by
your system or the string
Selecting Fonts and Labels
FixedWidth
Default: Typically Helvetica
2-111
axes
Property Name
Property Description
Property Value
FontSize
Size of the font used for title and
labels
Values: an integer in
FontUnits Default: 10
FontUnits
Units used to interpret the
FontSize property
Values: points,
normalized, inches,
centimeters, pixels
Default: points
FontWeight
Select bold or normal font
Values: normal, bold,
light, demi
Default: normal
Title
Handle of the title text object
Values: any valid text object
handle
XLabel, YLabel, ZLabel
Handles of the respective axis label
text objects
Values: any valid text object
handle
XTickLabel,
YTickLabel,
ZTickLabel
Specify tick mark labels for the
respective axis
Values: matrix of strings
Defaults: numeric values
selected automatically by
MATLAB
XTickLabelMode,
YTickLabelMode,
ZTickLabelMode
Use MATLAB or user-specified tick
mark labels
Values: auto, manual
Default: auto
XAxisLocation
Specify the location of the x-axis
Values: top, bottom
Default: bottom
YAxisLocation
Specify the location of the y-axis
Values: right left
Default: left
XDir, YDir, ZDir
Specify the direction of increasing
values for the respective axes
Values: normal, reverse
Default: normal
Controlling Axis Scaling
2-112
axes
Property Name
Property Description
Property Value
XLim, YLim, ZLim
Specify the limits to the respective
axes
Values: [min max]
Default: min and max
determined automatically
by MATLAB
XLimMode, YLimMode,
ZLimMode
Use MATLAB or user-specified
values for the respective axis limits
Values: auto, manual
Default: auto
XMinorGrid,YMinorGrid,
ZMinorGrid
Determines whether MATLAB
displays gridlines connecting minor
tick marks in the respective axis.
Values: on, off
Default: off
XMinorTick,YMinorTick,
ZMinorTick
Determines whether MATLAB
displays minor tick marks in the
respective axis.
Values: on, off
Default: off
XScale, YScale, ZScale
Select linear or logarithmic scaling
of the respective axis
Values: linear, log
Default: linear (changed
by plotting commands that
create nonlinear plots)
XTick, YTick, ZTick
Specify the location of the axis ticks
marks
Values: a vector of data
values locating tick marks
Default: MATLAB
automatically determines
tick mark placement
XTickMode, YTickMode,
ZTickMode
Use MATLAB or user-specified
values for the respective tick mark
locations
Values: auto, manual
Default: auto
Specify the position of point from
which you view the scene
Values: [x,y,z] axes
coordinates
Default: automatically
determined by MATLAB
Controlling the View
CameraPosition
2-113
axes
Property Name
Property Description
Property Value
CameraPositionMode
Use MATLAB or user-specified
camera position
Values: auto, manual
Default: auto
CameraTarget
Center of view pointed to by camera
Values: [x,y,z] axes
coordinates
Default: automatically
determined by MATLAB
CameraTargetMode
Use MATLAB or user-specified
camera target
Values: auto, manual
Default: auto
CameraUpVector
Direction that is oriented up
Values: [x,y,z] axes
coordinates
Default: automatically
determined by MATLAB
CameraUpVectorMode
Use MATLAB or user-specified
camera up vector
Values: auto, manual
Default: auto
CameraViewAngle
Camera field of view
Values: angle in degrees
between 0 and 180
Default: automatically
determined by MATLAB
CameraViewAngleMode
Use MATLAB or user-specified
camera view angle
Values: auto, manual
Default: auto
Projection
Select type of projection
Values: orthographic,
perspective
Default: orthographic
Controlling the Axes Aspect Ratio
DataAspectRatio
Relative scaling of data units
Values: three relative
values [dx dy dz]
Default: automatically
determined by MATLAB
DataAspectRatioMode
Use MATLAB or user-specified data
aspect ratio
Values: auto, manual
Default: auto
2-114
axes
Property Name
Property Description
Property Value
PlotBoxAspectRatio
Relative scaling of axes plot box
Values: three relative
values [dx dy dz]
Default: automatically
determined by MATLAB
PlotBoxAspectRatioMode
Use MATLAB or user-specified plot
box aspect ratio
Values: auto, manual
Default: auto
Controlling Callback Routine Execution
BusyAction
Specify how to handle events that
interrupt execution callback
routines
Values: cancel, queue
Default: queue
ButtonDownFcn
Define a callback routine that
executes when a button is pressed
over the axes
Values: string or function
handle
Default: an empty string
CreateFcn
Define a callback routine that
executes when an axes is created
Values: string or function
handle
Default: an empty string
DeleteFcn
Define a callback routine that
executes when an axes is created
Values: string or function
handle
Default: an empty string
Interruptible
Control whether an executing
callback routine can be interrupted
Values: on, off Default: on
UIContextMenu
Associate a context menu with the
axes
Values: handle of a
Uicontextmenu
Specifying the Rendering Mode
DrawMode
Specify the rendering method to use
with the Painters renderer
Values: normal, fast
Default: normal
Targeting Axes for Graphics Display
HandleVisibility
Control access to a specific axes’
handle
Values: on, callback, off
Default: on
2-115
axes
Property Name
Property Description
Property Value
NextPlot
Determine the eligibility of the axes
for displaying graphics
Values: add, replace,
replacechildren
Default: replace
Properties that Specify Transparency
ALim
Alpha axis limits
Values: [amin amax]
ALimMode
Alpha axis limits mode
Values: auto | manual
Default: auto
Properties that Specify Color
AmbientLightColor
Color of the background light in a
scene
Values: ColorSpec
Default: [1 1 1]
CLim
Control how data is mapped to
colormap
Values: [cmin cmax]
Default: automatically
determined by MATLAB
CLimMode
Use MATLAB or user-specified
values for CLim
Values: auto, manual
Default: auto
Color
Color of the axes background
Values: none, ColorSpec
Default: none
ColorOrder
Line colors used for multiline plots
Values: m-by-3 matrix of
RGB values
Default: depends on color
scheme used
XColor, YColor, ZColor
Colors of the axis lines and tick
marks
Values: ColorSpec
Default: depends on current
color scheme
2-116
Axes Properties
Modifying
Properties
2Axes Properties
You can set and query graphics object properties in two ways:
• The Property Editor is an interactive tool that enables you to see and change
object property values.
• The set and get commands enable you to set and query the values of
properties
To change the default value of properties see Setting Default Property Values.
Axes Property
Descriptions
This section lists property names along with the types of values each accepts.
Curly braces { } enclose default values.
ALim
[amin, amax]
Alpha axis limits. A two-element vector that determines how MATLAB maps
the AlphaData values of surface, patch and image objects to the figure's
alphamap. amin is the value of the data mapped to the first alpha value in the
alphamap, and amax is the value of the data mapped to the last alpha value in
the alphamap. Data values in between are linearly interpolated across the
alphamap, while data values outside are clamped to either the first or last
alphamap value, whichever is closest.
When ALimMode is auto (the default), MATLAB assigns amin the minimum
data value and amax the maximum data value in the graphics object's
AlphaData. This maps AlphaData elements with minimum data values to the
first alphamap entry and those with maximum data values to the last
alphamap entry. Data values in between are mapped linearly to the values
If the axes contains multiple graphics objects, MATLAB sets ALim to span the
range of all objects' AlphaData (or FaceVertexAlphaData for patch objects).
ALimMode
{auto} | manual
Alpha axis limits mode. In auto mode, MATLAB sets the ALim property to span
the AlphaData limits of the graphics objects displayed in the axes. If ALimMode
is manual, MATLAB does not change the value of ALim when the AlphaData
limits of axes children change. Setting the ALim property sets ALimMode to
manual.
AmbientLightColor ColorSpec
The background light in a scene. Ambient light is a directionless light that
shines uniformly on all objects in the axes. However, if there are no visible light
2-117
Axes Properties
objects in the axes, MATLAB does not use AmbientLightColor. If there are
light objects in the axes, the AmbientLightColor is added to the other light
sources.
AspectRatio
(Obsolete)
This property produces a warning message when queried or changed. It has
been superseded by the DataAspectRatio[Mode] and
PlotBoxAspectRatio[Mode] properties.
Box
on | {off}
Axes box mode. This property specifies whether to enclose the axes extent in a
box for 2-D views or a cube for 3-D views. The default is to not display the box.
BusyAction
cancel | {queue}
Callback routine interruption. The BusyAction property enables you to control
how MATLAB handles events that potentially interrupt executing callback
routines. If there is a callback routine executing, subsequently invoked
callback routines always attempt to interrupt it. If the Interruptible property
of the object whose callback is executing is set to on (the default), then
interruption occurs at the next point where the event queue is processed. If the
Interruptible property is off, the BusyAction property (of the object owning
the executing callback) determines how MATLAB handles the event. The
choices are:
• cancel – discard the event that attempted to execute a second callback
routine.
• queue – queue the event that attempted to execute a second callback routine
until the current callback finishes.
ButtonDownFcn
string or function handle
Button press callback routine. A callback routine that executes whenever you
press a mouse button while the pointer is within the axes, but not over another
graphics object displayed in the axes. For 3-D views, the active area is defined
by a rectangle that encloses the axes.
Define this routine as a string that is a valid MATLAB expression or the name
of an M-file. The expression executes in the MATLAB workspace.
See Function Handle Callbacks for information on how to use function handles
to define the callback function.
2-118
Axes Properties
CameraPosition
[x, y, z] axes coordinates
The location of the camera. This property defines the position from which the
camera views the scene. Specify the point in axes coordinates.
If you fix CameraViewAngle, you can zoom in and out on the scene by changing
the CameraPosition, moving the camera closer to the CameraTarget to zoom in
and farther away from the CameraTarget to zoom out. As you change the
CameraPosition, the amount of perspective also changes, if Projection is
perspective. You can also zoom by changing the CameraViewAngle; however,
this does not change the amount of perspective in the scene.
CameraPositionMode
{auto} | manual
Auto or manual CameraPosition. When set to auto, MATLAB automatically
calculates the CameraPosition such that the camera lies a fixed distance from
the CameraTarget along the azimuth and elevation specified by view. Setting a
value for CameraPosition sets this property to manual.
CameraTarget
[x, y, z] axes coordinates
Camera aiming point. This property specifies the location in the axes that the
camera points to. The CameraTarget and the CameraPosition define the vector
(the view axis) along which the camera looks.
CameraTargetMode
{auto} | manual
Auto or manual CameraTarget placement. When this property is auto,
MATLAB automatically positions the CameraTarget at the centroid of the axes
plotbox. Specifying a value for CameraTarget sets this property to manual.
CameraUpVector
[x, y, z] axes coordinates
Camera rotation. This property specifies the rotation of the camera around the
viewing axis defined by the CameraTarget and the CameraPosition properties.
Specify CameraUpVector as a three-element array containing the x, y, and z
components of the vector. For example, [0 1 0] specifies the positive y-axis as
the up direction.
The default CameraUpVector is [0 0 1], which defines the positive z-axis as the
up direction.
CameraUpVectorMode auto} | manual
Default or user-specified up vector. When CameraUpVectorMode is auto,
MATLAB uses a value of [0 0 1] (positive z-direction is up) for 3-D views and
2-119
Axes Properties
[0 1 0] (positive y-direction is up) for 2-D views. Setting a value for
CameraUpVector sets this property to manual.
CameraViewAngle
scalar greater than 0 and less than or equal to
180 (angle in degrees)
The field of view. This property determines the camera field of view. Changing
this value affects the size of graphics objects displayed in the axes, but does not
affect the degree of perspective distortion. The greater the angle, the larger the
field of view, and the smaller objects appear in the scene.
CameraViewAngleMode{auto} | manual
Auto or manual CameraViewAngle. When in auto mode, MATLAB sets
CameraViewAngle to the minimum angle that captures the entire scene (up to
180˚).
The following table summarizes MATLAB automatic camera behavior.
CameraView
Angle
Camera
Target
Camera
Position
Behavior
auto
auto
auto
CameraTarget is set to plot box centroid,
CameraViewAngle is set to capture entire scene,
CameraPosition is set along the view axis.
auto
auto
manual
CameraTarget is set to plot box centroid,
CameraViewAngle is set to capture entire scene.
auto
manual
auto
CameraViewAngle is set to capture entire scene,
CameraPosition is set along the view axis.
auto
manual
manual
CameraViewAngle is set to capture entire scene.
manual
auto
auto
CameraTarget is set to plot box centroid,
CameraPosition is set along the view axis.
manual
auto
manual
CameraTarget is set to plot box centroid
manual
manual
auto
CameraPosition is set along the view axis.
manual
manual
manual
All Camera properties are user-specified.
2-120
Axes Properties
Children
vector of graphics object handles
Children of the axes. A vector containing the handles of all graphics objects
rendered within the axes (whether visible or not). The graphics objects that can
be children of axes are images, lights, lines, patches, surfaces, and text. You
can change the order of the handles and thereby change the stacking of the
objects on the display.
The text objects used to label the x-, y-, and z-axes are also children of axes, but
their HandleVisibility properties are set to callback. This means their
handles do not show up in the axes Children property unless you set the Root
ShowHiddenHandles property to on.
CLim
[cmin, cmax]
Color axis limits. A two-element vector that determines how MATLAB maps
the CData values of surface and patch objects to the figure’s colormap. cmin is
the value of the data mapped to the first color in the colormap, and cmax is the
value of the data mapped to the last color in the colormap. Data values in
between are linearly interpolated across the colormap, while data values
outside are clamped to either the first or last colormap color, whichever is
closest.
When CLimMode is auto (the default), MATLAB assigns cmin the minimum
data value and cmax the maximum data value in the graphics object’s CData.
This maps CData elements with minimum data value to the first colormap
entry and with maximum data value to the last colormap entry.
If the axes contains multiple graphics objects, MATLAB sets CLim to span the
range of all objects’ CData.
CLimMode
{auto} | manual
Color axis limits mode. In auto mode, MATLAB sets the CLim property to span
the CData limits of the graphics objects displayed in the axes. If CLimMode is
manual, MATLAB does not change the value of CLim when the CData limits of
axes children change. Setting the CLim property sets this property to manual.
Clipping
{on} | off
This property has no effect on axes.
2-121
Axes Properties
Color
{none} | ColorSpec
Color of the axes back planes. Setting this property to none means the axes is
transparent and the figure color shows through. A ColorSpec is a
three-element RGB vector or one of the MATLAB predefined names. Note that
while the default value is none, the matlabrc.m file may set the axes color to
a specific color.
ColorOrder
m-by-3 matrix of RGB values
Colors to use for multiline plots. ColorOrder is an m-by-3 matrix of RGB values
that define the colors used by the plot and plot3 functions to color each line
plotted. If you do not specify a line color with plot and plot3, these functions
cycle through the ColorOrder to obtain the color for each line plotted. To obtain
the current ColorOrder, which may be set during startup, get the property
value:
get(gca,'ColorOrder')
Note that if the axes NextPlot property is set to replace (the default),
high-level functions like plot reset the ColorOrder property before
determining the colors to use. If you want MATLAB to use a ColorOrder that
is different from the default, set NextPlot to replacechildren. You can also
specify your own default ColorOrder.
CreateFcn
string or function handle
Callback routine executed during object creation. This property defines a
callback routine that executes when MATLAB creates an axes object. You must
define this property as a default value for axes. For example, the statement,
set(0,'DefaultAxesCreateFcn','set(gca,''Color'',''b'')')
defines a default value on the Root level that sets the current axes’ background
color to blue whenever you (or MATLAB) create an axes. MATLAB executes
this routine after setting all properties for the axes. Setting this property on an
existing axes object has no effect.
The handle of the object whose CreateFcn is being executed is accessible only
through the Root CallbackObject property, which can be queried using gcbo.
See Function Handle Callbacks for information on how to use function handles
to define the callback function.
2-122
Axes Properties
CurrentPoint
2-by-3 matrix
Location of last button click, in axes data units. A 2-by-3 matrix containing the
coordinates of two points defined by the location of the pointer. These two
points lie on the line that is perpendicular to the plane of the screen and passes
through the pointer. The 3-D coordinates are the points, in the axes coordinate
system, where this line intersects the front and back surfaces of the axes
volume (which is defined by the axes x, y, and z limits).
The returned matrix is of the form:
x back y back z back
x front y front z front
MATLAB updates the CurrentPoint property whenever a button-click event
occurs. The pointer does not have to be within the axes, or even the figure
window; MATLAB returns the coordinates with respect to the requested axes
regardless of the pointer location.
DataAspectRatio
[dx dy dz]
Relative scaling of data units. A three-element vector controlling the relative
scaling of data units in the x, y, and z directions. For example, setting this
property t o [1 2 1] causes the length of one unit of data in the x direction to
be the same length as two units of data in the y direction and one unit of data
in the z direction.
Note that the DataAspectRatio property interacts with the
PlotBoxAspectRatio, XLimMode, YLimMode, and ZLimMode properties to control
how MATLAB scales the x-, y-, and z-axis. Setting the DataAspectRatio will
disable the stretch-to-fill behavior, if DataAspectRatioMode,
PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto. The
2-123
Axes Properties
following table describes the interaction between properties when
stretch-to-fill behavior is disabled.
X-, Y-,
Z-Limits
DataAspect
Ratio
PlotBox
AspectRatio
Behavior
auto
auto
auto
Limits chosen to span data range in all
dimensions.
auto
auto
manual
Limits chosen to span data range in all
dimensions. DataAspectRatio is modified to
achieve the requested PlotBoxAspectRatio
within the limits selected by MATLAB.
auto
manual
auto
Limits chosen to span data range in all
dimensions. PlotBoxAspectRatio is modified to
achieve the requested DataAspectRatio within
the limits selected by MATLAB.
auto
manual
manual
Limits chosen to completely fit and center the
plot within the requested PlotBoxAspectRatio
given the requested DataAspectRatio (this may
produce empty space around 2 of the 3
dimensions).
manual
auto
auto
Limits are honored. The DataAspectRatio and
PlotBoxAspectRatio are modified as necessary.
manual
auto
manual
Limits and PlotBoxAspectRatio are honored.
The DataAspectRatio is modified as necessary.
manual
manual
auto
Limits and DataAspectRatio are honored. The
PlotBoxAspectRatio is modified as necessary.
1 manual
2 auto
manual
manual
The 2 automatic limits are selected to honor the
specified aspect ratios and limit. See “Examples”
2 or 3
manual
manual
manual
Limits and DataAspectRatio are honored; the
PlotBoxAspectRatio is ignored.
2-124
Axes Properties
DataAspectRatioMode
{auto} | manual
User or MATLAB controlled data scaling. This property controls whether the
values of the DataAspectRatio property are user defined or selected
automatically by MATLAB. Setting values for the DataAspectRatio property
automatically sets this property to manual. Changing DataAspectRatioMode to
manual disables the stretch-to-fill behavior, if DataAspectRatioMode,
PlotBoxAspectRatioMode, and CameraViewAngleMode are all auto.
DeleteFcn
string or function handle
Delete axes callback routine. A callback routine that executes when the axes
object is deleted (e.g., when you issue a delete or a close command). MATLAB
executes the routine before destroying the object’s properties so the callback
routine can query these values.
The handle of the object whose DeleteFcn is being executed is accessible only
through the Root CallbackObject property, which can be queried using gcbo.
See Function Handle Callbacks for information on how to use function handles
to define the callback function.
DrawMode
{normal} | fast
Rendering method. This property controls the method MATLAB uses to render
graphics objects displayed in the axes, when the figure Renderer property is
painters.
• normal mode draws objects in back to front ordering based on the current
view in order to handle hidden surface elimination and object intersections.
• fast mode draws objects in the order in which you specify the drawing
commands, without considering the relationships of the objects in three
dimensions. This results in faster rendering because it requires no sorting of
objects according to location in the view, but may produce undesirable
results because it bypasses the hidden surface elimination and object
intersection handling provided by normal DrawMode.
When the figure Renderer is zbuffer, DrawMode is ignored, and hidden surface
elimination and object intersection handling are always provided.
FontAngle
{normal} | italic | oblique
Select italic or normal font. This property selects the character slant for axes
text. normal specifies a nonitalic font. italic and oblique specify italic font.
2-125
Axes Properties
FontName
A name such as Courier or the string FixedWidth
Font family name. The font family name specifying the font to use for axes
labels. To display and print properly, FontName must be a font that your system
supports. Note that the x-, y-, and z-axis labels do not display in a new font until
you manually reset them (by setting the XLabel, YLabel, and ZLabel properties
or by using the xlabel, ylabel, or zlabel command). Tick mark labels change
immediately.
Specifying a Fixed-Width Font
If you want an axes to use a fixed-width font that looks good in any locale, you
should set FontName to the string FixedWidth:
set(axes_handle,'FontName','FixedWidth')
This eliminates the need to hardcode the name of a fixed-width font, which may
not display text properly on systems that do not use ASCII character encoding
(such as in Japan where multibyte character sets are used). A properly written
MATLAB application that needs to use a fixed-width font should set FontName
to FixedWidth (note that this string is case sensitive) and rely on
FixedWidthFontName to be set correctly in the end-user’s environment.
End users can adapt a MATLAB application to different locales or personal
environments by setting the root FixedWidthFontName property to the
appropriate value for that locale from startup.m.
Note that setting the root FixedWidthFontName property causes an immediate
update of the display to use the new font.
FontSize
Font size specified in FontUnits
Font size. An integer specifying the font size to use for axes labels and titles, in
units determined by the FontUnits property. The default point size is 12. The
x-, y-, and z-axis text labels do not display in a new font size until you manually
reset them (by setting the XLabel, YLabel, or ZLabel properties or by using the
xlabel, ylabel, or zlabel command). Tick mark labels change immediately.
FontUnits
{points} | normalized | inches |
centimeters | pixels
Units used to interpret the FontSize property. When set to normalized,
MATLAB interprets the value of FontSize as a fraction of the height of the
axes. For example, a normalized FontSize of 0.1 sets the text characters to a
2-126
Axes Properties
font whose height is one tenth of the axes’ height. The default units (points),
are equal to 1/72 of an inch.
FontWeight
{normal} | bold | light | demi
Select bold or normal font. The character weight for axes text. The x-, y-, and
z-axis text labels do not display in bold until you manually reset them (by
setting the XLabel, YLabel, and ZLabel properties or by using the xlabel,
ylabel, or zlabel commands). Tick mark labels change immediately.
GridLineStyle
− | − −| {:} | −. | none
Line style used to draw grid lines. The line style is a string consisting of a
character, in quotes, specifying solid lines (−), dashed lines (−−), dotted lines(:),
or dash-dot lines (−.). The default grid line style is dotted. To turn on grid lines,
use the grid command.
HandleVisibility
{on} | callback | off
Control access to object’s handle by command-line users and GUIs. This
property determines when an object’s handle is visible in its parent’s list of
children. HandleVisibility is useful for preventing command-line users from
accidentally drawing into or deleting a figure that contains only user interface
devices (such as a dialog box).
Handles are always visible when HandleVisibility is on.
Setting HandleVisibility to callback causes handles to be visible from
within callback routines or functions invoked by callback routines, but not from
within functions invoked from the command line. This provides a means to
protect GUIs from command-line users, while allowing callback routines to
have complete access to object handles.
Setting HandleVisibility to off makes handles invisible at all times. This
may be necessary when a callback routine invokes a function that might
potentially damage the GUI (such as evaluating a user-typed string) and so
temporarily hides its own handles during the execution of that function.
When a handle is not visible in its parent’s list of children, it cannot be
returned by functions that obtain handles by searching the object hierarchy or
querying handle properties. This includes get, findobj, gca, gcf, gco, newplot,
cla, clf, and close.
2-127
Axes Properties
When a handle’s visibility is restricted using callback or off, the object’s
handle does not appear in its parent’s Children property, figures do not appear
in the Root’s Currentfigure property, objects do not appear in the Root’s
CallbackObject property or in the figure’s CurrentObject property, and axes
do not appear in their parent’s Currentaxes property.
You can set the Root ShowHiddenHandles property to on to make all handles
visible, regardless of their HandleVisibility settings (this does not affect the
values of the HandleVisibility properties).
Handles that are hidden are still valid. If you know an object’s handle, you can
set and get its properties, and pass it to any function that operates on handles.
HitTest
{on} | off
Selectable by mouse click. HitTest determines if the axes can become the
current object (as returned by the gco command and the figure CurrentObject
property) as a result of a mouse click on the axes. If HitTest is off, clicking on
the axes selects the object below it (which is usually the figure containing it).
Interruptible
{on} | off
Callback routine interruption mode. The Interruptible property controls
whether an axes callback routine can be interrupted by subsequently invoked
callback routines. Only callback routines defined for the ButtonDownFcn are
affected by the Interruptible property. MATLAB checks for events that can
interrupt a callback routine only when it encounters a drawnow, figure,
getframe, or pause command in the routine. See the BusyAction property for
related information.
Setting Interruptible to on allows any graphics object’s callback routine to
interrupt callback routines originating from an axes property. Note that
MATLAB does not save the state of variables or the display (e.g., the handle
returned by the gca or gcf command) when an interruption occurs.
Layer
{bottom} | top
Draw axis lines below or above graphics objects. This property determines if
axis lines and tick marks draw on top or below axes children objects for any 2-D
view (i.e., when you are looking along the x-, y-, or z-axis). This is useful for
placing grid lines and tick marks on top of images.
2-128
Axes Properties
LineStyleOrder
LineSpec
Order of line styles and markers used in a plot. This property specifies which
line styles and markers to use and in what order when creating multiple-line
plots. For example,
set(gca,'LineStyleOrder', '−*|:|o')
sets LineStyleOrder to solid line with asterisk marker, dotted line, and hollow
circle marker. The default is (−), which specifies a solid line for all data plotted.
Alternatively, you can create a cell array of character strings to define the line
styles:
set(gca,'LineStyleOrder',{'−*',':','o'})
MATLAB supports four line styles, which you can specify any number of times
in any order. MATLAB cycles through the line styles only after using all colors
defined by the ColorOrder property. For example, the first eight lines plotted
use the different colors defined by ColorOrder with the first line style.
MATLAB then cycles through the colors again, using the second line style
specified, and so on.
You can also specify line style and color directly with the plot and plot3
functions or by altering the properties of the line objects.
Note that, if the axes NextPlot property is set to replace (the default),
high-level functions like plot reset the LineStyleOrder property before
determining the line style to use. If you want MATLAB to use a
LineStyleOrder that is different from the default, set NextPlot to
replacechildren. You can also specify your own default LineStyleOrder.
LineWidth
linewidth in points
Width of axis lines. This property specifies the width, in points, of the x-, y-, and
z-axis lines. The default line width is 0.5 points (1 point = 1/72 inch).
MinorGridLineStyle − | − −| {:} | −. | none
Line style used to draw minor grid lines. The line style is a string consisting of
one or more characters, in quotes, specifying solid lines (−), dashed lines (−−),
dotted lines(:), or dash-dot lines (−.). The default minor grid line style is dotted.
To turn on minor grid lines, use the grid minor command.
2-129
Axes Properties
NextPlot
add | {replace} | replacechildren
Where to draw the next plot. This property determines how high-level plotting
functions draw into an existing axes.
• add — use the existing axes to draw graphics objects.
• replace — reset all axes properties, except Position, to their defaults and
delete all axes children before displaying graphics (equivalent to cla reset).
• replacechildren — remove all child objects, but do not reset axes properties
(equivalent to cla).
The newplot function simplifies the use of the NextPlot property and is used
by M-file functions that draw graphs using only low-level object creation
routines. See the M-file pcolor.m for an example. Note that figure graphics
objects also have a NextPlot property.
Parent
figure handle
Axes parent. The handle of the axes’ parent object. The parent of an axes object
is the figure in which it is displayed. The utility function gcf returns the
handle of the current axes’ Parent. You can reparent axes to other figure
objects.
PlotBoxAspectRatio
[px py pz]
Relative scaling of axes plotbox. A three-element vector controlling the relative
scaling of the plot box in the x-, y-, and z-directions. The plot box is a box
enclosing the axes data region as defined by the x-, y-, and z-axis limits.
Note that the PlotBoxAspectRatio property interacts with the
DataAspectRatio, XLimMode, YLimMode, and ZLimMode properties to control the
way graphics objects are displayed in the axes. Setting the
PlotBoxAspectRatio disables stretch-to-fill behavior, if
DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode
are all auto.
PlotBoxAspectRatioMode
{auto} | manual
User or MATLAB controlled axis scaling. This property controls whether the
values of the PlotBoxAspectRatio property are user defined or selected
automatically by MATLAB. Setting values for the PlotBoxAspectRatio
property automatically sets this property to manual. Changing the
PlotBoxAspectRatioMode to manual disables stretch-to-fill behavior, if
2-130
Axes Properties
DataAspectRatioMode, PlotBoxAspectRatioMode, and CameraViewAngleMode
are all auto.
Position
four-element vector
Position of axes. A four-element vector specifying a rectangle that locates the
axes within the figure window. The vector is of the form:
[left bottom width height]
where left and bottom define the distance from the lower-left corner of the
figure window to the lower-left corner of the rectangle. width and height are
the dimensions of the rectangle. All measurements are in units specified by the
Units property.
When axes stretch-to-fill behavior is enabled (when DataAspectRatioMode,
PlotBoxAspectRatioMode, CameraViewAngleMode are all auto), the axes are
stretched to fill the Position rectangle. When stretch-to-fill is disabled, the
axes are made as large as possible, while obeying all other properties, without
extending outside the Position rectangle
Projection
{orthographic} | perspective
Type of projection. This property selects between two projection types:
• orthographic – This projection maintains the correct relative dimensions of
graphics objects with regard to the distance a given point is from the viewer.
Parallel lines in the data are drawn parallel on the screen.
• perspective – This projection incorporates foreshortening, which allows you
to perceive depth in 2-D representations of 3-D objects. Perspective
projection does not preserve the relative dimensions of objects; a distant line
segment displays smaller than a nearer line segment of the same length.
Parallel lines in the data may not appear parallel on screen.
Selected
on | off
Is object selected. When you set this property to on, MATLAB displays selection
“handles” at the corners and midpoints if the SelectionHighlight property is
also on (the default). You can, for example, define the ButtonDownFcn callback
routine to set this property to on, thereby indicating that the axes has been
selected.
2-131
Axes Properties
SelectionHighlight
{on} | off
Objects highlight when selected. When the Selected property is on, MATLAB
indicates the selected state by drawing four edge handles and four corner
handles. When SelectionHighlight is off, MATLAB does not draw the
handles.
Tag
string (GUIDE sets this property)
User-specified object label. The Tag property provides a means to identify
graphics objects with a user-specified label. This is particularly useful when
constructing interactive graphics programs that would otherwise need to
define object handles as global variables or pass them as arguments between
callback routines.
For example, suppose you want to direct all graphics output from an M-file to
a particular axes, regardless of user actions that may have changed the current
axes. To do this, identify the axes with a Tag:
axes('Tag','Special Axes')
Then make that axes the current axes before drawing by searching for the Tag
with findobj:
axes(findobj('Tag','Special Axes'))
TickDir
in | out
Direction of tick marks. For 2-D views, the default is to direct tick marks
inward from the axis lines; 3-D views direct tick marks outward from the axis
line.
TickDirMode
{auto} | manual
Automatic tick direction control. In auto mode, MATLAB directs tick marks
inward for 2-D views and outward for 3-D views. When you specify a setting for
TickDir, MATLAB sets TickDirMode to manual. In manual mode, MATLAB
does not change the specified tick direction.
TickLength
[2DLength 3DLength]
Length of tick marks. A two-element vector specifying the length of axes tick
marks. The first element is the length of tick marks used for 2-D views and the
second element is the length of tick marks used for 3-D views. Specify tick mark
lengths in units normalized relative to the longest of the visible X-, Y-, or Z-axis
annotation lines.
2-132
Axes Properties
Title
handle of text object
Axes title. The handle of the text object that is used for the axes title. You can
use this handle to change the properties of the title text or you can set Title to
the handle of an existing text object. For example, the following statement
changes the color of the current title to red:
set(get(gca,'Title'),'Color','r')
To create a new title, set this property to the handle of the text object you want
to use:
set(gca,'Title',text('String','New Title','Color','r'))
However, it is generally simpler to use the title command to create or replace
an axes title:
title('New Title','Color','r')
Type
string (read only)
Type of graphics object. This property contains a string that identifies the class
of graphics object. For axes objects, Type is always set to 'axes'.
UIContextMenu
handle of a uicontextmenu object
Associate a context menu with the axes. Assign this property the handle of a
Uicontextmenu object created in the axes’ parent figure. Use the
uicontextmenu function to create the context menu. MATLAB displays the
context menu whenever you right-click over the axes.
Units
inches | centimeters | {normalized} |
points | pixels | characters
Position units. The units used to interpret the Position property. All units are
measured from the lower-left corner of the figure window.
• normalized units map the lower-left corner of the figure window to (0,0) and
the upper-right corner to (1.0, 1.0).
• inches, centimeters, and points are absolute units (one point equals 1/72 of
an inch).
• Character units are defined by characters from the default system font; the
width of one character is the width of the letter x, the height of one character
is the distance between the baselines of two lines of text.
2-133
Axes Properties
UserData
matrix
User specified data. This property can be any data you want to associate with
the axes object. The axes does not use this property, but you can access it using
the set and get functions.
View
Obsolete
The functionality provided by the View property is now controlled by the axes
camera properties – CameraPosition, CameraTarget, CameraUpVector, and
CameraViewAngle. See the view command.
Visible
{on} | off
Visibility of axes. By default, axes are visible. Setting this property to off
prevents axis lines, tick marks, and labels from being displayed. The visible
property does not affect children of axes.
XAxisLocation
top | {bottom}
Location of x-axis tick marks and labels. This property controls where
MATLAB displays the x-axis tick marks and labels. Setting this property to top
moves the x-axis to the top of the plot from its default position at the bottom.
YAxisLocation
right | {left}
Location of y-axis tick marks and labels. This property controls where
MATLAB displays the y-axis tick marks and labels. Setting this property to
right moves the y-axis to the right side of the plot from its default position on
the left side. See the plotyy function for a simple way to use two y-axes.
Properties That Control the X-, Y-, or Z-Axis
XColor, YColor, ZColor
ColorSpec
Color of axis lines. A three-element vector specifying an RGB triple, or a
predefined MATLAB color string. This property determines the color of the
axis lines, tick marks, tick mark labels, and the axis grid lines of the respective
x-, y-, and z-axis. The default color axis color is black. See ColorSpec for details
on specifying colors.
XDir, YDir, ZDir
{normal} | reverse
Direction of increasing values. A mode controlling the direction of increasing
axis values. axes form a right-hand coordinate system. By default:
2-134
Axes Properties
• x-axis values increase from left to right. To reverse the direction of increasing
x values, set this property to reverse.
set(gca,'XDir','reverse')
• y-axis values increase from bottom to top (2-D view) or front to back (3-D
view). To reverse the direction of increasing y values, set this property to
reverse.
set(gca,'YDir','reverse')
• z-axis values increase pointing out of the screen (2-D view) or from bottom to
top (3-D view). To reverse the direction of increasing z values, set this
property to reverse.
set(gca,'ZDir','reverse')
XGrid, YGrid, ZGrid
on | {off}
Axis gridline mode. When you set any of these properties to on, MATLAB draws
grid lines perpendicular to the respective axis (i.e., along lines of constant x, y,
or z values). Use the grid command to set all three properties on or off at once.
set(gca,'XGrid','on')
XLabel, YLabel, ZLabel
handle of text object
Axis labels. The handle of the text object used to label the x, y, or z-axis,
respectively. To assign values to any of these properties, you must obtain the
handle to the text string you want to use as a label. This statement defines a
text object and assigns its handle to the XLabel property:
set(get(gca,'XLabel'),'String','axis label')
MATLAB places the string 'axis label' appropriately for an x-axis label. Any
text object whose handle you specify as an XLabel, YLabel, or ZLabel property
is moved to the appropriate location for the respective label.
Alternatively, you can use the xlabel, ylabel, and zlabel functions, which
generally provide a simpler means to label axis lines.
XLim, YLim, ZLim
[minimum maximum]
Axis limits. A two-element vector specifying the minimum and maximum
values of the respective axis.
2-135
Axes Properties
Changing these properties affects the scale of the x-, y-, or z-dimension as well
as the placement of labels and tick marks on the axis. The default values for
these properties are [0 1].
XLimMode, YLimMode, ZLimMode{auto} | manual
MATLAB or user-controlled limits. The axis limits mode determines whether
MATLAB calculates axis limits based on the data plotted (i.e., the XData,
YData, or ZData of the axes children) or uses the values explicitly set with the
XLim, YLim, or ZLim property, in which case, the respective limits mode is set to
manual.
on | {off}
XMinorGrid, YMinorGrid, ZMinorGrid
Enable or disable minor gridlines. When set to on, MATLAB draws gridlines
aligned with the minor tick marks of the respective axis. Note that you do not
have to enable minor ticks to display minor grids.
on | {off}
XMinorTick, YMinorTick, ZMinorTick
Enable or disable minor tick marks. When set to on, MATLAB draws tick
marks between the major tick marks of the respective axis. MATLAB
automaticaly determines the number of minor ticks based on the space
between the major ticks.
XScale, YScale, ZScale
{linear} | log
Axis scaling. Linear or logarithmic scaling for the respective axis. See also
loglog, semilogx, and semilogy.
XTick, YTick, ZTick
vector of data values locating tick marks
Tick spacing. A vector of x-, y-, or z-data values that determine the location of
tick marks along the respective axis. If you do not want tick marks displayed,
set the respective property to the empty vector, [ ]. These vectors must contain
monotonically increasing values.
XTickLabel, YTickLabel, ZTickLabel
string
Tick labels. A matrix of strings to use as labels for tick marks along the
respective axis. These labels replace the numeric labels generated by
MATLAB. If you do not specify enough text labels for all the tick marks,
MATLAB uses all of the labels specified, then reuses the specified labels.
For example, the statement,
set(gca,'XTickLabel',{'One';'Two';'Three';'Four'})
2-136
Axes Properties
labels the first four tick marks on the x-axis and then reuses the labels until all
ticks are labeled.
Labels can be specified as cell arrays of strings, padded string matrices, string
vectors separated by vertical slash characters, or as numeric vectors (where
each number is implicitly converted to the equivalent string using num2str).
All of the following are equivalent:
set(gca,'XTickLabel',{'1';'10';'100'})
set(gca,'XTickLabel','1|10|100')
set(gca,'XTickLabel',[1;10;100])
set(gca,'XTickLabel',['1 ';'10 ';'100'])
Note that tick labels do not interpret TeX character sequences (however, the
Title, XLabel, YLabel, and ZLabel properties do).
XTickMode, YTickMode, ZTickMode {auto} | manual
MATLAB or user controlled tick spacing. The axis tick modes determine
whether MATLAB calculates the tick mark spacing based on the range of data
for the respective axis (auto mode) or uses the values explicitly set for any of
the XTick, YTick, and ZTick properties (manual mode). Setting values for the
XTick, YTick, or ZTick properties sets the respective axis tick mode to manual.
XTickLabelMode, YTickLabelMode, ZTickLabelMode
{auto} | manual
MATLAB or user determined tick labels. The axis tick mark labeling mode
determines whether MATLAB uses numeric tick mark labels that span the
range of the plotted data (auto mode) or uses the tick mark labels specified
with the XTickLabel, YTickLabel, or ZTickLabel property (manual mode).
Setting values for the XTickLabel, YTickLabel, or ZTickLabel property sets
the respective axis tick label mode to manual.
2-137
axis
Purpose
Syntax
2axis
Axis scaling and appearance
axis([xmin xmax ymin ymax])
axis([xmin xmax ymin ymax zmin zmax cmin cmax])
v = axis
axis
axis
axis
axis
auto
manual
tight
fill
axis ij
axis xy
axis
axis
axis
axis
axis
equal
image
square
vis3d
normal
axis off
axis on
axis(axes_handles,...)
[mode,visibility,direction] = axis('state')
Description
axis manipulates commonly used axes properties. (See Algorithm section.)
axis([xmin xmax ymin ymax]) sets the limits for the x- and y-axis of the
current axes.
axis([xmin xmax ymin ymax zmin zmax cmin cmax]) sets the x-, y-, and
z-axis limits and the color scaling limits (see caxis) of the current axes.
v = axis returns a row vector containing scaling factors for the x-, y-, and
z-axis. v has four or six components depending on whether the current axes is
2-D or 3-D, respectively. The returned values are the current axes’ XLim, Ylim,
and ZLim properties.
2-138
axis
axis auto sets MATLAB to its default behavior of computing the current axes’
limits automatically, based on the minimum and maximum values of x, y, and
z data. You can restrict this automatic behavior to a specific axis. For example,
axis 'auto x' computes only the x-axis limits automatically; axis 'auto yz'
computes the y- and z-axis limits automatically.
axis manual and axis(axis) freezes the scaling at the current limits, so that
if hold is on, subsequent plots use the same limits. This sets the XLimMode,
YLimMode, and ZLimMode properties to manual.
axis tight sets the axis limits to the range of the data.
axis fill sets the axis limits and PlotBoxAspectRatio so that the axes fill
the position rectangle. This option has an effect only if
PlotBoxAspectRatioMode or DataAspectRatioMode are manual.
axis ij places the coordinate system origin in the upper-left corner. The i-axis
is vertical, with values increasing from top to bottom. The j-axis is horizontal
with values increasing from left to right.
axis xy draws the graph in the default Cartesian axes format with the
coordinate system origin in the lower-left corner. The x-axis is horizontal with
values increasing from left to right. The y-axis is vertical with values
increasing from bottom to top.
axis equal sets the aspect ratio so that the data units are the same in every
direction. The aspect ratio of the x-, y-, and z-axis is adjusted automatically
according to the range of data units in the x, y, and z directions.
axis image is the same as axis equal except that the plot box fits tightly
around the data.
axis square makes the current axes region square (or cubed when
three-dimensional). MATLAB adjusts the x-axis, y-axis, and z-axis so that they
have equal lengths and adjusts the increments between data units accordingly.
axis vis3d freezes aspect ratio properties to enable rotation of 3-D objects and
overrides stretch-to-fill.
2-139
axis
axis normal automatically adjusts the aspect ratio of the axes and the relative
scaling of the data units so that the plot fits the figures shape as best as
possible.
axis off turns off all axis lines, tick marks, and labels.
axis on turns on all axis lines, tick marks, and labels.
axis(axes_handles,...) applies the axis command to the specified axes. For
example, the following statements
h1 = subplot(221);
h2 = subplot(222);
axis([h1 h2],'square')
set both axes to square.
[mode,visibility,direction] = axis('state') returns three strings
indicating the current setting of axes properties:
Output Argument
Strings Returned
mode
'auto' | 'manual'
visibility
'on' | 'off'
direction
'xy' | 'ij'
mode is auto if XLimMode, YLimMode, and ZLimMode are all set to auto. If
XLimMode, YLimMode, or ZLimMode is manual, mode is manual.
Examples
The statements
x = 0:.025:pi/2;
plot(x,tan(x),'-ro')
2-140
axis
use the automatic scaling of the y-axis based on ymax = tan(1.57), which is
well over 1000:
1400
1200
1000
800
600
400
200
0
0
0.2
0.4
0.6
0.8
1
1.2
1.4
1.6
The right figure shows a more satisfactory plot after typing
2-141
axis
axis([0
pi/2
0
5])
5
4.5
4
3.5
3
2.5
2
1.5
1
0.5
0
Algorithm
0
0.5
1
1.5
When you specify minimum and maximum values for the x-, y-, and z-axes,
axis sets the XLim, Ylim, and ZLim properties for the current axes to the
respective minimum and maximum values in the argument list. Additionally,
the XLimMode, YLimMode, and ZLimMode properties for the current axes are set
to manual.
axis auto sets the current axes’ XLimMode, YLimMode, and ZLimMode properties
to 'auto'.
axis manual sets the current axes’ XLimMode, YLimMode, and ZLimMode
properties to 'manual'.
2-142
axis
The following table shows the values of the axes properties set by axis equal,
axis normal, axis square, and axis image.
Axes Property
axis equal
axis normal
axis square
axis tightequal
DataAspectRatio
[1 1 1]
not set
not set
[1 1 1]
DataAspectRatioMode
manual
auto
auto
manual
PlotBoxAspectRatio
[3 4 4]
not set
[1 1 1]
auto
PlotBoxAspectRatioMode
manual
auto
manual
auto
Stretch-to-fill
disabled
active
disabled
disabled
See Also
axes, get, grid, set, subplot
Properties of axes graphics objects
“Axes Operations” for related functions
2-143
balance
Purpose
2balance
Diagonal scaling to improve eigenvalue accuracy
Syntax
[T,B] = balance(A)
B = balance(A)
Description
[T,B] = balance(A) returns a similarity transformation T such that
B = T\A*T, and B has approximately equal row and column norms. T is a
permutation of a diagonal matrix whose elements are integer powers of two to
prevent the introduction of round-off error. If A is symmetric, then B == A and
T is the identity matrix.
B = balance(A) returns just the balanced matrix B.
Remarks
Nonsymmetric matrices can have poorly conditioned eigenvalues. Small
perturbations in the matrix, such as roundoff errors, can lead to large
perturbations in the eigenvalues. The condition number of the eigenvector
matrix,
cond(V) = norm(V)*norm(inv(V))
where
[V,T] = eig(A)
relates the size of the matrix perturbation to the size of the eigenvalue
perturbation. Note that the condition number of A itself is irrelevant to the
eigenvalue problem.
Balancing is an attempt to concentrate any ill conditioning of the eigenvector
matrix into a diagonal scaling. Balancing usually cannot turn a nonsymmetric
matrix into a symmetric matrix; it only attempts to make the norm of each row
equal to the norm of the corresponding column.
Note The MATLAB eigenvalue function, eig(A), automatically balances A
before computing its eigenvalues. Turn off the balancing with
eig(A,'nobalance').
2-144
balance
Examples
This example shows the basic idea. The matrix A has large elements in the
upper right and small elements in the lower left. It is far from being symmetric.
A = [1 100 10000; .01 1 100; .0001
A =
1.0e+04 *
0.0001
0.0100
1.0000
0.0000
0.0001
0.0100
0.0000
0.0000
0.0001
.01
1]
Balancing produces a diagonal matrix T with elements that are powers of two
and a balanced matrix B that is closer to symmetric than A.
[T,B] = balance(A)
T =
1.0e+03 *
2.0480
0
0
0.0320
0
0
B =
1.0000
1.5625
0.6400
1.0000
0.8192
1.2800
0
0
0.0003
1.2207
0.7813
1.0000
To see the effect on eigenvectors, first compute the eigenvectors of A, shown
here as the columns of V.
[V,E] = eig(A); V
V =
-1.0000
0.9999
0.0050
0.0100
0.0000
0.0001
0.9937
-0.1120
0.0010
Note that all three vectors have the first component the largest. This indicates
V is badly conditioned; in fact cond(V) is 8.7766e+003. Next, look at the
eigenvectors of B.
[V,E] = eig(B); V
V =
-0.8873
0.6933
0.2839
0.4437
0.3634
0.5679
0.0898
-0.6482
-0.7561
2-145
balance
Now the eigenvectors are well behaved and cond(V) is 1.4421. The ill
conditioning is concentrated in the scaling matrix; cond(T) is 8192.
This example is small and not really badly scaled, so the computed eigenvalues
of A and B agree within roundoff error; balancing has little effect on the
computed results.
Algorithm
balance uses LAPACK routines DGEBAL (real) and ZGEBAL (complex). If you
request the output T, it also uses the LAPACK routines DGEBAK (real) and
ZGEBAK (complex).
Limitations
Balancing can destroy the properties of certain matrices; use it with some care.
If a matrix contains small elements that are due to roundoff error, balancing
may scale them up to make them as significant as the other elements of the
original matrix.
See Also
eig
References
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra,
J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen,
LAPACK User’s Guide
(http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition,
SIAM, Philadelphia, 1999.
2-146
bar, barh
Purpose
Syntax
2bar, barh
Bar chart
bar(Y)
bar(x,Y)
bar(...,width)
bar(...,'style')
bar(...,LineSpec)
h = bar(...)
barh(...)
h = barh(...)
Description
A bar chart displays the values in a vector or matrix as horizontal or vertical
bars.
bar(Y) draws one bar for each element in Y. If Y is a matrix, bar groups the
bars produced by the elements in each row. The x-axis scale ranges from 1 to
length(Y) when Y is a vector, and 1 to size(Y,1), which is the number of rows,
when Y is a matrix.
bar(x,Y) draws a bar for each element in Y at locations specified in x, where x
is a monotonically increasing vector defining the x-axis intervals for the
vertical bars. If Y is a matrix, bar clusters the elements in the same row in Y at
locations corresponding to an element in x.
bar(...,width) sets the relative bar width and controls the separation of bars
within a group. The default width is 0.8, so if you do not specify x, the bars
within a group have a slight separation. If width is 1, the bars within a group
touch one another.
bar(...,'style') specifies the style of the bars. 'style' is 'grouped' or
'stacked'. 'group' is the default mode of display.
• 'grouped' displays n groups of m vertical bars, where n is the number of
rows and m is the number of columns in Y. The group contains one bar per
column in Y.
• 'stacked' displays one bar for each row in Y. The bar height is the sum of
the elements in the row. Each bar is multi-colored, with colors corresponding
2-147
bar, barh
to distinct elements and showing the relative contribution each row element
makes to the total sum.
bar(...,LineSpec) displays all bars using the color specified by LineSpec.
h = bar(...) returns a vector of handles to patch graphics objects. bar creates
one patch graphics object per column in Y.
barh(...), and h = barh(...) create horizontal bars. Y determines the bar
length. The vector x is a monotonic vector defining the y-axis intervals for
horizontal bars.
Examples
Plot a bell shaped curve:
x = –2.9:0.2:2.9;
bar(x,exp(–x.*x))
colormap hsv
1
0.9
0.8
0.7
0.6
0.5
0.4
0.3
0.2
0.1
0
−3
−2
−1
0
1
2
3
Create four subplots showing the effects of various bar arguments:
Y = round(rand(5,3)*10);
subplot(2,2,1)
bar(Y,'group')
title 'Group'
2-148
bar, barh
subplot(2,2,2)
bar(Y,'stack')
title 'Stack'
subplot(2,2,3)
barh(Y,'stack')
title 'Stack'
subplot(2,2,4)
bar(Y,1.5)
title 'Width = 1.5'
Group
Stack
10
25
8
20
6
15
4
10
2
5
0
0
1
2
3
4
5
1
Stack
2
3
4
5
Width = 1.5
10
5
8
4
6
3
4
2
2
1
0
0
5
10
15
20
25
1
2
3
4
5
2-149
bar, barh
See Also
bar3, ColorSpec, patch, stairs, hist
“Area, Bar, and Pie Plots” for related functions
Bar and Area Graphs for more examples
2-150
bar3, bar3h
Purpose
Syntax
2bar3, bar3h
Three-dimensional bar chart
bar3(Y)
bar3(x,Y)
bar3(...,width)
bar3(...,'style')
bar3(...,LineSpec)
h = bar3(...)
bar3h(...)
h = bar3h(...)
Description
bar3 and bar3h draw three-dimensional vertical and horizontal bar charts.
bar3(Y) draws a three-dimensional bar chart, where each element in Y
corresponds to one bar. When Y is a vector, the x-axis scale ranges from 1 to
length(Y). When Y is a matrix, the x-axis scale ranges from 1 to size(Y,2),
which is the number of columns, and the elements in each row are grouped
together.
bar3(x,Y) draws a bar chart of the elements in Y at the locations specified in
x, where x is a monotonic vector defining the y-axis intervals for vertical bars.
If Y is a matrix, bar3 clusters elements from the same row in Y at locations
corresponding to an element in x. Values of elements in each row are grouped
together.
bar3(...,width) sets the width of the bars and controls the separation of bars
within a group. The default width is 0.8, so if you do not specify x, bars within
a group have a slight separation. If width is 1, the bars within a group touch
one another.
bar3(...,'style') specifies the style of the bars. 'style' is 'detached',
'grouped', or 'stacked'. 'detached' is the default mode of display.
• 'detached' displays the elements of each row in Y as separate blocks behind
one another in the x direction.
• 'grouped' displays n groups of m vertical bars, where n is the number of
rows and m is the number of columns in Y. The group contains one bar per
column in Y.
2-151
bar3, bar3h
• 'stacked' displays one bar for each row in Y. The bar height is the sum of
the elements in the row. Each bar is multi-colored, with colors corresponding
to distinct elements and showing the relative contribution each row element
makes to the total sum.
bar3(...,LineSpec) displays all bars using the color specified by LineSpec.
h = bar3(...) returns a vector of handles to patch graphics objects. bar3
creates one patch object per column in Y.
bar3h(...) and h = bar3h(...) create horizontal bars. Y determines the bar
length. The vector x is a monotonic vector defining the y-axis intervals for
horizontal bars.
Examples
This example creates six subplots showing the effects of different arguments
for bar3. The data Y is a seven-by-three matrix generated using the cool
colormap:
Y = cool(7);
subplot(3,2,1)
bar3(Y,'detached')
title('Detached')
subplot(3,2,2)
bar3(Y,0.25,'detached')
title('Width = 0.25')
subplot(3,2,3)
bar3(Y,'grouped')
title('Grouped')
subplot(3,2,4)
bar3(Y,0.5,'grouped')
title('Width = 0.5')
2-152
bar3, bar3h
subplot(3,2,5)
bar3(Y,'stacked')
title('Stacked')
subplot(3,2,6)
bar3(Y,0.3,'stacked')
title('Width = 0.3')
colormap([1 0 0;0 1 0;0 0 1])
2-153
bar3, bar3h
Detached
Width = 0.25
1
1
0.5
0.5
0
0
1
2
1
3
4
5
6
Grouped
1
0.5
0.5
0
0
2
4
4
5
6
2
3
Stacked
1.5
1.5
1
1
0.5
0.5
0
0
See Also
1
3
4
5
6
7
4
5
6
7
Width = 0.3
2
2
6
7
2
1
5
Width = 0.5
1
3
3
7
1
1
2
2
3
4
7
5
6
7
bar, LineSpec, patch
“Area, Bar, and Pie Plots” for related functions
Bar and Area Graphs for more examples
2-154
base2dec
Purpose
2base2dec
Base to decimal number conversion
Syntax
d = base2dec('strn',base)
Description
d = base2dec('strn',base) converts the string number strn of the specified
base into its decimal (base 10) equivalent. base must be an integer between 2
and 36. If 'strn' is a character array, each row is interpreted as a string in the
specified base.
Examples
The expression base2dec('212',3) converts 2123 to decimal, returning 23.
See Also
dec2base
2-155
beep
Purpose
2beep
Produce a beep sound
Syntax
beep
beep on
beep off
s = beep
Description
beep produces you computer’s default beep sound
beep on turns the beep on
beep off turn the beep off
s = beep returns the current beep mode (on or off)
2-156
besselh
Purpose
2besselh
Bessel function of the third kind (Hankel function)
Syntax
H = besselh(nu,K,Z)
H = besselh(nu,Z)
H = besselh(nu,K,Z,1)
[H,ierr] = besselh(...)
Definitions
The differential equation
z
2d
2
y
dz
2
dy
2
2
+ z ------- + ( z – ν ) y = 0
dz
where ν is a nonnegative constant, is called Bessel’s equation, and its solutions
are known as Bessel functions. J ν ( z ) and J – ν ( z ) form a fundamental set of
solutions of Bessel’s equation for noninteger ν . Y ν ( z ) is a second solution of
Bessel’s equation – linearly independent of J ν ( z ) – defined by
J ν ( z ) cos ( νπ ) – J – ν ( z )
Y ν ( z ) = ----------------------------------------------------------sin ( νπ )
The relationship between the Hankel and Bessel functions is
(1)
H ν ( z) = J ν( z) + i Y ν( z)
(2)
H ν ( z) = J ν( z) – i Y ν( z)
where J ν ( z ) is besselj, and Y ν ( z ) is bessely.
Description
(K)
H = besselh(nu,K,Z) computes the Hankel function H ν ( z ) , where K = 1 or
2, for each element of the complex array Z. If nu and Z are arrays of the same
size, the result is also that size. If either input is a scalar, besselh expands it
to the other input's size. If one input is a row vector and the other is a column
vector, the result is a two-dimensional table of function values.
H = besselh(nu,Z) uses K = 1.
(K)
H = besselh(nu,K,Z,1) scales H ν ( z ) by exp(-i*Z) if K = 1, and by
exp(+i*Z) if K = 2.
2-157
besselh
[H,ierr] = besselh(...) also returns completion flags in an array the same
size as H.
ierr
Description
0
besselh successfully computed the Hankel function for this
element.
Examples
1
Illegal arguments.
2
Overflow. Returns Inf.
3
Some loss of accuracy in argument reduction.
4
Unacceptable loss of accuracy, Z or nu too large.
5
No convergence. Returns NaN.
This example generates the contour plots of the modulus and phase of the
(1)
Hankel function H 0 ( z ) shown on page 359 of [1] Abramowitz and Stegun,
Handbook of Mathematical Functions.
It first generates the modulus contour plot
[X,Y] = meshgrid(-4:0.025:2,-1.5:0.025:1.5);
H = besselh(0,1,X+i*Y);
contour(X,Y,abs(H),0:0.2:3.2), hold on
2-158
besselh
1.5
1
0.5
0
−0.5
−1
−1.5
−4
−3
−2
−1
0
1
2
then adds the contour plot of the phase of the same function.
contour(X,Y,(180/pi)*angle(H),-180:10:180); hold off
1.5
1
0.5
0
−0.5
−1
−1.5
−4
See Also
−3
−2
−1
0
1
2
besselj, bessely, besseli, besselk
2-159
besselh
References
2-160
[1] Abramowitz, M. and I. A. Stegun, Handbook of Mathematical Functions,
National Bureau of Standards, Applied Math. Series #55, Dover Publications,
1965.
besseli
Purpose
2besseli
Modified Bessel function of the first kind
Syntax
I = besseli(nu,Z)
I = besseli(nu,Z,1)
[I,ierr] = besseli(...)
Definitions
The differential equation
2
z2
d y
dy
+ z ------- – ( z 2 + ν 2 ) y = 0
dz
d z2
where ν is a real constant, is called the modified Bessel’s equation, and its
solutions are known as modified Bessel functions.
I ν ( z ) and I – ν ( z ) form a fundamental set of solutions of the modified Bessel’s
equation for noninteger ν . I ν ( z ) is defined by
ν
I ν ( z ) =  --z- 
2
∞
∑
k=0
2 k
z 
 ---- 4
---------------------------------------k! Γ ( ν + k + 1 )
where Γ(a) is the gamma function.
K ν ( z ) is a second solution, independent of I ν ( z ) . It can be computed using
besselk.
Description
I = besseli(nu,Z) computes the modified Bessel function of the first kind,
I ν ( z ) , for each element of the array Z. The order nu need not be an integer, but
must be real. The argument Z can be complex. The result is real where Z is
positive.
If nu and Z are arrays of the same size, the result is also that size. If either input
is a scalar, it is expanded to the other input's size. If one input is a row vector
and the other is a column vector, the result is a two-dimensional table of
function values.
I = besseli(nu,Z,1) computes besseli(nu,Z).*exp(-abs(real(Z))).
2-161
besseli
[I,ierr] = besseli(...) also returns completion flags in an array the same
size as I.
ierr
Description
0
besseli succesfully computed the modified Bessel function for
this element.
Examples
1
Illegal arguments.
2
Overflow. Returns Inf.
3
Some loss of accuracy in argument reduction.
4
Unacceptable loss of accuracy, Z or nu too large.
5
No convergence. Returns NaN.
Example 1.
format long
z = (0:0.2:1)';
besseli(1,z)
ans =
0
0.10050083402813
0.20402675573357
0.31370402560492
0.43286480262064
0.56515910399249
Example 2. besseli(3:9,(0:.2,10)',1) generates the entire table on
page 423 of [1] Abramowitz and Stegun, Handbook of Mathematical Functions.
Algorithm
The besseli functions uses a Fortran MEX-file to call a library developed by
D. E. Amos [3] [4].
See Also
airy, besselh, besselj, besselk, bessely
2-162
besseli
References
[1] Abramowitz, M. and I.A. Stegun, Handbook of Mathematical Functions,
National Bureau of Standards, Applied Math. Series #55, Dover Publications,
1965, sections 9.1.1, 9.1.89 and 9.12, formulas 9.1.10 and 9.2.5.
[2] Carrier, Krook, and Pearson, Functions of a Complex Variable: Theory and
Technique, Hod Books, 1983, section 5.5.
[3] Amos, D. E., “A Subroutine Package for Bessel Functions of a Complex
Argument and Nonnegative Order,” Sandia National Laboratory Report,
SAND85-1018, May, 1985.
[4] Amos, D. E., “A Portable Package for Bessel Functions of a Complex
Argument and Nonnegative Order,” Trans. Math. Software, 1986.
2-163
besselk
Purpose
2besselk
Modified Bessel function of the second kind
Syntax
K = besselk(nu,Z)
K = besselk(nu,Z,1)
[K,ierr] = besselk(...)
Definitions
The differential equation
2
z2
d y
dy
+ z ------- – ( z 2 + ν 2 ) y = 0
dz
d z2
where ν is a real constant, is called the modified Bessel’s equation, and its
solutions are known as modified Bessel functions.
A solution K ν ( z ) of the second kind can be expressed as
I –ν ( z ) – I ν ( z )
π
K ν ( z ) =  ---  -----------------------------------2
sin ( νπ )
where I ν ( z ) and I – ν ( z ) form a fundamental set of solutions of the modified
Bessel’s equation for noninteger ν
ν
I ν ( z ) =  --z- 
2
∞
∑
k=0
2 k
z 
 ---- 4
---------------------------------------k! Γ ( ν + k + 1 )
and Γ(a) is the gamma function. K ν ( z ) is independent of I ν ( z ) .
I ν ( z ) can be computed using besseli.
Description
K = besselk(nu,Z) computes the modified Bessel function of the second kind,
K ν ( z ) , for each element of the array Z. The order nu need not be an integer, but
must be real. The argument Z can be complex. The result is real where Z is
positive.
If nu and Z are arrays of the same size, the result is also that size. If either input
is a scalar, it is expanded to the other input's size. If one input is a row vector
and the other is a column vector, the result is a two-dimensional table of
function values.
2-164
besselk
K = besselk(nu,Z,1) computes besselk(nu,Z).*exp(Z).
[K,ierr] = besselk(...) also returns completion flags in an array the same
size as K.
ierr
Description
0
besselk succesfully computed the modified Bessel function for
this element.
Examples
1
Illegal arguments.
2
Overflow. Returns Inf.
3
Some loss of accuracy in argument reduction.
4
Unacceptable loss of accuracy, Z or nu too large.
5
No convergence. Returns NaN.
Example 1.
format long
z = (0:0.2:1)';
besselk(1,z)
ans =
Inf
4.77597254322047
2.18435442473269
1.30283493976350
0.86178163447218
0.60190723019723
Example 2. besselk(3:9,(0:.2:10)',1) generates part of the table on
page 424 of [1] Abramowitz and Stegun, Handbook of Mathematical Functions.
Algorithm
The besselk function uses a Fortran MEX-file to call a library developed by
D. E. Amos [3] [4].
2-165
besselk
See Also
airy, besselh, besseli, besselj, bessely
References
[1] Abramowitz, M. and I.A. Stegun, Handbook of Mathematical Functions,
National Bureau of Standards, Applied Math. Series #55, Dover Publications,
1965, sections 9.1.1, 9.1.89 and 9.12, formulas 9.1.10 and 9.2.5.
[2] Carrier, Krook, and Pearson, Functions of a Complex Variable: Theory and
Technique, Hod Books, 1983, section 5.5.
[3] Amos, D. E., “A Subroutine Package for Bessel Functions of a Complex
Argument and Nonnegative Order,” Sandia National Laboratory Report,
SAND85-1018, May, 1985.
[4] Amos, D. E., “A Portable Package for Bessel Functions of a Complex
Argument and Nonnegative Order,” Trans. Math. Software, 1986.
2-166
besselj
Purpose
2besselj
Bessel function of the first kind
Syntax
J = besselj(nu,Z)
J = besselj(nu,Z,1)
[J,ierr] = besselj(nu,Z)
Definition
The differential equation
z
2d
2
y
dz
2
dy
2
2
+ z ------- + ( z – ν ) y = 0
dz
where ν is a real constant, is called Bessel’s equation, and its solutions are
known as Bessel functions.
J ν ( z ) and J – ν ( z ) form a fundamental set of solutions of Bessel’s equation for
noninteger ν . J ν ( z ) is defined by
J ν ( z ) =  --z-
 2
ν
∞
∑
k=0
2 k
z 
 – ---- 4
---------------------------------------k! Γ ( ν + k + 1 )
where Γ(a) is the gamma function.
Y ν ( z ) is a second solution of Bessel’s equation that is linearly independent of
J ν ( z ) . It can be computed using bessely.
Description
J = besselj(nu,Z) computes the Bessel function of the first kind, J ν ( z ) , for
each element of the array Z. The order nu need not be an integer, but must be
real. The argument Z can be complex. The result is real where Z is positive.
If nu and Z are arrays of the same size, the result is also that size. If either input
is a scalar, it is expanded to the other input's size. If one input is a row vector
and the other is a column vector, the result is a two-dimensional table of
function values.
J = besselj(nu,Z,1) computes besselj(nu,Z).*exp(-abs(imag(Z))).
[J,ierr] = besselj(nu,Z) also returns completion flags in an array the
same size as J.
2-167
besselj
ierr
Description
0
besselj succesfully computed the Bessel function for this
element.
Remarks
1
Illegal arguments.
2
Overflow. Returns Inf.
3
Some loss of accuracy in argument reduction.
4
Unacceptable loss of accuracy, Z or nu too large.
5
No convergence. Returns NaN.
The Bessel functions are related to the Hankel functions, also called Bessel
functions of the third kind,
(1)
H ν ( z) = J ν( z) + i Y ν( z)
(2)
H ν ( z) = J ν( z) – i Y ν( z)
(K )
where H ν ( z ) is besselh, J ν ( z ) is besselj, and Y ν ( z ) is bessely. The
Hankel functions also form a fundamental set of solutions to Bessel’s equation
(see besselh).
Examples
Example 1.
format long
z = (0:0.2:1)';
besselj(1,z)
ans =
0
0.09950083263924
0.19602657795532
0.28670098806392
0.36884204609417
0.44005058574493
2-168
besselj
Example 2. besselj(3:9,(0:.2:10)') generates the entire table on page 398
of [1] Abramowitz and Stegun, Handbook of Mathematical Functions.
Algorithm
The besselj function uses a Fortran MEX-file to call a library developed by
D. E. Amos [3] [4].
See Also
besselh, besseli, besselk, bessely
References
[1] Abramowitz, M. and I.A. Stegun, Handbook of Mathematical Functions,
National Bureau of Standards, Applied Math. Series #55, Dover Publications,
1965, sections 9.1.1, 9.1.89 and 9.12, formulas 9.1.10 and 9.2.5.
[2] Carrier, Krook, and Pearson, Functions of a Complex Variable: Theory and
Technique, Hod Books, 1983, section 5.5.
[3] Amos, D. E., “A Subroutine Package for Bessel Functions of a Complex
Argument and Nonnegative Order,” Sandia National Laboratory Report,
SAND85-1018, May, 1985.
[4] Amos, D. E., “A Portable Package for Bessel Functions of a Complex
Argument and Nonnegative Order,” Trans. Math. Software, 1986.
2-169
bessely
Purpose
2bessely
Bessel functions of the second kind
Syntax
Y = bessely(nu,Z)
Y = bessely(nu,Z,1)
[Y,ierr] = bessely(nu,Z)
Definition
The differential equation
z
2d
2
y
dz
2
dy
2
2
+ z ------- + ( z – ν ) y = 0
dz
where ν is a real constant, is called Bessel’s equation, and its solutions are
known as Bessel functions.
A solution Y ν ( z ) of the second kind can be expressed as
J ν ( z ) cos ( νπ ) – J – ν ( z )
Y ν ( z ) = ----------------------------------------------------------sin ( νπ )
where J ν ( z ) and J – ν ( z ) form a fundamental set of solutions of Bessel’s
equation for noninteger ν
J ν ( z ) =  --z-
 2
ν
∞
∑
k=0
2 k
z 
 – ---- 4
---------------------------------------k! Γ ( ν + k + 1 )
and Γ(a) is the gamma function. Y ν ( z ) is linearly independent of J ν ( z )
J ν ( z ) can be computed using besselj.
Description
Y = bessely(nu,Z) computes Bessel functions of the second kind, Y ν ( z ) , for
each element of the array Z. The order nu need not be an integer, but must be
real. The argument Z can be complex. The result is real where Z is positive.
If nu and Z are arrays of the same size, the result is also that size. If either input
is a scalar, it is expanded to the other input's size. If one input is a row vector
and the other is a column vector, the result is a two-dimensional table of
function values.
Y = bessely(nu,Z,1) computes bessely(nu,Z).*exp(-abs(imag(Z))).
2-170
bessely
[Y,ierr] = bessely(nu,Z) also returns completion flags in an array the
same size as Y.
ierr
Description
0
bessely succesfully computed the Bessel function for this
element.
Remarks
1
Illegal arguments.
2
Overflow. Returns Inf.
3
Some loss of accuracy in argument reduction.
4
Unacceptable loss of accuracy, Z or nu too large.
5
No convergence. Returns NaN.
The Bessel functions are related to the Hankel functions, also called Bessel
functions of the third kind,
(1)
H ν ( z) = J ν( z) + i Y ν( z)
(2)
H ν ( z) = J ν( z) – i Y ν( z)
(K )
where H ν ( z ) is besselh, J ν ( z ) is besselj, and Y ν ( z ) is bessely. The
Hankel functions also form a fundamental set of solutions to Bessel’s equation
(see besselh).
Examples
Example 1.
format long
z = (0:0.2:1)';
bessely(1,z)
ans =
-Inf
-3.32382498811185
-1.78087204427005
2-171
bessely
-1.26039134717739
-0.97814417668336
-0.78121282130029
Example 2. bessely(3:9,(0:.2:10)') generates the entire table on page 399
of [1] Abramowitz and Stegun, Handbook of Mathematical Functions.
Algorithm
The bessely function uses a Fortran MEX-file to call a library developed by
D. E Amos [3] [4].
See Also
besselh, besseli, besselj, besselk
References
[1] Abramowitz, M. and I.A. Stegun, Handbook of Mathematical Functions,
National Bureau of Standards, Applied Math. Series #55, Dover Publications,
1965, sections 9.1.1, 9.1.89 and 9.12, formulas 9.1.10 and 9.2.5.
[2] Carrier, Krook, and Pearson, Functions of a Complex Variable: Theory and
Technique, Hod Books, 1983, section 5.5.
[3] Amos, D. E., “A Subroutine Package for Bessel Functions of a Complex
Argument and Nonnegative Order,” Sandia National Laboratory Report,
SAND85-1018, May, 1985.
[4] Amos, D. E., “A Portable Package for Bessel Functions of a Complex
Argument and Nonnegative Order,” Trans. Math. Software, 1986.
2-172
beta
Purpose
2beta
Beta function
Syntax
B = beta(Z,W)
Definition
The beta function is
B ( z, w ) =
1
∫0 t z – 1 ( 1 – t ) w – 1 dt
Γ ( z )Γ ( w )
= ------------------------Γ( z + w)
where Γ ( z ) is the gamma function.
Description
B = beta(Z,W) computes the beta function for corresponding elements of
arrays Z and W. The arrays must be real and nonnegative. They must be the
same size, or either can be scalar.
Examples
In this example, which uses integer arguments,
beta(n,3)
= (n-1)!*2!/(n+2)!
= 2/(n*(n+1)*(n+2))
is the ratio of fairly small integers, and the rational format is able to recover
the exact result.
format rat
beta((0:10)',3)
ans =
1/0
1/3
1/12
1/30
1/60
1/105
1/168
1/252
1/360
1/495
1/660
2-173
beta
Algorithm
See Also
2-174
beta(z,w) = exp(gammaln(z)+gammaln(w)-gammaln(z+w))
betainc, betaln, gammaln
betainc
Purpose
2betainc
Incomplete beta function
Syntax
I = betainc(X,Z,W)
Definition
The incomplete beta function is
1
I x ( z, w ) = -------------------B ( z, w )
x
∫0 t z – 1 ( 1 – t ) w – 1 dt
where B ( z, w ) , the beta function, is defined as
B ( z, w ) =
1
∫0 t z – 1 ( 1 – t ) w – 1 dt
Γ ( z )Γ ( w )
= ------------------------Γ( z + w)
and Γ ( z ) is the gamma function.
Description
I = betainc(X,Z,W) computes the incomplete beta function for corresponding
elements of the arrays X, Z and W. The elements of X must be in the closed
interval [0,1] . The arrays Z and W must be nonnegative and real. All arrays
must be the same size, or any of them can be scalar.
Examples
format long
betainc(.5,(0:10)',3)
ans =
1.00000000000000
0.87500000000000
0.68750000000000
0.50000000000000
0.34375000000000
0.22656250000000
0.14453125000000
0.08984375000000
0.05468750000000
0.03271484375000
0.01928710937500
See Also
beta, betaln
2-175
betaln
Purpose
2betaln
Logarithm of beta function
Syntax
L = betaln(Z,W)
Description
L = betaln(Z,W) computes the natural logarithm of the beta function
log(beta(Z,W)), for corresponding elements of arrays Z and W, without
computing beta(Z,W). Since the beta function can range over very large or very
small values, its logarithm is sometimes more useful.
Z and W must be real and nonnegative. They must be the same size, or either
can be scalar.
Examples
x = 510
betaln(x,x)
ans =
-708.8616
-708.8616 is slightly less than log(realmin). Computing beta(x,x) directly
would underflow (or be denormal).
Algorithm
See Also
2-176
betaln(z,w) = gammaln(z)+gammaln(w)-gammaln(z+w)
beta, betainc, gammaln
bicg
Purpose
2bicg
BiConjugate Gradients method
Syntax
x = bicg(A,b)
bicg(A,b,tol)
bicg(A,b,tol,maxit)
bicg(A,b,tol,maxit,M)
bicg(A,b,tol,maxit,M1,M2)
bicg(A,b,tol,maxit,M1,M2,x0)
bicg(afun,b,tol,maxit,mfun1,mfun2,x0,p1,p2,...)
[x,flag] = bicg(A,b,...)
[x,flag,relres] = bicg(A,b,...)
[x,flag,relres,iter] = bicg(A,b,...)
[x,flag,relres,iter,resvec] = bicg(A,b,...)
Description
x = bicg(A,b) attempts to solve the system of linear equations A*x = b for x.
The n-by-n coefficient matrix A must be square and should be large and sparse.
The column vector b must have length n. A can be a function afun such that
afun(x) returns A*x and afun(x,'transp') returns A'*x.
If bicg converges, it displays a message to that effect. If bicg fails to converge
after the maximum number of iterations or halts for any reason, it prints a
warning message that includes the relative residual norm(b-A*x)/norm(b)
and the iteration number at which the method stopped or failed.
bicg(A,b,tol) specifies the tolerance of the method. If tol is [], then bicg
uses the default, 1e-6.
bicg(A,b,tol,maxit) specifies the maximum number of iterations. If maxit
is [], then bicg uses the default, min(n,20).
bicg(A,b,tol,maxit,M) and bicg(A,b,tol,maxit,M1,M2) use the
preconditioner M or M = M1*M2 and effectively solve the system
inv(M)*A*x = inv(M)*b for x. If M is [] then bicg applies no preconditioner.
M can be a function mfun such that mfun(x) returns M\x and mfun(x,'transp')
returns M'\x.
bicg(A,b,tol,maxit,M1,M2,x0) specifies the initial guess. If x0 is [], then
bicg uses the default, an all-zero vector.
2-177
bicg
bicg(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...) passes parameters
p1,p2,... to functions afun(x,p1,p2,...) and
afun(x,p1,p2,...,'transp'), and similarly to the preconditioner functions
m1fun and m2fun.
[x,flag] = bicg(A,b,...) also returns a convergence flag.
Flag
Convergence
0
bicg converged to the desired tolerance tol within maxit
iterations.
1
bicg iterated maxit times but did not converge.
2
Preconditioner M was ill-conditioned.
3
bicg stagnated. (Two consecutive iterates were the same.)
4
One of the scalar quantities calculated during bicg became
too small or too large to continue computing.
Whenever flag is not 0, the solution x returned is that with minimal norm
residual computed over all the iterations. No messages are displayed if the
flag output is specified.
[x,flag,relres] = bicg(A,b,...) also returns the relative residual
norm(b-A*x)/norm(b). If flag is 0, relres <= tol.
[x,flag,relres,iter] = bicg(A,b,...) also returns the iteration number
at which x was computed, where 0 <= iter <= maxit.
[x,flag,relres,iter,resvec] = bicg(A,b,...) also returns a vector of the
residual norms at each iteration including norm(b-A*x0).
Examples
Example 1.
n = 100;
on = ones(n,1);
A = spdiags([-2*on 4*on -on],-1:1,n,n);
b = sum(A,2);
tol = 1e-8;
2-178
bicg
maxit = 15;
M1 = spdiags([on/(-2) on],-1:0,n,n);
M2 = spdiags([4*on -on],0:1,n,n);
x = bicg(A,b,tol,maxit,M1,M2,[]);
displays this message
bicg converged at iteration 9 to a solution with relative
residual 5.3e-009
Alternatively, use this matrix-vector product function
function y = afun(x,n,transp_flag)
if (nargin > 2) & strcmp(transp_flag,'transp')
y = 4 * x;
y(1:n-1) = y(1:n-1) - 2 * x(2:n);
y(2:n) = y(2:n) - x(1:n-1);
else
y = 4 * x;
y(2:n) = y(2:n) - 2 * x(1:n-1);
y(1:n-1) = y(1:n-1) - x(2:n);
end
as input to bicg.
x1 = bicg(@afun,b,tol,maxit,M1,M2,[],n);
Example 2. This examples demonstrates the use of a preconditioner. Start
with A = west0479, a real 479-by-479 sparse matrix, and define b so that the
true solution is a vector of all ones.
load west0479;
A = west0479;
b = sum(A,2);
You can accurately solve A*x = b using backslash since A is not so large.
x = A \ b;
norm(b-A*x) / norm(b)
ans =
8.3154e-017
2-179
bicg
Now try to solve A*x = b with bicg.
[x,flag,relres,iter,resvec] = bicg(A,b)
flag =
1
relres =
1
iter =
0
The value of flag indicates that bicg iterated the default 20 times without
converging. The value of iter shows that the method behaved so badly that the
initial all-zero guess was better than all the subsequent iterates. The value of
relres supports this: relres = norm(b-A*x)/norm(b) = norm(b)/norm(b) = 1.
You can confirm that the unpreconditioned method oscillates rather wildly by
plotting the relative residuals at each iteration.
semilogy(0:20,resvec/norm(b),'-o')
xlabel('Iteration Number')
ylabel('Relative Residual')
5
10
4
Relative Residual
10
3
10
2
10
1
10
0
10
2-180
0
5
10
Iteration Number
15
20
bicg
Now, try an incomplete LU factorization with a drop tolerance of 1e-5 for the
preconditioner.
[L1,U1] = luinc(A,1e-5);
Warning: Incomplete upper triangular factor has 1 zero diagonal.
It cannot be used as a preconditioner for an iterative
method.
nnz(A), nnz(L1), nnz(U1)
ans =
1887
ans =
5562
ans =
4320
The zero on the main diagonal of the upper triangular U1 indicates that U1 is
singular. If you try to use it as a preconditioner,
[x,flag,relres,iter,resvec] = bicg(A,b,1e-6,20,L1,U1)
flag =
2
relres =
1
iter =
0
resvec =
7.0557e+005
the method fails in the very first iteration when it tries to solve a system of
equations involving the singular U1 using backslash. bicg is forced to return
the initial estimate since no other iterates were produced.
Try again with a slightly less sparse preconditioner.
[L2,U2] = luinc(A,1e-6);
2-181
bicg
nnz(L2), nnz(U2)
ans =
6231
ans =
4559
This time U2 is nonsingular and may be an appropriate preconditioner.
[x,flag,relres,iter,resvec] = bicg(A,b,1e-15,10,L2,U2)
flag =
0
relres =
2.8664e-016
iter =
8
and bicg converges to within the desired tolerance at iteration number 8.
Decreasing the value of the drop tolerance increases the fill-in of the
incomplete factors but also increases the accuracy of the approximation to the
original matrix. Thus, the preconditioned system becomes closer to
inv(U)*inv(L)*L*U*x = inv(U)*inv(L)*b, where L and U are the true LU
factors, and closer to being solved within a single iteration.
The next graph shows the progress of bicg using six different incomplete LU
factors as preconditioners. Each line in the graph is labeled with the drop
tolerance of the preconditioner used in bicg.
2-182
bicg
0
10
−5
relative residual
10
−10
10
−15
10
1e−12
1e−10
1e−6
1e−8
1e−14
0
See Also
1
2
3
4
5
iteration number
6
7
8
bicgstab, cgs, gmres, lsqr, luinc, minres, pcg, qmr, symmlq
@ (function handle), \ (backslash)
References
[1] Barrett, R., M. Berry, T. F. Chan, et al., Templates for the Solution of Linear
Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia, 1994.
2-183
bicgstab
Purpose
2bicgstab
BiConjugate Gradients Stabilized method
Syntax
x = bicgstab(A,b)
bicgstab(A,b,tol)
bicgstab(A,b,tol,maxit)
bicgstab(A,b,tol,maxit,M)
bicgstab(A,b,tol,maxit,M1,M2)
bicgstab(A,b,tol,maxit,M1,M2,x0)
bicgstab(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...)
[x,flag] = bicgstab(A,b,...)
[x,flag,relres] = bicgstab(A,b,...)
[x,flag,relres,iter] = bicgstab(A,b,...)
[x,flag,relres,iter,resvec] = bicgstab(A,b,...)
Description
x = bicgstab(A,b) attempts to solve the system of linear equations A*x=b for
x. The n-by-n coefficient matrix A must be square and should be large and
sparse. The column vector b must have length n. A can be a function afun such
that afun(x) returns A*x.
If bicgstab converges, a message to that effect is displayed. If bicgstab fails
to converge after the maximum number of iterations or halts for any reason, a
warning message is printed displaying the relative residual
norm(b-A*x)/norm(b) and the iteration number at which the method stopped
or failed.
bicgstab(A,b,tol) specifies the tolerance of the method. If tol is [], then
bicgstab uses the default, 1e-6.
bicgstab(A,b,tol,maxit) specifies the maximum number of iterations. If
maxit is [], then bicgstab uses the default, min(n,20).
bicgstab(A,b,tol,maxit,M) and bicgstab(A,b,tol,maxit,M1,M2) use
preconditioner M or M = M1*M2 and effectively solve the system
inv(M)*A*x = inv(M)*b for x. If M is [] then bicgstab applies no
preconditioner. M can be a function that returns M\x.
bicgstab(A,b,tol,maxit,M1,M2,x0) specifies the initial guess. If x0 is [],
then bicgstab uses the default, an all zero vector.
2-184
bicgstab
bicgstab(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...) passes
parameters p1,p2,... to functions afun(x,p1,p2,...), m1fun(x,p1,p2,...),
and m2fun(x,p1,p2,...).
[x,flag] = bicgstab(A,b,...) also returns a convergence flag.
Flag
Convergence
0
bicgstab converged to the desired tolerance tol within
maxit iterations.
1
bicgstab iterated maxit times but did not converge.
2
Preconditioner M was ill-conditioned.
3
bicgstab stagnated. (Two consecutive iterates were the
same.)
4
One of the scalar quantities calculated during bicgstab
became too small or too large to continue computing.
Whenever flag is not 0, the solution x returned is that with minimal norm
residual computed over all the iterations. No messages are displayed if the
flag output is specified.
[x,flag,relres] = bicgstab(A,b,...) also returns the relative residual
norm(b-A*x)/norm(b). If flag is 0, relres <= tol.
[x,flag,relres,iter] = bicgstab(A,b,...) also returns the iteration
number at which x was computed, where 0 <= iter <= maxit. iter can be an
integer + 0.5, indicating convergence half way through an iteration.
[x,flag,relres,iter,resvec] = bicgstab(A,b,...) also returns a vector
of the residual norms at each half iteration, including norm(b-A*x0).
Example
Example 1. This example first solves Ax = b by providing A and the
preconditioner M1 directly as arguments. It then solves the same system using
functions that return A and the preconditioner.
A = gallery('wilk',21);
b = sum(A,2);
2-185
bicgstab
tol = 1e-12;
maxit = 15;
M1 = diag([10:-1:1 1 1:10]);
x = bicgstab(A,b,tol,maxit,M1,[],[]);
displays this message
bicgstab converged at iteration 12.5 to a solution with relative
residual 2.9e-014
Alternatively, use this matrix-vector product function
function y = afun(x,n)
y = [0;
x(1:n-1)] + [((n-1)/2:-1:0)';
(1:(n-1)/2)'] .*x + [x(2:n);
0];
and this preconditioner backsolve function
function y = mfun(r,n)
y = r ./ [((n-1)/2:-1:1)'; 1; (1:(n-1)/2)'];
as inputs to bicgstab
x1 = bicgstab(@afun,b,tol,maxit,@mfun,[],[],21);
Note that both afun and mfun must accept bicgstab's extra input n=21.
Example 2. This examples demonstrates the use of a preconditioner. Start
with A = west0479, a real 479-by-479 sparse matrix, and define b so that the
true solution is a vector of all ones.
load west0479;
A = west0479;
b = sum(A,2);
[x,flag] = bicgstab(A,b)
flag is 1 because bicgstab does not converge to the default tolerance 1e-6
within the default 20 iterations.
[L1,U1] = luinc(A,1e-5);
[x1,flag1] = bicgstab(A,b,1e-6,20,L1,U1)
2-186
bicgstab
flag1 is 2 because the upper triangular U1 has a zero on its diagonal. This
causes bicgstab to fail in the first iteration when it tries to solve a system such
as U1*y = r using backslash.
[L2,U2] = luinc(A,1e-6);
[x2,flag2,relres2,iter2,resvec2] = bicgstab(A,b,1e-15,10,L2,U2)
flag2 is 0 because bicgstab converges to the tolerance of 3.1757e-016 (the
value of relres2) at the sixth iteration (the value of iter2) when
preconditioned by the incomplete LU factorization with a drop tolerance of
1e-6. resvec2(1) = norm(b) and resvec2(13) = norm(b-A*x2). You can
follow the progress of bicgstab by plotting the relative residuals at the halfway
point and end of each iteration starting from the initial estimate (iterate
number 0).
semilogy(0:0.5:iter2,resvec2/norm(b),'-o')
xlabel('iteration number')
ylabel('relative residual')
0
10
−2
10
−4
10
−6
relative residual
10
−8
10
−10
10
−12
10
−14
10
−16
10
0
1
2
3
iteration number
4
5
6
2-187
bicgstab
See Also
bicg, cgs, gmres, lsqr, luinc, minres, pcg, qmr, symmlq
@ (function handle), \ (backslash)
References
[1] Barrett, R., M. Berry, T. F. Chan, et al., Templates for the Solution of Linear
Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia, 1994.
[2] van der Vorst, H. A., “BI-CGSTAB: A fast and smoothly converging variant
of BI-CG for the solution of nonsymmetric linear systems”, SIAM J. Sci. Stat.
Comput., March 1992,Vol. 13, No. 2, pp. 631-644.
2-188
bin2dec
Purpose
2bin2dec
Binary to decimal number conversion
Syntax
bin2dec(binarystr)
Description
bin2dec(binarystr) interprets the binary string binarystr and returns the
equivalent decimal number.
Examples
bin2dec('010111') returns 23.
See Also
dec2bin
2-189
bitand
Purpose
2bitand
Bit-wise AND
Syntax
C = bitand(A,B)
Description
C = bitand(A,B) returns the bit-wise AND of two nonnegative integer
arguments A and B. To ensure the operands are integers, use the ceil, fix,
floor, and round functions.
Examples
The five-bit binary representations of the integers 13 and 27 are 01101 and
11011, respectively. Performing a bit-wise AND on these numbers yields
01001, or 9.
C = bitand(13,27)
C =
9
See Also
2-190
bitcmp, bitget, bitmax, bitor, bitset, bitshift, bitxor
bitcmp
Purpose
2bitcmp
Complement bits
Syntax
C = bitcmp(A,n)
Description
C = bitcmp(A,n) returns the bit-wise complement of A as an n-bit
floating-point integer (flint).
Example
With eight-bit arithmetic, the ones’ complement of 01100011 (99, decimal) is
10011100 (156, decimal).
C = bitcmp(99,8)
C =
156
See Also
bitand, bitget, bitmax, bitor, bitset, bitshift, bitxor
2-191
bitget
Purpose
2bitget
Get bit
Syntax
C = bitget(A,bit)
Description
C = bitget(A,bit) returns the value of the bit at position bit in A. Operand
A must be a nonnegative integer, and bit must be a number between 1 and the
number of bits in the floating-point integer (flint) representation of A (52 for
IEEE flints). To ensure the operand is an integer, use the ceil, fix, floor, and
round functions.
Example
The dec2bin function converts decimal numbers to binary. However, you can
also use the bitget function to show the binary representation of a decimal
number. Just test successive bits from most to least significant:
disp(dec2bin(13))
1101
C = bitget(13,4:-1:1)
C =
1
See Also
2-192
1
0
1
bitand, bitcmp, bitmax, bitor, bitset, bitshift, bitxor
bitmax
Purpose
2bitmax
Maximum floating-point integer
Syntax
bitmax
Description
bitmax returns the maximum unsigned floating-point integer for your
computer. It is the value when all bits are set, namely the value 2
See Also
53
– 1.
bitand, bitcmp, bitget, bitor, bitset, bitshift, bitxor
2-193
bitor
Purpose
2bitor
Bit-wise OR
Syntax
C = bitor(A,B)
Description
C = bitor(A,B) returns the bit-wise OR of two nonnegative integer
arguments A and B. To ensure the operands are integers, use the ceil, fix,
floor, and round functions.
Examples
The five-bit binary representations of the integers 13 and 27 are 01101 and
11011, respectively. Performing a bit-wise OR on these numbers yields 11111,
or 31.
C = bitor(13,27)
C =
31
See Also
2-194
bitand, bitcmp, bitget, bitmax, bitset, bitshift, bitxor
bitset
Purpose
2bitset
Set bit
Syntax
C = bitset(A,bit)
C = bitset(A,bit,v)
Description
C = bitset(A,bit) sets bit position bit in A to 1 (on). A must be a nonnegative
integer and bit must be a number between 1 and the number of bits in the
floating-point integer (flint) representation of A (52 for IEEE flints). To ensure
the operand is an integer, use the ceil, fix, floor, and round functions.
C = bitset(A,bit,v) sets the bit at position bit to the value v, which must be
either 0 or 1.
Examples
Setting the fifth bit in the five-bit binary representation of the integer 9 (01001)
yields 11001, or 25.
C = bitset(9,5)
C =
25
See Also
bitand, bitcmp, bitget, bitmax, bitor, bitshift, bitxor
2-195
bitshift
Purpose
2bitshift
Bit-wise shift
Syntax
C = bitshift(A,k,n)
C = bitshift(A,k)
Description
C = bitshift(A,k,n) returns the value of A shifted by k bits. If k>0, this is
same as a multiplication by 2k (left shift). If k<0, this is the same as a division
by 2k (right shift). An equivalent computation for this function is
C = fix(A*2^k).
If the shift causes C to overflow n bits, the overflowing bits are dropped. A must
contain nonnegative integers between 0 and BITMAX, which you can ensure by
using the ceil, fix, floor, and round functions.
C = bitshift(A,k) uses the default value of n = 53.
Examples
Shifting 1100 (12, decimal) to the left two bits yields 110000 (48, decimal).
C = bitshift(12,2)
C =
48
See Also
2-196
bitand, bitcmp, bitget, bitmax, bitor, bitset, bitxor, fix
bitxor
Purpose
2bitxor
Bit-wise XOR
Syntax
C = bitxor(A,B)
Description
C = bitxor(A,B) returns the bit-wise XOR of the two arguments A and B. Both
A and B must be integers. You can ensure this by using the ceil, fix, floor,
and round functions.
Examples
The five-bit binary representations of the integers 13 and 27 are 01101 and
11011, respectively. Performing a bit-wise XOR on these numbers yields 10110,
or 22.
C = bitxor(13,27)
C =
22
See Also
bitand, bitcmp, bitget, bitmax, bitor, bitset, bitshift
2-197
blanks
Purpose
2blanks
A string of blanks
Syntax
blanks(n)
Description
blanks(n) is a string of n blanks.
Examples
blanks is useful with the display function. For example,
disp(['xxx' blanks(20) 'yyy'])
displays twenty blanks between the strings 'xxx' and 'yyy'.
disp(blanks(n)') moves the cursor down n lines.
See Also
2-198
clc, format, home
blkdiag
Purpose
2blkdiag
Construct a block diagonal matrix from input arguments
Syntax
out = blkdiag(a,b,c,d,...)
Description
out = blkdiag(a,b,c,d,...) , where a, b, c, d, ... are matrices, outputs a
block diagonal matrix of the form
a
0
0
0
0
0
b
0
0
0
0
0
c
0
0
0
0
0
d
0
0
0
0
0
…
The input matrices do not have to be square, nor do they have to be of equal
size.
Note blkdiag works not only for matrices, but for any MATLAB objects that
support horzcat and vertcat operations.
See Also
diag, horzcat, vertcat
2-199
box
Purpose
2box
Display axes border
Syntax
box on
box off
box
box(axes_handle,...)
Description
box on displays the boundary of the current axes.
box off does not display the boundary of the current axes.
box toggles the visible state of the current axes’ boundary.
box(axes_handle,...) uses the axes specified by axes_handle instead of the
current axes.
Algorithm
The box function sets the axes Box property to on or off.
See Also
axes, grid
“Axes Operations” for related functions
2-200
break
Purpose
2break
Terminate execution of a for loop or while loop
Syntax
break
Description
break terminates the execution of a for or while loop. Statements in the loop
that appear after the break statement, are not executed.
In nested loops, break exits only from the loop in which it occurs. Control
passes to the statement that follows the end of that loop.
Remarks
break is not defined outside of a for or while loop. Use return in this context
instead.
Examples
The example below shows a while loop that reads the contents of the file fft.m
into a MATLAB character array. A break statement is used to exit the while
loop when the first empty line is encountered. The resulting character array
contains the M-file help for the fft program.
fid = fopen('fft.m','r');
s = '';
while ~feof(fid)
line = fgetl(fid);
if isempty(line), break, end
s = strvcat(s,line);
end
disp(s)
See Also
for, while, end, continue, return
2-201
brighten
Purpose
Syntax
Description
2brighten
Brighten or darken colormap
brighten(beta)
brighten(h,beta)
newmap = brighten(beta)
newmap = brighten(cmap,beta)
brighten increases or decreases the color intensities in a colormap. The
modified colormap is brighter if 0 < beta < 1 and darker if –1 < beta < 0.
brighten(beta) replaces the current colormap with a brighter or darker
colormap of essentially the same colors. brighten(beta), followed by
brighten(–beta), where beta < 1, restores the original map.
brighten(h,beta) brightens all objects that are children of the figure having
the handle h.
newmap = brighten(beta) returns a brighter or darker version of the current
colormap without changing the display.
newmap = brighten(cmap,beta) returns a brighter or darker version of the
colormap cmap without changing the display.
Examples
Brighten and then darken the current colormap:
beta = .5; brighten(beta);
beta = —.5; brighten(beta);
Algorithm
The values in the colormap are raised to the power of gamma, where gamma is
 1 – β,
γ=  1
------------1 + β,
β>0
β≤0
brighten has no effect on graphics objects defined with true color.
See Also
colormap, rgbplot
“Color Operations” for related functions
2-202
brighten
Altering Colormaps for more information
2-203
builtin
Purpose
2builtin
Execute builtin function from overloaded method
Syntax
builtin(function,x1,...,xn)
[y1,..,yn] = builtin(function,x1,...,xn)
Description
builtin is used in methods that overload builtin functions to execute the
original builtin function. If function is a string containing the name of a
builtin function, then
builtin(function,x1,...,xn) evaluates that function at the given
arguments.
[y1,..,yn] = builtin(function,x1,...,xn) returns multiple output
arguments.
Remarks
builtin(...) is the same as feval(...) except that it calls the original builtin
version of the function even if an overloaded one exists. (For this to work you
must never overload builtin.)
See Also
feval
2-204
bvp4c
Purpose
2bvp4c
Solve two-point boundary value problems (BVPs) for ordinary differential
equations
Syntax
sol = bvp4c(odefun,bcfun,solinit)
sol = bvp4c(odefun,bcfun,solinit,options)
sol = bvp4c(odefun,bcfun,solinit,options,p1,p2...)
Arguments
odefun
A function that evaluates the differential equations f ( x, y ) . It can
have the form
dydx
dydx
dydx
dydx
=
=
=
=
odefun(x,y)
odefun(x,y,p1,p2,...)
odefun(x,y,parameters)
odefun(x,y,parameters,p1,p2,...)
where x is a scalar corresponding to x , and y is a column vector
corresponding to y . parameters is a vector of unknown
parameters, and p1,p2,... are known parameters. The output
dydx is a column vector.
bcfun
A function that computes the residual in the boundary conditions
bc ( y ( a ), y ( b ) ) . It can have the form
res
res
res
res
=
=
=
=
bcfun(ya,yb)
bcfun(ya,yb,p1,p2,...)
bcfun(ya,yb,parameters)
bcfun(ya,yb,parameters,p1,p2,...)
where ya and yb are column vectors corresponding to y ( a ) and
y ( b ) . parameters is a vector of unknown parameters, and
p1,p2,... are known parameters. The output res is a column
vector.
solinit
A structure with fields:
x
Ordered nodes of the initial mesh. Boundary
conditions are imposed at a = solinit.x(1) and
b = solinit.x(end).
y
Initial guess for the solution such that
solinit.y(:,i) is a guess for the solution at the
node solinit.x(i).
2-205
bvp4c
parameters
Optional. A vector that provides an initial guess for
unknown parameters.
The structure can have any name, but the fields must be named x,
y, and parameters. You can form solinit with the helper function
bvpinit. See bvpinit for details.
options
Optional integration argument. A structure you create using the
bvpset function. See bvpset for details.
p1,p2... Optional. Known parameters that the solver passes to odefun,
bcfun, and all the functions specified in options.
Description
sol = bvp4c(odefun,bcfun,solinit) integrates a system of ordinary
differential equations of the form
y′ = f ( x, y )
on the interval [a,b] subject to general two-point boundary conditions
bc ( y ( a ), y ( b ) ) = 0
The bvp4c solver can also find unknown parameters p for problems of the form
y′ = f ( x, y, p )
bc ( y ( a ), y ( b ), p ) = 0
where p corresponds to parameters. You provide bvp4c an initial guess for any
unknown parameters in solinit.parameters. The bvp4c solver returns the
final values of these unknown parameters in sol.parameters.
bvp4c produces a solution that is continuous on [a,b] and has a continuous first
derivative there. Use the function deval and the output sol of bvp4c to
evaluate the solution at specific points xint in the interval [a,b].
sxint = deval(sol,xint)
The structure sol returned by bvp4c has the following fields:
2-206
sol.x
Mesh selected by bvp4c
sol.y
Approximation to y ( x ) at the mesh points of sol.x
sol.yp
Approximation to y′ ( x ) at the mesh points of sol.x
bvp4c
sol.parameters
Values returned by bvp4c for the unknown parameters,
if any
sol.solver
'bvp4c'
The structure sol can have any name, and bvp4c creates the fields x, y, yp,
parameters, and solver.
sol = bvp4c(odefun,bcfun,solinit,options) solves as above with default
integration properties replaced by the values in options, a structure created
with the bvpset function. See bvpset for details.
sol = bvp4c(odefun,bcfun,solinit,options,p1,p2...) passes constant
known parameters, p1, p2, ..., to odefun, bcfun, and all the functions the user
specifies in options. Use options = [] as a placeholder if no options are set.
Examples
Example 1. Boundary value problems can have multiple solutions and one
purpose of the initial guess is to indicate which solution you want. The second
order differential equation
y′′ + y = 0
has exactly two solutions that satisfy the boundary conditions
y(0) = 0
y ( 4 ) = –2
Prior to solving this problem with bvp4c, you must write the differential
equation as a system of two first order ODEs
y1 ′ = y2
y2 ′ = – y1
Here y 1 = y and y 2 = y′ . This system has the required form
y′ = f ( x, y )
bc ( y ( a ), y ( b ) ) = 0
The function f and the boundary conditions bc are coded in MATLAB as
functions twoode and twobc.
2-207
bvp4c
function dydx = twoode(x,y)
dydx = [ y(2)
-abs(y(1))];
function res = twobc(ya,yb)
res = [ ya(1)
yb(1) + 2];
Form a guess structure consisting of an initial mesh of five equally spaced
points in [0,4] and a guess of constant values y 1( x) ≡ 1 and y 2( x) ≡ 0 with the
command
solinit = bvpinit(linspace(0,4,5),[1 0]);
Now solve the problem with
sol = bvp4c(@twoode,@twobc,solinit);
Evaluate the numerical solution at 100 equally spaced points and plot y ( x )
with
x = linspace(0,4);
y = deval(sol,x);
plot(x,y(1,:));
2.5
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
0
2-208
0.5
1
1.5
2
2.5
3
3.5
4
bvp4c
You can obtain the other solution of this problem with the initial guess
solinit = bvpinit(linspace(0,4,5),[-1 0]);
2.5
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
0
0.5
1
1.5
2
2.5
3
3.5
4
Example 2. This boundary value problem involves an unknown parameter.
The task is to compute the fourth ( q = 5 ) eigenvalue λ of Mathieu's equation
y′′ + ( λ – 2 q cos 2x ) y = 0
Because the unknown parameter λ is present, this second order differential
equation is subject to three boundary conditions
y′ ( 0 ) = 0
y′ ( π ) = 0
y(0) = 1
It is convenient to use subfunctions to place all the functions required by bvp4c
in a single M-file.
function mat4bvp
lambda = 15;
solinit = bvpinit(linspace(0,pi,10),@mat4init,lambda);
sol = bvp4c(@mat4ode,@mat4bc,solinit);
2-209
bvp4c
fprintf('The fourth eigenvalue is approximately %7.3f.\n',...
sol.parameters)
xint = linspace(0,pi);
Sxint = deval(sol,xint);
plot(xint,Sxint(1,:))
axis([0 pi -1 1.1])
title('Eigenfunction of Mathieu''s equation.')
xlabel('x')
ylabel('solution y')
% -----------------------------------------------------------function dydx = mat4ode(x,y,lambda)
q = 5;
dydx = [ y(2)
-(lambda - 2*q*cos(2*x))*y(1) ];
% -----------------------------------------------------------function res = mat4bc(ya,yb,lambda)
res = [ ya(2)
yb(2)
ya(1)-1 ];
% -----------------------------------------------------------function yinit = mat4init(x)
yinit = [ cos(4*x)
-4*sin(4*x) ];
The differential equation (converted to a first order system) and the boundary
conditions are coded as subfunctions mat4ode and mat4bc, respectively.
Because unknown parameters are present, these functions must accept three
input arguments, even though some of the arguments are not used.
The guess structure solinit is formed with bvpinit. An initial guess for the
solution is supplied in the form of a function mat4init. We chose y = cos 4x
because it satisfies the boundary conditions and has the correct qualitative
behavior (the correct number of sign changes). In the call to bvpinit, the third
argument (lambda = 15) provides an initial guess for the unknown parameter
λ.
2-210
bvp4c
After the problem is solved with bvp4c, the field sol.parameters returns the
value λ = 17.097 , and the plot shows the eigenfunction associated with this
eigenvalue.
Eigenfunction of Mathieu’s equation.
1
0.8
0.6
solution y
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
0
Algorithms
0.5
1
1.5
x
2
2.5
3
bvp4c is a finite difference code that implements the three-stage Lobatto IIIa
formula. This is a collocation formula and the collocation polynomial provides
a C1-continuous solution that is fourth order accurate uniformly in [a,b]. Mesh
selection and error control are based on the residual of the continuous solution.
See Also
@ (function_handle), bvpget, bvpinit, bvpset, deval
References
[1] Shampine, L.F., M.W. Reichelt, and J. Kierzenka, “Solving Boundary Value
Problems for Ordinary Differential Equations in MATLAB with bvp4c,”
available at ftp://ftp.mathworks.com/pub/doc/papers/bvp/.
2-211
bvpget
Purpose
2bvpget
Extract properties from the options structure created with bvpset
Syntax
val = bvpget(options,'name')
val = bvpget(options,'name',default)
Description
val = bvpget(options,'name') extracts the value of the named property
from the structure options, returning an empty matrix if the property value is
not specified in options. It is sufficient to type only the leading characters that
uniquely identify the property. Case is ignored for property names. [] is a valid
options argument.
val = bvpget(options,'name',default) extracts the named property as
above, but returns val = default if the named property is not specified in
options. For example,
val = bvpget(opts,'RelTol',1e-4);
returns val = 1e-4 if the RelTol is not specified in opts.
See Also
2-212
bvp4c, bvpinit, bvpset, deval
bvpinit
Purpose
Syntax
Description
2bvpinit
Form the initial guess for bvp4c
solinit
solinit
solinit
solinit
=
=
=
=
bvpinit(x,v)
bvpinit(x,v,parameters)
bvpinit(sol,[anew bnew])
bvpinit(sol,[anew bnew],parameters)
solinit = bvpinit(x,v) forms the initial guess for bvp4c in common
circumstances.
x is a vector that specifies an initial mesh. If you want to solve the boundary
value problem (BVP) on [ a, b ] , then specify x(1) as a and x(end) as b . The
function bvp4c adapts this mesh to the solution, so often a guess like
x = linspace(a,b,10) suffices. However, in difficult cases, you must place
mesh points where the solution changes rapidly. The entries of x must be
ordered and distinct, so if a < b , then x(1) < x(2) < ... < x(end), and
similarly for a > b .
v is a guess for the solution. It can be either a vector, or a function:
• Vector – For each component of the solution, bvpinit replicates the
corresponding element of the vector as a constant guess across all mesh
points. That is, v(i) is a constant guess for the ith component y(i,:) of the
solution at all the mesh points in x.
• Function – For a given mesh point, the function must return a vector whose
elements are guesses for the corresponding components of the solution. The
function must be of the form
y = guess(x)
where x is a mesh point and y is a vector whose length is the same as the
number of components in the solution. For example, if you use @guess,
bvpinit calls this function for each mesh point y(:,j) = guess(x(j)).
solinit = bvpinit(x,v,parameters) indicates that the BVP involves
unknown parameters. Use the vector parameters to provide a guess for all
unknown parameters.
2-213
bvpinit
solinit is a structure with the following fields. The structure can have any
name, but the fields must be named x, y, and parameters.
x
Ordered nodes of the initial mesh.
y
Initial guess for the solution with solinit.y(:,i) a guess for
the solution at the node solinit.x(i).
parameters
Optional. A vector that provides an initial guess for unknown
parameters.
solinit = bvpinit(sol,[anew bnew]) forms an initial guess on the interval
[anew bnew] from a solution sol on an interval [ a, b ] . The new interval must
be larger than the previous one, so either anew <= a < b <= bnew or
anew >= a > b >= bnew. The solution sol is extrapolated to the new interval.
If sol contains parameters, they are copied to solinit.
solinit = bvpinit(sol,[anew bnew],parameters) forms solinit as
described above, but uses parameters as a guess for unknown parameters in
solinit.
See Also
2-214
@ (function_handle), bvp4c, bvpget, bvpset, deval
bvpset
Purpose
2bvpset
Create/alter boundary value problem (BVP) options structure
Syntax
options = bvpset('name1',value1,'name2',value2,...)
options = bvpset(oldopts'name1',value1,...)
options = bvpset(oldopts,newopts)
bvpset
Description
options = bvpset('name1',value1,'name2',value2,...) creates a
structure options in which the named properties have the specified values.
Any unspecified properties have default values. It is sufficient to type only the
leading characters that uniquely identify the property. Case is ignored for
property names.
options = bvpset(oldopts,'name1',value1,...) alters an existing options
structure oldopts.
options = bvpset(oldopts,newopts) combines an existing options structure
oldopts with a new options structure newopts. Any new properties overwrite
corresponding old properties.
bvpset with no input arguments displays all property names and their possible
values.
BVP Properties
These properties are available.
Property
Value
Description
RelTol
Positive scalar
{1e-3}
A relative tolerance that applies to all components of the
residual vector. The computed solution S ( x ) is the exact
solution of S′( x) = F ( x, S ( x )) + res ( x ) . On each
subinterval of the mesh, the residual res ( x ) satisfies
(res(i)/max(abs(F(i)),AbsTol(i)/RelTol)) ≤ RelTol
AbsTol
Positive scalar or
vector {1e-6}
An absolue tolerance that applies to all components of the
residual vector. Elements of a vector of tolerances apply to
corresponding components of the residual vector.
2-215
bvpset
Property
Value
Description
Vectorized
on | {off}
Set on to inform bvp4c that you have coded the ODE
function F so that F([x1 x2 ...],[y1 y2 ...]) returns
[F(x1,y1) F(x2,y2) ...]. That is, your ODE function
can pass to the solver a whole array of column vectors at
once. This allows the solver to reduce the number of
function evaluations, and may significantly reduce
solution time.
SingularTerm
Matrix
Singular term of singular BVPs.
Set to the constant matrix S for equations of the form
y
y′ = S --- + f ( x, y, p )
x
that are posed on the interval [ 0, b ] where b > 0 .
FJacobian
Function |
matrix | cell
array
Analytic partial derivatives of ODEFUN.
For example, when solving y′ = f ( x, y ), set this property
to @FJAC if DFDY = FJAC(X,Y) evaluates the Jacobian of f
with respect to y . If the problem involves unknown
parameters p , [DFDY,DFDP] = FJAC(X,Y,P) must also
return the partial derivative of f with respect to p . For
problems with constant partial derivatives, set this
property to the value of DFDY or to a cell array
{DFDY,DFDP}.
BCJacobian
Function |
cell array
Analytic partial derivatives of BCFUN.
For example, for boundary conditions bc( ya, yb) = 0 , set
this property to @BCJAC if
[DBCDYA,DBCDYB] = BCJAC(YA,YB) evaluates the partial
derivatives of bc with respect to ya and to yb . If the
problem involves unknown parameters p , then
[DBCDYA,DBCDYB,DBCDP] = BCJAC(YA,YB,P) must also
return the partial derivative of bc with respect to p . For
problems with constant partial derivatives, set this
property to a cell array {DBCDYA,DBCDYB} or
{DBCDYA,DBCDYB,DBCDP}.
2-216
bvpset
Property
Value
Description
Nmax
positive integer
{floor(1000/n)}
Maximum number of mesh points allowed.
Stats
on | {off}
Display computational cost statistics.
See Also
@ (function_handle), bvp4c, bvpget, bvpinit, deval
2-217
bvpval
Purpose
2bvpval
Evaluate the numerical solution of a boundary value problem (BVP) using the
output of bvp4c
Note bvpval is obsolete and will be removed in the future. Please use deval
instead.
Syntax
sxint = bvpval(sol,xint)
Description
sxint = bvpval(sol,xint) uses sol, the output of bvp4c, to evaluate the
solution of a boundary value problem at each element of the vector xint. For
each i, sxint(:,i) is the solution corresponding to xint(i).
See Also
bvp4c, bvpinit, bvpget, bvpset
2-218
calendar
Purpose
Syntax
2calendar
Calendar
c = calendar
c = calendar(d)
c = calendar(y,m)
calendar(...)
Description
c = calendar returns a 6-by-7 matrix containing a calendar for the current
month. The calendar runs Sunday (first column) to Saturday.
c = calendar(d), where d is a serial date number or a date string, returns a
calendar for the specified month.
c = calendar(y,m), where y and m are integers, returns a calendar for the
specified month of the specified year.
calendar(...) displays the calendar on the screen.
Examples
The command:
calendar(1957,10)
reveals that the Space Age began on a Friday (on October 4, 1957, when
Sputnik 1 was launched).
S
0
6
13
20
27
0
See Also
M
0
7
14
21
28
0
Tu
1
8
15
22
29
0
Oct 1957
W
Th
2
3
9
10
16
17
23
24
30
31
0
0
F
4
11
18
25
0
0
S
5
12
19
26
0
0
datenum
2-219
camdolly
Purpose
2camdolly
Move the camera position and target
Syntax
camdolly(dx,dy,dz)
camdolly(dx,dy,dz,'targetmode')
camdolly(dx,dy,dz,'targetmode','coordsys')
camdolly(axes_handle,...)
Description
camdolly moves the camera position and the camera target by the specified
amounts.
camdolly(dx,dy,dz) moves the camera position and the camera target by the
specified amounts (see “Coordinate Systems”).
camdolly(dx,dy,dz,'targetmode') The targetmode argument can take on
two values that determine how MATLAB moves the camera:
• movetarget (default) – move both the camera and the target
• fixtarget – move only the camera
camdolly(dx,dy,dz,'targetmode','coordsys') The coordsys argument can
take on three values that determine how MATLAB interprets dx, dy, and dz:
Coordinate Systems
• camera (default) – move in the camera’s coordinate system. dx moves
left/right, dy moves down/up, and dz moves along the viewing axis. The units
are normalized to the scene.
For example, setting dx to 1 moves the camera to the right, which pushes the
scene to the left edge of the box formed by the axes position rectangle. A
negative value moves the scene in the other direction. Setting dz to 0.5
moves the camera to a position halfway between the camera position and the
camera target
• pixels – interpret dx and dy as pixel offsets. dz is ignored.
• data – interpret dx, dy, and dz as offesets in axes data coordinates.
camdolly(axes_handle,...) operates on the axes identified by the first
argument, axes_handle. When you do not specify an axes handle, camdolly
operates on the current axes.
2-220
camdolly
Remarks
camdolly sets the axes CameraPosition and CameraTarget properties, which
in turn causes the CameraPositionMode and CameraTargetMode properties to
be set to manual.
Examples
This example moves the camera along the x- and y-axes in a series of steps.
surf(peaks)
axis vis3d
t = 0:pi/20:2*pi;
dx = sin(t)./40;
dy = cos(t)./40;
for i = 1:length(t);
camdolly(dx(i),dy(i),0)
drawnow
end
See Also
axes, campos, camproj, camtarget, camup, camva
The axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
“Controlling the Camera Viewpoint” for related functions
See Defining Scenes with Camera Graphics for more information on camera
properties.
2-221
camlight
Purpose
2camlight
Create or move a light object in camera coordinates
Syntax
camlight headlight
camlight right
camlight left
camlight
camlight(az,el)
camlight(...‘style’)
camlight(light_handle,...)
light_handle = camlight(...)
Description
camlight('headlight') creates a light at the camera position.
camlight('right') creates a light right and up from camera.
camlight('left') creates a light left and up from camera.
camlight with no arguments is the same as camlight('right').
camlight(az,el) creates a light at the specified azimuth (az) and elevation
(el) with respect to the camera position. The camera target is the center of
rotation and az and el are in degrees.
camlight(...,'style') The style argument can take on the two values:
• local (default) – the light is a point source that radiates from the location in
all directions.
• infinite – the light shines in parallel rays.
camlight(light_handle,...) uses the light specified in light_handle.
light_handle = camlight(...) returns the light’s handle.
Remarks
camlight sets the light object Position and Style properties. A light created
with camlight will not track the camera. In order for the light to stay in a
constant position relative to the camera, you must call camlight whenever you
move the camera.
2-222
camlight
Examples
This example creates a light positioned to the left of the camera and then
repositions the light each time the camera is moved:
surf(peaks)
axis vis3d
h = camlight('left');
for i = 1:20;
camorbit(10,0)
camlight(h,'left')
drawnow;
end
See Also
light, lightangle
“Lighting” for related functions
Lighting as a Visualization Tool for more information on using lights
2-223
camlookat
Purpose
2camlookat
Position the camera to view an object or group of objects
Syntax
camlookat(object_handles)
camlookat(axes_handle)
camlookat
Description
camlookat(object_handles) views the objects identified in the vector
object_handles. The vector can contain the handles of axes children.
camlookat(axes_handle) views the objects that are children of the axes
identified by axes_handle.
camlookat views the objects that are in the current axes.
Remarks
camlookat moves the camera position and camera target while preserving the
relative view direction and camera view angle. The object (or objects) being
viewed roughly fill the axes position rectangle.
camlookat sets the axes CameraPosition and CameraTarget properties.
Examples
This example creates three spheres at different locations and then
progressively positions the camera so that each sphere is the object around
which the scene is composed:
[x y z] = sphere;
s1 = surf(x,y,z);
hold on
s2 = surf(x+3,y,z+3);
s3 = surf(x,y,z+6);
daspect([1 1 1])
view(30,10)
camproj perspective
camlookat(gca) % Compose
pause(2)
camlookat(s1) % Compose
pause(2)
camlookat(s2) % Compose
pause(2)
camlookat(s3) % Compose
pause(2)
camlookat(gca)
2-224
the scene around the current axes
the scene around sphere s1
the scene around sphere s2
the scene around sphere s3
camlookat
See Also
campos, camtarget
“Controlling the Camera Viewpoint” for related functions
Defining Scenes with Camera Graphics for more information
2-225
camorbit
Purpose
2camorbit
Rotate the camera position around the camera target
Syntax
camorbit(dtheta,dphi)
camorbit(dtheta,dphi,'coordsys')
camorbit(dtheta,dphi,'coordsys','direction')
camorbit(axes_handle,...)
Description
camorbit(dtheta,dphi) rotates the camera position around the camera target
by the amounts specified in dtheta and dphi (both in degrees). dtheta is the
horizontal rotation and dphi is the vertical rotation.
camorbit(dtheta,dphi,'coordsys') The coordsys argument determines the
center of rotation. It can take on two values:
• data (default) – rotate the camera around an axis defined by the camera
target and the direction (default is the positive z direction).
• camera – rotate the camera about the point defined by the camera target.
camorbit(dtheta,dphi,'coordsys','direction') The direction
argument, in conjunction with the camera target, defines the axis of rotation
for the data coordinate system. Specify direction as a three-element vector
containing the x, y, and z-components of the direction or one of the characters,
x, y, or z, to indicate [1 0 0], [0 1 0], or [0 0 1] respectively.
camorbit(axes_handle,...) operates on the axes identified by the first
argument, axes_handle. When you do not specify an axes handle, camorbit
operates on the current axes.
Examples
Compare rotation in the two coordinate systems with these for loops. The first
rotates the camera horizontally about a line defined by the camera target point
and a direction that is parallel to the y-axis. Visualize this rotation as a cone
formed with the camera target at the apex and the camera position forming the
base:
surf(peaks)
axis vis3d
for i=1:36
camorbit(10,0,'data',[0 1 0])
drawnow
2-226
camorbit
end
Rotation in the camera coordinate system orbits the camera around the axes
along a circle while keeping the center of a circle at the camera target.
surf(peaks)
axis vis3d
for i=1:36
camorbit(10,0,'camera')
drawnow
end
See Also
axes, axis('vis3d'), camdolly, campan, camzoom, camroll
“Controlling the Camera Viewpoint” for related functions
Defining Scenes with Camera Graphics for more information
2-227
campan
Purpose
2campan
Rotate the camera target around the camera position
Syntax
campan(dtheta,dphi)
campan(dtheta,dphi,'coordsys')
campan(dtheta,dphi,'coordsys','direction')
campan(axes_handle,...)
Description
campan(dtheta,dphi) rotates the camera target around the camera position
by the amounts specified in dtheta and dphi (both in degrees). dtheta is the
horizontal rotation and dphi is the vertical rotation.
campan(dtheta,dphi,'coordsys') The coordsys argument determines the
center of rotation. It can take on two values:
• data (default) – rotate the camera target around an axis defined by the
camera position and the direction (default is the positive z direction)
• camera – rotate the camera about the point defined by the camera target.
campan(dtheta,dphi,'coordsys','direction') The direction argument,
in conjunction with the camera position, defines the axis of rotation for the data
coordinate system. Specify direction as a three-element vector containing the
x, y, and z-components of the direction or one of the characters, x, y, or z, to
indicate [1 0 0], [0 1 0], or [0 0 1] respectively.
campan(axes_handle,...) operates on the axes identified by the first
argument, axes_handle. When you do not specify an axes handle, campan
operates on the current axes.
See Also
axes, camdolly, camorbit, camtarget, camzoom, camroll
“Controlling the Camera Viewpoint” for related functions
Defining Scenes with Camera Graphics for more information
2-228
campos
Purpose
2campos
Set or query the camera position
Syntax
campos
campos([camera_position])
campos('mode')
campos('auto'
campos('manual')
campos(axes_handle,...)
Description
campos with no arguments returns the camera position in the current axes.
campos([camera_position]) sets the position of the camera in the current
axes to the specified value. Specify the position as a three-element vector
containing the x-, y-, and z-coordinates of the desired location in the data units
of the axes.
campos('mode') returns the value of the camera position mode, which can be
either auto (the default) or manual.
campos('auto') sets the camera position mode to auto.
campos('manual') sets the camera position mode to manual.
campos(axes_handle,...) performs the set or query on the axes identified by
the first argument, axes_handle. When you do not specify an axes handle,
campos operates on the current axes.
Remarks
campos sets or queries values of the axes CameraPosition and
CameraPositionMode properties. The camera position is the point in the
Cartesian coordinate system of the axes from which you view the scene.
Examples
This example moves the camera along the x-axis in a series of steps:
surf(peaks)
axis vis3d off
for x = −200:5:200
campos([x,5,10])
drawnow
end
2-229
campos
See Also
axis, camproj, camtarget, camup, camva
The axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
“Controlling the Camera Viewpoint” for related functions
Defining Scenes with Camera Graphics for more information
2-230
camproj
Purpose
2camproj
Set or query the projection type
Syntax
camproj
camproj(projection_type)
camproj(axes_handle,...)
Description
The projection type determines whether MATLAB uses a perspective or
orthographic projection for 3-D views.
camproj with no arguments returns the projection type setting in the current
axes.
camproj('projection_type') sets the projection type in the current axes to
the specified value. Possible values for projection_type are: orthographic
and perspective.
camproj(axes_handle,...) performs the set or query on the axes identified by
the first argument, axes_handle. When you do not specify an axes handle,
camproj operates on the current axes.
Remarks
camproj sets or queries values of the axes object Projection property.
See Also
campos, camtarget, camup, camva
The axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
“Controlling the Camera Viewpoint” for related functions
Defining Scenes with Camera Graphics for more information
2-231
camroll
Purpose
2camroll
Rotate the camera about the view axis
Syntax
camroll(dtheta)
camroll(axes_handle,dtheta)
Description
camroll(dtheta) rotates the camera around the camera viewing axis by the
amounts specified in dtheta (in degrees). The viewing axis is defined by the
line passing through the camera position and the camera target.
camroll(axes_handle,dtheta) operates on the axes identified by the first
argument, axes_handle. When you do not specify an axes handle, camroll
operates on the current axes.
Remarks
camroll set the axes CameraUpVector property and thereby also sets the
CameraUpVectorMode property to manual.
See Also
axes, axis('vis3d'), camdolly, camorbit, camzoom, campan
“Controlling the Camera Viewpoint” for related functions
Defining Scenes with Camera Graphics for more information
2-232
camtarget
Purpose
2camtarget
Set or query the location of the camera target
Syntax
camtarget
camtarget([camera_target])
camtarget('mode')
camtarget('auto')
camtarget('manual')
camtarget(axes_handle,...)
Description
The camera target is the location in the axes that the camera points to. The
camera remains oriented toward this point regardless of its position.
camtarget with no arguments returns the location of the camera target in the
current axes.
camtarget([camera_target]) sets the camera target in the current axes to
the specified value. Specify the target as a three-element vector containing the
x-, y-, and z-coordinates of the desired location in the data units of the axes.
camtarget('mode') returns the value of the camera target mode, which can be
either auto (the default) or manual.
camtarget('auto') sets the camera target mode to auto.
camtarget('manual') sets the camera target mode to manual.
camtarget(axes_handle,...) performs the set or query on the axes identified
by the first argument, axes_handle. When you do not specify an axes handle,
camtarget operates on the current axes.
Remarks
camtarget sets or queries values of the axes object Cameratarget and
CameraTargetMode properties.
When the camera target mode is auto, MATLAB positions the camera target
at the center of the axes plot box.
Examples
This example moves the camera position and the camera target along the
x-axis in a series of steps:
surf(peaks);
2-233
camtarget
axis vis3d
xp = linspace(−150,40,50);
xt = linspace(25,50,50);
for i=1:50
campos([xp(i),25,5]);
camtarget([xt(i),30,0])
drawnow
end
See Also
axis, camproj, campos, camup, camva
The axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
“Controlling the Camera Viewpoint” for related functions
Defining Scenes with Camera Graphics for more information
2-234
camup
Purpose
2camup
Set or query the camera up vector
Syntax
camup
camup([up_vector])
camup('mode')
camup('auto')
camup('manual')
camup(axes_handle,...)
Description
The camera up vector specifies the direction that is oriented up in the scene.
camup with no arguments returns the camera up vector setting in the current
axes.
camup([up_vector]) sets the up vector in the current axes to the specified
value. Specify the up vector as x-, y-, and z-components. See Remarks.
camup('mode') returns the current value of the camera up vector mode, which
can be either auto (the default) or manual.
camup('auto') sets the camera up vector mode to auto. In auto mode,
MATLAB uses a value for the up vector of [0 1 0] for 2-D views. This means
the z-axis points up.
camup('manual') sets the camera up vector mode to manual. In manual mode,
MATLAB does not change the value of the camera up vector.
camup(axes_handle,...) performs the set or query on the axes identified by
the first argument, axes_handle. When you do not specify an axes handle,
camup operates on the current axes.
Remarks
camup sets or queries values of the axes object CameraUpVector and
CameraUpVectorMode properties.
Specify the camera up vector as the x-, y-, and z-coordinates of a point in the
axes coordinate system that forms the directed line segment PQ, where P is the
point (0,0,0) and Q is the specified x-, y-, and z-coordinates. This line always
points up. The length of the line PQ has no effect on the orientation of the
scene. This means a value of [0 0 1] produces the same results as [0 0 25].
2-235
camup
See Also
axis, camproj, campos, camtarget, camva
The axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
“Controlling the Camera Viewpoint” for related functions
Defining Scenes with Camera Graphics for more information
2-236
camva
Purpose
2camva
Set or query the camera view angle
Syntax
camva
camva(view_angle)
camva('mode')
camva('auto')
camva('manual')
camva(axes_handle,...)
Description
The camera view angle determines the field of view of the camera. Larger
angles produce a smaller view of the scene. You can implement zooming by
changing the camera view angle.
camva with no arguments returns the camera view angle setting in the current
axes.
camva(view_angle) sets the view angle in the current axes to the specified
value. Specify the view angle in degrees.
camva('mode') returns the current value of the camera view angle mode,
which can be either auto (the default) or manual. See Remarks.
camva('auto') sets the camera view angle mode to auto.
camva('manual') sets the camera view angle mode to manual. See Remarks.
camva(axes_handle,...) performs the set or query on the axes identified by
the first argument, axes_handle. When you do not specify an axes handle,
camva operates on the current axes.
Remarks
camva sets or queries values of the axes object CameraViewAngle and
CameraViewAngleMode properties.
When the camera view angle mode is auto, MATLAB adjusts the camera view
angle so that the scene fills the available space in the window. If you move the
camera to a different position, MATLAB changes the camera view angle to
maintain a view of the scene that fills the available area in the window.
2-237
camva
Setting a camera view angle or setting the camera view angle to manual
disables the MATLAB stretch-to-fill feature (stretching of the axes to fit the
window). This means setting the camera view angle to its current value,
camva(camva)
can cause a change in the way the graph looks. See the Remarks section of the
axes reference page for more information.
Examples
This example creates two pushbuttons, one that zooms in and another that
zooms out.
uicontrol('Style','pushbutton',...
'String','Zoom In',...
'Position',[20 20 60 20],...
'Callback','if camva <= 1;return;else;camva(camva-1);end');
uicontrol('Style','pushbutton',...
'String','Zoom Out',...
'Position',[100 20 60 20],...
'Callback','if camva >= 179;return;else;camva(camva+1);end');
Now create a graph to zoom in and out on:
surf(peaks);
Note the range checking in the callback statements. This keeps the values for
the camera view angle in the range, greater than zero and less than 180.
See Also
axis, camproj, campos, camup, camtarget
The axes properties CameraPosition, CameraTarget, CameraUpVector,
CameraViewAngle, Projection
“Controlling the Camera Viewpoint” for related functions
Defining Scenes with Camera Graphics for more information
2-238
camzoom
Purpose
2camzoom
Zoom in and out on a scene
Syntax
camzoom(zoom_factor)
camzoom(axes_handle,...)
Description
camzoom(zoom_factor) zooms in or out on the scene depending on the value
specified by zoom_factor. If zoom_factor is greater than 1, the scene appears
larger; if zoom_factor is greater than zero and less than 1, the scene appears
smaller.
camzoom(axes_handle,...) operates on the axes identified by the first
argument, axes_handle. When you do not specify an axes handle, camzoom
operates on the current axes.
Remarks
camzoom sets the axes CameraViewAngle property, which in turn causes the
CameraViewAngleMode property to be set to manual. Note that setting the
CameraViewAngle property disables the MATLAB stretch-to-fill feature
(stretching of the axes to fit the window). This may result in a change to the
aspect ratio of your graph. See the axes function for more information on this
behavior.
See Also
axes, camdolly, camorbit, campan, camroll, camva
“Controlling the Camera Viewpoint” for related functions
Defining Scenes with Camera Graphics for more information
2-239
capture
Purpose
2capture
capture is obsolete in Release 11 (5.3). getframe provides the same
functionality and supports TrueColor displays by returning TrueColor images.
Syntax
capture
capture(h)
[X,cmap] = capture(h)
Description
capture creates a bitmap copy of the contents of the current figure, including
any uicontrol graphics objects. It creates a new figure and displays the bitmap
copy as an image graphics object in the new figure.
capture(h) creates a new figure that contains a copy of the figure identified by
h.
[X,cmap] = capture(h) returns an image matrix X and a colormap. You
display this information using the statements
colormap(cmap)
image(X)
Remarks
The resolution of a bitmap copy is less than that obtained with the print
command.
See Also
image, print
“Figure Windows” for related functions
2-240
cart2pol
Purpose
2cart2pol
Transform Cartesian coordinates to polar or cylindrical
Syntax
[THETA,RHO,Z] = cart2pol(X,Y,Z)
[THETA,RHO] = cart2pol(X,Y)
Description
[THETA,RHO,Z] = cart2pol(X,Y,Z) transforms three-dimensional Cartesian
coordinates stored in corresponding elements of arrays X, Y, and Z, into
cylindrical coordinates. THETA is a counterclockwise angular displacement in
radians from the positive x-axis, RHO is the distance from the origin to a point
in the x-y plane, and Z is the height above the x-y plane. Arrays X, Y, and Z must
be the same size (or any can be scalar).
[THETA,RHO] = cart2pol(X,Y) transforms two-dimensional Cartesian
coordinates stored in corresponding elements of arrays X and Y into polar
coordinates.
Algorithm
The mapping from two-dimensional Cartesian coordinates to polar
coordinates, and from three-dimensional Cartesian coordinates to cylindrical
coordinates is
Y
Z
P
P
z
rh
o
Y
rho
theta
theta
X
X
See Also
Two-Dimensional Mapping
Three-Dimensional Mapping
theta = atan2(y,x)
rho = sqrt(x.^2 + y.^2)
theta = atan2(y,x)
rho = sqrt(x.^2 + y.^2)
z = z
cart2sph, pol2cart, sph2cart
2-241
cart2sph
Purpose
2cart2sph
Transform Cartesian coordinates to spherical
Syntax
[THETA,PHI,R] = cart2sph(X,Y,Z)
Description
[THETA,PHI,R] = cart2sph(X,Y,Z) transforms Cartesian coordinates stored
in corresponding elements of arrays X, Y, and Z into spherical coordinates.
Azimuth THETA and elevation PHI are angular displacements in radians
measured from the positive x-axis, and the x-y plane, respectively; and R is the
distance from the origin to a point.
Arrays X, Y, and Z must be the same size.
Algorithm
The mapping from three-dimensional Cartesian coordinates to spherical
coordinates is
Z
P
r
Y
phi
th
et
a
X
See Also
2-242
cart2pol, pol2cart, sph2cart
theta = atan2(y,x)
phi = atan2(z, sqrt(x.^2 + y.^2))
r = sqrt(x.^2+y.^2+z.^2)
case
Purpose
2case
Description
case is part of the switch statement syntax, which allows for conditional
execution.
Case switch
A particular case consists of the case statement itself, followed by a case
expression, and one or more statements.
A case is executed only if its associated case expression (case_expr) is the first
to match the switch expression (switch_expr).
Examples
The general form of the switch statement is:
switch switch_expr
case case_expr
statement,...,statement
case {case_expr1,case_expr2,case_expr3,...}
statement,...,statement
...
otherwise
statement,...,statement
end
See Also
switch
2-243
cat
Purpose
2cat
Concatenate arrays
Syntax
C = cat(dim,A,B)
C = cat(dim,A1,A2,A3,A4...)
Description
C = cat(dim,A,B) concatenates the arrays A and B along dim.
C = cat(dim,A1,A2,A3,A4,...) concatenates all the input arrays (A1, A2, A3,
A4, and so on) along dim.
cat(2,A,B) is the same as [A,B] and cat(1,A,B) is the same as [A;B].
Remarks
When used with comma separated list syntax, cat(dim,C{:}) or
cat(dim,C.field) is a convenient way to concatenate a cell or structure array
containing numeric matrices into a single matrix.
Examples
Given,
A =
B =
1
3
2
4
5
7
6
8
concatenating along different dimensions produces:
1
3
5
7
2
4
6
8
C = cat(1,A,B)
1
3
A = magic(3); B = pascal(3);
C = cat(4,A,B);
produce a 3-by-3-by-1-by-2 array.
num2cell
The special character []
2-244
5
7
6
8
C = cat(2,A,B)
The commands
See Also
2
4
5
7
1
3
6
8
2
4
C = cat(3,A,B)
catch
Purpose
2catch
Description
The general form of a try statement is:
Begin catch block
try,
statement,
...,
statement,
catch,
statement,
...,
statement,
end
Normally, only the statements between the try and catch are executed.
However, if an error occurs while executing any of the statements, the error is
captured into lasterr, and the statements between the catch and end are
executed. If an error occurs within the catch statements, execution stops
unless caught by another try...catch block. The error string produced by a
failed try block can be obtained with lasterr.
See Also
end, eval, evalin, try
2-245
caxis
Purpose
2caxis
Color axis scaling
Syntax
caxis([cmin cmax])
caxis auto
caxis manual
caxis(caxis)
v = caxis
caxis(axes_handle,...)
Description
caxis controls the mapping of data values to the colormap. It affects any
surfaces, patches, and images with indexed CData and CDataMapping set to
scaled. It does not affect surfaces, patches, or images with true color CData or
with CDataMapping set to direct.
caxis([cmin cmax]) sets the color limits to specified minimum and maximum
values. Data values less than cmin or greater than cmax map to cmin and cmax,
respectively. Values between cmin and cmax linearly map to the current
colormap.
caxis auto lets MATLAB compute the color limits automatically using the
minimum and maximum data values. This is the default behavior. Color values
set to Inf map to the maximum color, and values set to −Inf map to the
minimum color. Faces or edges with color values set to NaN are not drawn.
caxis manual and caxis(caxis) freeze the color axis scaling at the current
limits. This enables subsequent plots to use the same limits when hold is on.
v = caxis returns a two-element row vector containing the [cmin cmax]
currently in use.
caxis(axes_handle,...) uses the axes specified by axes_handle instead of
the current axes.
Remarks
caxis changes the CLim and CLimMode properties of axes graphics objects.
How Color Axis Scaling Works
Surface, patch, and image graphics objects having indexed CData and
CDataMapping set to scaled, map CData values to colors in the figure colormap
each time they render. CData values equal to or less than cmin map to the first
2-246
caxis
color value in the colormap, and CData values equal to or greater than cmax
map to the last color value in the colormap. MATLAB performs the following
linear transformation on the intermediate values (referred to as C below) to
map them to an entry in the colormap (whose length is m, and whose row index
is referred to as index below).
index = fix((C–cmin)/(cmax–cmin)∗m)+1
Examples
Create (X,Y,Z) data for a sphere and view the data as a surface.
[X,Y,Z] = sphere;
C = Z;
surf(X,Y,Z,C)
Values of C have the range [−1 1]. Values of C near −1 are assigned the lowest
values in the colormap; values of C near 1 are assigned the highest values in
the colormap.
To map the top half of the surface to the highest value in the color table, use
caxis([−1 0])
To use only the bottom half of the color table, enter
caxis([−1 3])
which maps the lowest CData values to the bottom of the colormap, and the
highest values to the middle of the colormap (by specifying a cmax whose value
is equal to cmin plus twice the range of the CData).
The command
caxis auto
resets axis scaling back to auto-ranging and you see all the colors in the
surface. In this case, entering
caxis
returns
[–1 1]
2-247
caxis
Adjusting the color axis can be useful when using images with scaled color
data. For example, load the image data and colormap for Cape Cod,
Massachusetts.
load cape
This command loads the images data X and the image’s colormap map into the
workspace. Now display the image with CDataMapping set to scaled and install
the image’s colormap.
image(X,'CDataMapping','scaled')
colormap(map)
MATLAB sets the color limits to span the range of the image data, which is 1
to 192:
caxis
ans =
1
2-248
192
caxis
The blue color of the ocean is the first color in the colormap and is mapped to
the lowest data value (1). You can effectively move sealevel by changing the
lower color limit value. For example,
Caxis = [1 192]
Caxis = [3 192]
50
50
100
100
150
150
200
200
250
250
300
300
100
200
300
100
Caxis = [5 192]
50
100
100
150
150
200
200
250
250
300
300
See Also
200
300
Caxis = [6 192]
50
100
200
300
100
200
300
axes, axis, colormap, get, mesh, pcolor, set, surf
The CLim and CLimMode properties of axes graphics objects.
The Colormap property of figure graphics objects.
“Color Operations” for related functions
Axes Color Limits for more examples
2-249
cd
Purpose
2cd
Graphical
Interface
As an alternative to the cd function, use the Current Directory field in the
MATLAB desktop toolbar.
Syntax
cd
w = cd
cd('directory')
cd('..')
cd directory or cd ..
Description
cd displays the current working directory.
Change working directory
w = cd assigns the current working directory to w.
cd('directory') sets the current working directory to directory. Use the full
pathname for directory. On UNIX platforms, the character ~ is interpreted as
the user’s root directory.
cd('..') changes the current working directory to the directory above it.
cd directory or cd .. is the unquoted form of the syntax.
Examples
On UNIX
cd('/usr/local/matlab/toolbox/demos')
changes the current working directory to demos.
On Windows
cd('c:/toolbox/matlab/demos')
changes the current working directory to demos. Then typing
cd ..
changes the current working directory to matlab.
See Also
2-250
dir, path, pwd, what
cdf2rdf
Purpose
2cdf2rdf
Convert complex diagonal form to real block diagonal form
Syntax
[V,D] = cdf2rdf(V,D)
Description
If the eigensystem [V,D] = eig(X) has complex eigenvalues appearing in
complex-conjugate pairs, cdf2rdf transforms the system so D is in real
diagonal form, with 2-by-2 real blocks along the diagonal replacing the complex
pairs originally there. The eigenvectors are transformed so that
X = V*D/V
continues to hold. The individual columns of V are no longer eigenvectors, but
each pair of vectors associated with a 2-by-2 block in D spans the corresponding
invariant vectors.
Examples
The matrix
X =
1
0
0
2
4
-5
3
5
4
has a pair of complex eigenvalues.
[V,D] = eig(X)
V =
1.0000
0
0
-0.0191 - 0.4002i
0 - 0.6479i
0.6479
-0.0191 + 0.4002i
0 + 0.6479i
0.6479
1.0000
0
0
0
4.0000 + 5.0000i
0
0
0
4.0000 - 5.0000i
D =
Converting this to real block diagonal form produces
[V,D] = cdf2rdf(V,D)
2-251
cdf2rdf
V =
1.0000
0
0
-0.0191
0
0.6479
-0.4002
-0.6479
0
1.0000
0
0
0
4.0000
-5.0000
0
5.0000
4.0000
D =
Algorithm
The real diagonal form for the eigenvalues is obtained from the complex form
using a specially constructed similarity transformation.
See Also
eig, rsf2csf
2-252
cdfepoch
Purpose
2cdfepoch
Construct a cdfepoch object for Common Data Format (CDF) export
Syntax
E = cdfepoch(date)
Description
E = cdfepoch(date) constructs a cdfepoch object, where date is a valid string
(datestr), a number (datenum) representing a date, or a cdfepoch object.
When writing data to a CDF using cdfwrite, use cdfepoch to convert
MATLAB formatted dates to CDF formatted dates. The MATLAB cdfepoch
object simulates the CDFEPOCH datatype in CDF files
Note A CDF epoch is the number of milliseconds since 1-Jan-0000. MATLAB
datenums are the number of days since 0-Jan-0000.
See also
cdfinfo, cdfread, cdfwrite, datenum
2-253
cdfinfo
Purpose
2cdfinfo
Return information about a CDF file
Syntax
info = cdfinfo(file)
Description
info = cdfinfo(file) returns information about the Common Data Format
(CDF) file specified in the string, file. The function returns a structure, info,
that contains the fields shown in the following table.
Field
Description
Return Type
FileModDate
Date the file was last modified
String
Filename
Name of the file
String
FileSettings
Library settings used to create
the file
Structure array
FileSize
Size of the file, in bytes
Double
Format
File format (CDF)
String
FormatVersion
Version of the CDF library
used to create the file
String
GlobalAttributes
Global metadata
Structure array
Subfiles
Filenames containing the CDF
file’s data, if it is a multifile
CDF
Cell array
VariableAttributes
Metadata for the variables
Structure array
Variables
Details about the variables in
the file
Cell array
The GlobalAttributes and VariableAttributes Fields
GlobalAttributes and VariableAttributes are structure arrays that each
contain one field for each global or variable attribute respectively. The name of
the field corresponds to the name of an attribute. The data in that field,
contained in a cell array, represents the entry values for that attribute.
2-254
cdfinfo
For VariableAttributes, the attribute data resides in an N-by-2 cell array,
where N is the number of variables. The first column of this cell array contains
the variable names associated with the entries. The second column contains
the entry values.
Note Attribute names may not match the names of the attributes in the CDF
file exactly. Because attribute names can contain characters that are illegal in
MATLAB field names, they may be translated into legal field names. Illegal
characters that appear at the beginning of attributes are removed; other
illegal characters are replaced with underscores ('_'). If an attribute’s name is
modified, the attribute’s internal number is appended to the end of the field
name. For example, Variable%Attribute might become
Variable_Attribute_013.
The Variables Field
The Variables field of the returned info structure is an N-by-6 cell array,
where N is the number of variables. The six columns of the cell array contain
the following information.
Column No.
Description
Return Type
1
Name of the variable
String
2
Dimensions of the variable, as returned by
the size function
Double
array
3
Number of records assigned for the variable
Double
4
Data type of the variable, as stored in the
CDF file
String
2-255
cdfinfo
Column No.
5
Description
Return Type
Record and dimension variance settings for
the variable. The single T or F to the left of
the slash designates whether values vary by
record. The zero or more T or F letters to the
right of the slash designate whether values
vary at each dimension. Here are some
examples.
String
T/
F/T
T/TFF
6
(scalar variable)
(one-dimensional variable)
(three-dimensional variable)
Sparsity of the variable’s records. This is a
string holding one of three possible values:
String
• 'Full'
• 'Sparse (padded)'
• 'Sparse (nearest)'
Examples
info = cdfinfo('example.cdf')
info =
Filename: 'example.cdf'
FileModDate: '29-Jun-1995 05:51:58'
FileSize: 230513
Format: 'CDF'
FormatVersion: '2.4.8'
FileSettings: [1x1 struct]
Subfiles: {}
Variables: {7x6 cell}
GlobalAttributes: [1x1 struct]
VariableAttributes: [1x1 struct]
info.Variables
ans =
'L_gse'
[1x2 double]
'Status%C1'
[1x2 double]
'B_gse%C1'
[1x2 double]
'B_nsigma%C1' [1x2 double]
2-256
[
1]
[7493]
[7493]
[7493]
'char'
'F/T'
'uint8'
'T/T'
'single' 'T/T'
'single' 'T/'
'Full'
'Full'
'Full'
'Full'
cdfinfo
See Also
cdfread
2-257
cdfread
Purpose
2cdfread
Read data from a CDF file
Syntax
data =
data =
data =
data =
[data,
Description
data = cdfread(file) reads all of the variables from each record of the
Common Data Format (CDF) file specified in the string, file. The return
value, data, is a cell array in which each row contains a record and each column
cdfread(file)
cdfread(file, 'records', recnums, ...)
cdfread(file, 'variables', varnames, ...)
cdfread(file, 'slices', dimensionvalues, ...)
info] = cdfread(file, ...)
represents a variable.
data = cdfread(file, 'records', recnums, ...) reads only those records
specified in the vector, recnums. The record numbers are zero-based. The
return value, data, is a cell array having length(recnums) number of rows and
as many columns as there are variables.
data = cdfread(file, 'variables', varnames, ...) reads only those
variables specified in the 1-by-N or N-by-1 cell array of strings, varnames. The
return alue, data, is returned in a cell array having length(varnames)
number of columns and a row for each record requested.
data = cdfread(file, 'slices', dimensionvalues, ...) reads specific
values from the records of one variable in the CDF file. The N-by-3 matrix,
dimensionvalues, indicates which records are to be read by specifying start,
interval, and count parameters for each of the N dimensions of the variable.
The start parameter is zero-based.
The number of rows in dimensionvalues must be less than or equal to the
number of dimensions of the variable. Unspecified rows default to [0 1 N],
where N is the total number of values in a record. This causes cdfread to read
every value from those dimensions.
Because you can read just one variable at a time, you must also include a
'variables' parameter with this syntax.
[data, info] = cdfread(file, ...) also returns details about the CDF file
in the info structure.
2-258
cdfread
Examples
Read all of the data from the file.
data = cdfread('example.cdf');
Read just the data from variable 'Time'.
data = cdfread('example.cdf', 'Variable', {'Time'});
Read the first value in the first dimension, the second value in the second
dimension, the first and third values in the third dimension, and all values in
the remaining dimension of the variable 'multidimensional'.
data = cdfread('example.cdf', 'Variable', ...
{'multidimensional'}, 'Slices', [0 1 1; 1 1 1; 0 2 2]);
This is similar to reading the whole variable into 'data', and then using the
MATLAB command
data{1}(1, 2, [1 3], :)
See Also
cdfinfo, cdfwrite, cdfepoch
2-259
cdfwrite
Purpose
2cdfwrite
Write data to a CDF file
Syntax
cdfwrite(file, variablelist)
cdfwrite(..., 'PadValues', padvals)
cdfwrite(..., 'GlobalAttributes', gattrib)
cdfwrite(..., 'VariableAttributes', vattrib)
cdfwrite(..., 'WriteMode', mode)
cdfwrite(..., 'Format', format)
Description
cdfwrite(file,variablelist) writes out a Common Data Format (CDF) file,
specified in the string, file. The variablelist argument is a cell array of
ordered pairs, which are comprised of a CDF variable name (a string) and the
corresponding CDF variable value. To write out multiple records for a variable,
put the values in a cell array, where each element in the cell array represents
a record.
cdfwrite(...,'PadValues',padvals) writes out pad values for given
variable names. padvals is a cell array of ordered pairs, which are comprised
of a variable name (a string) and a corresponding pad value. Pad values are the
default value associated with the variable when an out-of-bounds record is
accessed. Variable names that appear in padvals must appear in
variablelist.
cdfwrite(...,'GlobalAttributes',gattrib) writes the structure gattrib
as global metadata for the CDF file. Each field of the structure is the name of
a global attribute. The value of each field contains the value of the attribute.
To write out multiple values for an attribute, put the values in a cell array
where each element in the cell array represents a record.
Note To specify a global attribute name that is illegal in MATLAB, create a
field called 'CDFAttributeRename' in the attribute structure. The value of
this field must have a value that is a cell array of ordered pairs. The ordered
pair consists of the name of the original attribute, as listed in the
GlobalAttributes structure and the corresponding name of the attribute to be
written to the CDF file.
2-260
cdfwrite
cdfwrite(..., 'VariableAttributes', vattrib) writes the structure
vattrib as variable metadata for the CDF. Each field of the struct is the name
of a variable attribute. The value of each field should be an M-by-2 cell array
where M is the number of variables with attributes. The first element in the
cell array should be the name of the variable and the second element should be
the value of the attribute for that variable.
Note To specify a variable attribute name that is illegal in MATLAB, create
a field called 'CDFAttributeRename' in the attribute structure. The value of
this field must have a value that is a cell array of ordered pairs. The ordered
pair consists of the name of the original attribute, as listed in the
VariableAttributes struct, and the corresponding name of the attribute to
be written to the CDF file. If you are specifying a variable attribute of a CDF
variable that you are renaming, the name of the variable in the
VariableAttributes structure must be the same as the renamed variable.
cdfwrite(...,'WriteMode',mode) where mode is either 'overwrite' or
'append', indicates whether or not the specified variables should be appended
to the CDF file if the file already exists. By default, cdfwrite overwrites
existing variables and attributes.,
cdfwrite(...,'Format',format) where format is either 'multifile' or
'singlefile', indicates whether or not the data is written out as a multifile
CDF. In a multifile CDF, each variable is stored in a separate file with the
name *.vN, where N is the number of the variable that is written out to the
CDF. By default, cdfwrite writes out a single file CDF. When 'WriteMode' is
set to 'Append', the 'Format' option is ignored, and the format of the
pre-existing CDF is used.
Examples
Write out a file 'example.cdf' containing a variable 'Longitude' with the
value [0:360].
cdfwrite('example', {'Longitude', 0:360});
Write out a file 'example.cdf' containing variables 'Longitude' and
'Latitude' with the variable 'Latitude' having a pad value of 10 for all
out-of-bounds records that are accessed.
2-261
cdfwrite
cdfwrite('example', {'Longitude', 0:360, 'Latitude', 10:20},...
'PadValues', {'Latitude', 10});
Write out a file 'example.cdf', containing a variable 'Longitude' with the
value [0:360], and with a variable attribute of 'validmin' with the value 10.
varAttribStruct.validmin = {'longitude' [10]};
cdfwrite('example', {'Longitude' 0:360}, 'VarAttribStruct',...
varAttribStruct);
See Also
2-262
cdfread, cdfinfo, cdfepoch
ceil
Purpose
2ceil
Round toward infinity
Syntax
B = ceil(A)
Description
B = ceil(A) rounds the elements of A to the nearest integers greater than or
equal to A. For complex A, the imaginary and real parts are rounded
independently.
Examples
a = [-1.9, -0.2, 3.4, 5.6, 7, 2.4+3.6i]
a =
Columns 1 through 4
-1.9000
-0.2000
3.4000
5.6000
Columns 5 through 6
7.0000
2.4000 + 3.6000i
ceil(a)
ans =
Columns 1 through 4
-1.0000
0
4.0000
6.0000
Columns 5 through 6
7.0000
3.0000 + 4.0000i
See Also
fix, floor, round
2-263
cell
Purpose
2cell
Create cell array
Syntax
c
c
c
c
c
Description
c = cell(n) creates an n-by-n cell array of empty matrices. An error message
appears if n is not a scalar.
=
=
=
=
=
cell(n)
cell(m,n) or c = cell([m n])
cell(m,n,p,...) or c = cell([m n p ...])
cell(size(A))
cell(javaobj)
c = cell(m,n) or c = cell([m,n]) creates an m-by-n cell array of empty
matrices. Arguments m and n must be scalars.
c = cell(m,n,p,...) or c = cell([m n p ...]) creates an m-by-n-by-p-...
cell array of empty matrices. Arguments m, n, p,... must be scalars.
c = cell(size(A)) creates a cell array the same size as A containing all empty
matrices.
c = cell(javaobj) converts a Java array or Java object, javaobj, into a
MATLAB cell array. Elements of the resulting cell array will be of the
MATLAB type (if any) closest to the Java array elements or Java object.
Examples
This example creates a cell array that is the same size as another array, A.
A = ones(2,2)
A =
1
1
1
1
c = cell(size(A))
c =
[]
[]
[]
[]
The next example converts an array of java.lang.String objects into a
MATLAB cell array.
2-264
cell
strArray = java_array('java.lang.String',3);
strArray(1) = java.lang.String('one');
strArray(2) = java.lang.String('two');
strArray(3) = java.lang.String('three');
cellArray = cell(strArray)
cellArray =
'one'
'two'
'three'
See Also
num2cell, ones, rand, randn, zeros
2-265
cell2mat
Purpose
2cell2mat
Convert cell array of matrices into single matrix
Syntax
m = cell2mat(c)
Description
m = cell2mat(c) converts a multidimensional cell array, c, with contents of
the same data type into a single matrix, m. The contents of c must be able to
concatenate into a hyperrectangle. Moreover, for each pair of neighboring cells,
the dimensions of the cell’s contents must match, excluding the dimension in
which the cells are neighbors.
The example shown below combines matrices in a 3-by-2 cell array into a single
60-by-50 matrix:
cell2mat(c)
10x25
10x25
20x25
20x25
cell2mat
30x25
Remarks
60x50
30x25
The dimensionality (or number of dimensions) of m will match the highest
dimensionality contained in the cell array.
cell2mat is not supported for cell arrays containing cell arrays or objects.
Examples
Combine the matrices in four cells of cell array C into the single matrix, M:
C = {[1] [2 3 4]; [5; 9] [6 7 8; 10 11 12]}
C =
[
1]
[1x3 double]
[2x1 double]
[2x3 double]
2-266
cell2mat
C{1,1}
ans =
1
C{1,2}
ans =
2
3
4
C{2,1}
ans =
5
9
C{2,2}
ans =
6
10
7
11
8
12
M = cell2mat(C)
M =
1
2
3
5
6
7
9
10
11
See Also
4
8
12
mat2cell, num2cell
2-267
cell2struct
Purpose
2cell2struct
Convert cell array to structure array
Syntax
s = cell2struct(c,fields,dim)
Description
s = cell2struct(c,fields,dim) creates a structure array, s, from the
information contained within cell array, c.
The fields argument specifies field names for the structure array. fields can
be a character array or a cell array of strings.
The dim argument controls which axis of the cell array is to be used in creating
the structure array. The length of c along the specified dimension must match
the number of fields named in fields. In other words, the following must be
true.
size(c,dim) == length(fields)
size(c,dim) == size(fields,1)
Examples
% if fields is a cell array
% if fields is a char array
The cell array, c, in this example contains information on trees. The three
columns of the array indicate the common name, genus, and average height of
a tree.
c = {'birch','betula',65;
c =
'birch'
'betula'
'maple'
'acer'
'maple','acer',50}
[65]
[50]
To put this information into a structure with the fields name, genus, and
height, use cell2struct along the second dimension of the 2-by-3 cell array.
fields = {'name', 'genus', 'height'};
s = cell2struct(c, fields, 2);
This yields the following 2-by-1 structure array.
s(1)
ans =
name: 'birch'
genus: 'betula'
height: 65
See Also
2-268
fieldnames, struct2cell
s(2)
ans =
name: 'maple'
genus: 'acer'
height: 50
celldisp
Purpose
2celldisp
Display cell array contents.
Syntax
celldisp(C)
celldisp(C,name)
Description
celldisp(C) recursively displays the contents of a cell array.
celldisp(C,name) uses the string name for the display instead of the name of
the first input (or ans).
Example
Use celldisp to display the contents of a 2-by-3 cell array:
C = {[1 2] 'Tony' 3+4i; [1 2;3 4] -5 'abc'};
celldisp(C)
C{1,1} =
1
2
C{2,1} =
1
3
2
4
C{1,2} =
Tony
C{2,2} =
-5
C{1,3} =
3.0000+ 4.0000i
C{2,3} =
abc
See Also
cellplot
2-269
cellfun
Purpose
2cellfun
Apply a function to each element in a cell array
Syntax
D = cellfun('fname',C)
D = cellfun('size',C,k)
D = cellfun('isclass',C,classname)
Description
D = cellfun('fname',C) applies the function fname to the elements of the cell
array C and returns the results in the double array D. Each element of D
contains the value returned by fname for the corresponding element in C. The
output array D is the same size as the cell array C.
These functions are supported:
Function
Return Value
isempty
true for an empty cell element
islogical
true for a logical cell element
isreal
true for a real cell element
length
Length of the cell element
ndims
Number of dimensions of the cell element
prodofsize
Number of elements in the cell element
D = cellfun('size',C,k) returns the size along the k-th dimension of each
element of C.
D = cellfun('isclass',C,'classname') returns true for each element of C
that matches classname. This function syntax returns false for objects that
are a subclass of classname.
Limitations
If the cell array contains objects, cellfun does not call overloaded versions of
the function fname.
Example
Consider this 2-by-3 cell array:
C{1,1} = [1 2; 4 5];
C{1,2} = 'Name';
2-270
cellfun
C{1,3}
C{2,1}
C{2,2}
C{2,3}
=
=
=
=
pi;
2 + 4i;
7;
magic(3);
cellfun returns a 2-by-3 double array:
D = cellfun('isreal',C)
D =
1
0
1
1
1
1
len = cellfun('length',C)
len =
2
1
4
1
1
3
isdbl = cellfun('isclass',C,'double')
isdbl =
1
1
See Also
0
1
1
1
isempty, islogical, isreal, length, ndims, size
2-271
cellplot
Purpose
2cellplot
Graphically display the structure of cell arrays
Syntax
cellplot(c)
cellplot(c,'legend')
handles = cellplot(...)
Description
cellplot(c) displays a figure window that graphically represents the
contents of c. Filled rectangles represent elements of vectors and arrays, while
scalars and short text strings are displayed as text.
cellplot(c,'legend') also puts a legend next to the plot.
handles = cellplot(c) displays a figure window and returns a vector of
surface handles.
Limitations
The cellplot function can display only two-dimensional cell arrays.
Examples
Consider a 2-by-2 cell array containing a matrix, a vector, and two text strings:
c{1,1}
c{1,2}
c{2,1}
c{2,2}
=
=
=
=
'2-by-2';
'eigenvalues of eye(2)';
eye(2);
eig(eye(2));
The command cellplot(c) produces:
2-272
cellstr
Purpose
2cellstr
Create cell array of strings from character array
Syntax
c = cellstr(S)
Description
c = cellstr(S) places each row of the character array S into separate cells of
c. Use the char function to convert back to a string matrix.
Examples
Given the string matrix
S=['abc ';'defg';'hi
']
S =
abc
defg
hi
whos S
Name
S
Size
3x4
Bytes
24
Class
char array
The following command returns a 3-by-1 cell array.
c = cellstr(S)
c =
'abc'
'defg'
'hi'
whos c
Name
c
See Also
Size
3x1
Bytes
294
Class
cell array
iscellstr, strings
2-273
cgs
Purpose
2cgs
Conjugate Gradients Squared method
Syntax
x = cgs(A,b)
cgs(A,b,tol)
cgs(A,b,tol,maxit)
cgs(A,b,tol,maxit,M)
cgs(A,b,tol,maxit,M1,M2)
cgs(A,b,tol,maxit,M1,M2,x0)
cgs(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...)
[x,flag] = cgs(A,b,...)
[x,flag,relres] = cgs(A,b,...)
[x,flag,relres,iter] = cgs(A,b,...)
[x,flag,relres,iter,resvec] = cgs(A,b,...)
Description
x = cgs(A,b) attempts to solve the system of linear equations A*x = b for x.
The n-by-n coefficient matrix A must be square and should be large and sparse.
The column vector b must have length n. A can be a function afun such that
afun(x) returns A*x.
If cgs converges, a message to that effect is displayed. If cgs fails to converge
after the maximum number of iterations or halts for any reason, a warning
message is printed displaying the relative residual norm(b-A*x)/norm(b) and
the iteration number at which the method stopped or failed.
cgs(A,b,tol) specifies the tolerance of the method, tol. If tol is [], then cgs
uses the default, 1e-6.
cgs(A,b,tol,maxit) specifies the maximum number of iterations, maxit. If
maxit is [] then cgs uses the default, min(n,20).
cgs(A,b,tol,maxit,M) and cgs(A,b,tol,maxit,M1,M2) use the
preconditioner M or M = M1*M2 and effectively solve the system
inv(M)*A*x = inv(M)*b for x. If M is [] then cgs applies no preconditioner. M
can be a function that returns M\x.
cgs(A,b,tol,maxit,M1,M2,x0) specifies the initial guess x0. If x0 is [], then
cgs uses the default, an all-zero vector.
2-274
cgs
cgs(afun,b,tol,maxit,m1fun,m2fun,x0,p1,p2,...) passes parameters
p1,p2,... to functions afun(x,p1,p2,...), m1fun(x,p1,p2,...), and
m2fun(x,p1,p2,...)
[x,flag] = cgs(A,b,...) returns a solution x and a flag that describes the
convergence of cgs.
Flag
Convergence
0
cgs converged to the desired tolerance tol within maxit
iterations.
1
cgs iterated maxit times but did not converge.
2
Preconditioner M was ill-conditioned.
3
cgs stagnated. (Two consecutive iterates were the same.)
4
One of the scalar quantities calculated during cgs became
too small or too large to continue computing.
Whenever flag is not 0, the solution x returned is that with minimal norm
residual computed over all the iterations. No messages are displayed if the
flag output is specified.
[x,flag,relres] = cgs(A,b,...) also returns the relative residual
norm(b-A*x)/norm(b). If flag is 0, then relres <= tol.
[x,flag,relres,iter] = cgs(A,b,...) also returns the iteration number at
which x was computed, where 0 <= iter <= maxit.
[x,flag,relres,iter,resvec] = cgs(A,b,...) also returns a vector of the
residual norms at each iteration, including norm(b-A*x0).
Examples
Example 1.
A = gallery('wilk',21);
b = sum(A,2);
tol = 1e-12; maxit = 15;
M1 = diag([10:-1:1 1 1:10]);
x = cgs(A,b,tol,maxit,M1,[],[]);
2-275
cgs
Alternatively, use this matrix-vector product function
function y = afun(x,n)
y = [ 0;
x(1:n-1)] + [((n-1)/2:-1:0)';
(1:(n-1)/2)'] .*x + [x(2:n);
0 ];
and this preconditioner backsolve function
function y = mfun(r,n)
y = r ./ [((n-1)/2:-1:1)'; 1; (1:(n-1)/2)'];
as inputs to cgs.
x1 = cgs(@afun,b,tol,maxit,@mfun,[],[],21);
Note that both afun and mfun must accept cgs’s extra input n=21.
Example 2.
load west0479
A = west0479
b = sum(A,2)
[x,flag] = cgs(A,b)
flag is 1 because cgs does not converge to the default tolerance 1e-6 within the
default 20 iterations.
[L1,U1] = luinc(A,1e-5)
[x1,flag1] = cgs(A,b,1e-6,20,L1,U1)
flag1 is 2 because the upper triangular U1 has a zero on its diagonal, and cgs
fails in the first iteration when it tries to solve a system such as U1*y = r for
y with backslash.
[L2,U2] = luinc(A,1e-6)
[x2,flag2,relres2,iter2,resvec2] = cgs(A,b,1e-15,10,L2,U2)
flag2 is 0 because cgs converges to the tolerance of 6.344e-16 (the value of
relres2) at the fifth iteration (the value of iter2) when preconditioned by the
incomplete LU factorization with a drop tolerance of 1e-6.
resvec2(1) = norm(b) and resvec2(6) = norm(b-A*x2). You can follow the
2-276
cgs
progress of cgs by plotting the relative residuals at each iteration starting from
the initial estimate (iterate number 0) with
semilogy(0:iter2,resvec2/norm(b),'-o')
xlabel('iteration number')
ylabel('relative residual')
0
10
−2
10
−4
10
−6
relative residual
10
−8
10
−10
10
−12
10
−14
10
−16
10
See Also
0
0.5
1
1.5
2
2.5
3
iteration number
3.5
4
4.5
5
bicg, bicgstab, gmres, lsqr, luinc, minres, pcg, qmr, symmlq
@ (function handle), \ (backslash)
References
[1] Barrett, R., M. Berry, T. F. Chan, et al., Templates for the Solution of Linear
Systems: Building Blocks for Iterative Methods, SIAM, Philadelphia, 1994.
[2] Sonneveld, Peter, “CGS: A fast Lanczos-type solver for nonsymmetric linear
systems”, SIAM J. Sci. Stat. Comput., January 1989, Vol. 10, No. 1, pp. 36-52.
2-277
char
Purpose
2char
Create character array (string)
Syntax
S = char(X)
S = char(C)
S = char(t1,t2,t3...)
Description
S = char(X) converts the array X that contains positive integers representing
character codes into a MATLAB character array (the first 127 codes are
ASCII). The actual characters displayed depend on the character set encoding
for a given font. The result for any elements of X outside the range from 0 to
65535 is not defined (and may vary from platform to platform). Use double to
convert a character array into its numeric codes.
S = char(C) when C is a cell array of strings, places each element of C into the
rows of the character array s. Use cellstr to convert back.
S = char(t1,t2,t3,..) forms the character array S containing the text
strings T1,T2,T3,... as rows, automatically padding each string with blanks to
form a valid matrix. Each text parameter, Ti, can itself be a character array.
This allows the creation of arbitrarily large character arrays. Empty strings
are significant.
Remarks
Ordinarily, the elements of A are integers in the range 32:127, which are the
printable ASCII characters, or in the range 0:255, which are all 8-bit values.
For noninteger values, or values outside the range 0:255, the characters
printed are determined by fix(rem(A,256)).
Examples
To print a 3-by-32 display of the printable ASCII characters:
ascii
ascii
! ” #
@ A B
' a b
2-278
=
=
$
C
c
char(reshape(32:127,32,3)')
% & ' ( ) ∗+ , - . / 0 1 2 3 4 5 6 7 8 9 : ; < = > ?
D E F G H I J K L M N O P Q R S T U V W X Y Z [ \ ] ^ _
d e f g h i j k l m n o p q r s t u v w x y z { | } ~
char
See Also
cellstr, double, get, set, strings, strvcat, text
2-279
checkin
Purpose
2checkin
Graphical
Interface
As an alternative to the checkin function, use Source Control Check In in the
Editor, Simulink, or Stateflow File menu.
Syntax
checkin('filename','comments','string')
checkin({'filename1','filename2','filename3', ...},'comments',
'string')
checkin('filename','option','value', ...)
Description
checkin('filename','comments','string') checks in the file named
filename to the source control system. Use the full pathname for the filename.
Check file into source control system
You must save the file before checking it in. The file can be open or closed when
you use checkin. The string argument is a MATLAB string containing
check-in comments for the source control system. You must supply the
comments argument and 'string'.
checkin({'filename1','filename2','filename3', ...},'comments',
'string') checks in the files named filename1 through filenamen to the
source control system. Use the full pathnames for the files. Additional
arguments apply to all files checked in.
checkin('filename','option','value', ...) provides additional checkin
options. The option and value arguments are shown in the table below.
option
Argument
Purpose
value Argument
'force'
When set to on, filename is checked in
even if the file has not changed since it
was checked out. The default value for
force is off.
'on'
'off' (default)
'lock'
When set to on, filename remains
checked out. Comments are submitted.
The default value for lock is off.
'on'
'off' (default)
You can check in a file that you checked out in a previous MATLAB session or
that you checked out directly from your source control system.
2-280
checkin
Examples
Check in a File with Comments
Typing
checkin('/matlab/mymfiles/clock.m','comments','Adjustment for
Y2K')
checks in the file /matlab/mymfiles/clock.m to the source control system with
the comment Adjustment for Y2K.
Check in Multiple Files with Comments
Typing
checkin({'/matlab/mymfiles/clock.m', ...
'/matlab/mymfiles/calendar.m'},'comments','Adjustment for Y2K')
checks two files into the source control system using the same comment for
each.
Check a File in and Keep It Checked out
Typing
checkin('/matlab/mymfiles/clock.m','comments','Adjustment for
Y2K','lock','on')
checks the file /matlab/mymfiles/clock.m into the source control system and
keeps the file checked out.
See Also
checkout, cmopts, undocheckout
2-281
checkout
Purpose
2checkout
Graphical
Interface
As an alternative to the checkout function, use Source Control Check Out in
the Editor, Simulink, or Stateflow File menu.
Syntax
checkout('filename')
checkout({'filename1','filename2','filename3', ...})
checkout('filename','option','value', ...)
Description
checkout('filename') checks out the file named filename from the source
control system. filename must be the full pathname for the file. The file can be
open or closed when you use checkout.
Check file out of source control system
checkout({'filename1','filename2','filename3', ...}) checks out the
files named filename1 through filenamen from the source control system. Use
the full pathnames for the files. Additional arguments apply to all files checked
out.
checkout('filename','option','value', ...) provides additional
checkout options. The option and value arguments are shown in the following
table.
2-282
checkout
option
Argument
Purpose
value
Argument
'force'
When set to on, the checkout is forced,
even if you already have the file checked
out. This is effectively an undocheckout
followed by a checkout. When force is
set to off, you can’t check out the file if
you already have it checked out.
'on'
'off' (default)
'lock'
When set to on, the checkout gets the file,
allows you to write to it, and locks the file
so that access to the file for others is read
only. When set to off, the checkout gets a
read-only version of the file, allowing
another user to check out the file for
updating. With lock set to off, you don’t
have to check in a file after checking it
out.
'on' (default)
'off'
'revision'
Checks out the specified revision of the
file.
'version_num'
If you end the MATLAB session, the file remains checked out. You can check
in the file from within MATLAB during a later session, or directly from your
source control system.
Examples
Check out a File
Typing
checkout('/matlab/mymfiles/clock.m')
checks out the file /matlab/mymfiles/clock.m from the source control system.
2-283
checkout
Check out Multiple Files
Typing
checkout({'/matlab/mymfiles/clock.m',...
'/matlab/mymfiles/calendar.m'})
checks out /matlab/mymfiles/clock.m and
/matlab/mymfiles/calendar.m from the source control system.
Force a Checkout, Even If File Is Already Checked out
Typing
checkout('/matlab/mymfiles/clock.m','force','on')
checks out /matlab/mymfiles/clock.m even if clock.m is already checked out
to you.
Check out Specified Revision of File
Typing
checkout('/matlab/mymfiles/clock.m','revision','1.1')
checks out revision 1.1 of clock.m.
See Also
2-284
checkin, cmopts, undocheckout
chol
Purpose
2chol
Cholesky factorization
Syntax
R = chol(X)
[R,p] = chol(X)
Description
The chol function uses only the diagonal and upper triangle of X. The lower
triangular is assumed to be the (complex conjugate) transpose of the upper.
That is, X is Hermitian.
R = chol(X), where X is positive definite produces an upper triangular R so
that R'*R = X. If X is not positive definite, an error message is printed.
[R,p] = chol(X), with two output arguments, never produces an error
message. If X is positive definite, then p is 0 and R is the same as above. If X is
not positive definite, then p is a positive integer and R is an upper triangular
matrix of order q = p-1 so that R'*R = X(1:q,1:q).
Examples
The binomial coefficients arranged in a symmetric array create an interesting
positive definite matrix.
n = 5;
X = pascal(n)
X =
1
1
1
1
2
3
1
3
6
1
4
10
1
5
15
1
4
10
20
35
1
5
15
35
70
It is interesting because its Cholesky factor consists of the same coefficients,
arranged in an upper triangular matrix.
R = chol(X)
R =
1
1
0
1
0
0
0
0
0
0
1
2
1
0
0
1
3
3
1
0
1
4
6
4
1
2-285
chol
Destroy the positive definiteness (and actually make the matrix singular) by
subtracting 1 from the last element.
X(n,n) = X(n,n)-1
X =
1
1
1
1
1
1
2
3
4
5
1
3
6
10
15
1
4
10
20
35
1
5
15
35
69
Now an attempt to find the Cholesky factorization fails.
Algorithm
chol uses the the LAPACK subroutines DPOTRF (real) and ZPOTRF (complex).
References
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra,
J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen,
LAPACK User’s Guide
(http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition,
SIAM, Philadelphia, 1999.
See Also
cholinc, cholupdate
2-286
cholinc
Purpose
2cholinc
Sparse incomplete Cholesky and Cholesky-Infinity factorizations
Syntax
R = cholinc(X,droptol)
R = cholinc(X,options)
R = cholinc(X,'0')
[R,p] = cholinc(X,'0')
R = cholinc(X,'inf')
Description
cholinc produces two different kinds of incomplete Cholesky factorizations:
the drop tolerance and the 0 level of fill-in factorizations. These factors may be
useful as preconditioners for a symmetric positive definite system of linear
equations being solved by an iterative method such as pcg (Preconditioned
Conjugate Gradients). cholinc works only for sparse matrices.
R = cholinc(X,droptol) performs the incomplete Cholesky factorization of X,
with drop tolerance droptol.
R = cholinc(X,options) allows additional options to the incomplete
Cholesky factorization. options is a structure with up to three fields:
droptol
Drop tolerance of the incomplete factorization
michol
Modified incomplete Cholesky
rdiag
Replace zeros on the diagonal of R
Only the fields of interest need to be set.
droptol is a non-negative scalar used as the drop tolerance for the incomplete
Cholesky factorization. This factorization is computed by performing the
incomplete LU factorization with the pivot threshold option set to 0 (which
forces diagonal pivoting) and then scaling the rows of the incomplete upper
triangular factor, U, by the square root of the diagonal entries in that column.
Since the nonzero entries U(i,j) are bounded below by droptol*norm(X(:,j))
(see luinc), the nonzero entries R(i,j) are bounded below by the local drop
tolerance droptol*norm(X(:,j))/R(i,i).
Setting droptol = 0 produces the complete Cholesky factorization, which is
the default.
2-287
cholinc
michol stands for modified incomplete Cholesky factorization. Its value is
either 0 (unmodified, the default) or 1 (modified). This performs the modified
incomplete LU factorization of X and scales the returned upper triangular
factor as described above.
rdiag is either 0 or 1. If it is 1, any zero diagonal entries of the upper triangular
factor R are replaced by the square root of the local drop tolerance in an
attempt to avoid a singular factor. The default is 0.
R = cholinc(X,'0') produces the incomplete Cholesky factor of a real sparse
matrix that is symmetric and positive definite using no fill-in. The upper
triangular R has the same sparsity pattern as triu(X), although R may be zero
in some positions where X is nonzero due to cancellation. The lower triangle of
X is assumed to be the transpose of the upper. Note that the positive
definiteness of X does not guarantee the existence of a factor with the required
sparsity. An error message results if the factorization is not possible. If the
factorization is successful, R'*R agrees with X over its sparsity pattern.
[R,p] = cholinc(X,'0') with two output arguments, never produces an error
message. If R exists, p is 0. If R does not exist, then p is a positive integer and R
is an upper triangular matrix of size q-by-n where q = p-1. In this latter case,
the sparsity pattern of R is that of the q-by-n upper triangle of X. R'*R agrees
with X over the sparsity pattern of its first q rows and first q columns.
R = cholinc(X,'inf') produces the Cholesky-Infinity factorization. This
factorization is based on the Cholesky factorization, and additionally handles
real positive semi-definite matrices. It may be useful for finding a solution to
systems which arise in interior-point methods. When a zero pivot is
encountered in the ordinary Cholesky factorization, the diagonal of the
Cholesky-Infinity factor is set to Inf and the rest of that row is set to 0. This
forces a 0 in the corresponding entry of the solution vector in the associated
system of linear equations. In practice, X is assumed to be positive
semi-definite so even negative pivots are replaced with a value of Inf.
Remarks
2-288
The incomplete factorizations may be useful as preconditioners for solving
large sparse systems of linear equations. A single 0 on the diagonal of the upper
triangular factor makes it singular. The incomplete factorization with a drop
tolerance prints a warning message if the upper triangular factor has zeros on
the diagonal. Similarly, using the rdiag option to replace a zero diagonal only
cholinc
gets rid of the symptoms of the problem, but it does not solve it. The
preconditioner may not be singular, but it probably is not useful, and a warning
message is printed.
The Cholesky-Infinity factorization is meant to be used within interior-point
methods. Otherwise, its use is not recommended.
Examples
Example 1.
Start with a symmetric positive definite matrix, S.
S = delsq(numgrid('C',15));
S is the two-dimensional, five-point discrete negative Lapacian on the grid
generated by numgrid('C',15).
Compute the Cholesky factorization and the incomplete Cholesky factorization
of level 0 to compare the fill-in. Make S singular by zeroing out a diagonal entry
and compute the (partial) incomplete Cholesky factorization of level 0.
C = chol(S);
R0 = cholinc(S,'0');
S2 = S; S2(101,101) = 0;
[R,p] = cholinc(S2,'0');
Fill-in occurs within the bands of S in the complete Cholesky factor, but none
in the incomplete Cholesky factor. The incomplete factorization of the singular
S2 stopped at row p = 101 resulting in a 100-by-139 partial factor.
D1 = (R0'*R0).*spones(S)-S;
D2 = (R'*R).*spones(S2)-S2;
D1 has elements of the order of eps, showing that R0'*R0 agrees with S over its
sparsity pattern. D2 has elements of the order of eps over its first 100 rows and
first 100 columns, D2(1:100,:) and D2(:,1:100).
2-289
cholinc
S
C= chol(S)
0
0
20
20
40
40
60
60
80
80
100
100
120
120
140
0
140
50
100
nz = 643
R0=cholinc(S,’0’)
0
50
100
nz = 1557
Partial factor [R,p]=cholinc(S2,’0’)
0
0
20
20
40
60
40
80
60
100
80
120
140
100
0
0
50
100
nz = 391
50
100
nz = 290
Example 2.
The first subplot below shows that cholinc(S,0), the incomplete Cholesky
factor with a drop tolerance of 0, is the same as the Cholesky factor of S.
Increasing the drop tolerance increases the sparsity of the incomplete factors,
as seen below.
cholinc(S,0)
cholinc(S,1e−3)
0
0
20
20
40
40
60
60
80
80
100
100
120
120
140
0
50
100
nz = 1557
140
0
cholinc(S,1e−2)
2-290
cholinc(S,1e−1)
0
0
20
20
40
40
60
60
80
80
100
100
120
120
140
0
50
100
nz = 671
50
100
nz = 1211
140
0
50
100
nz = 391
cholinc
Unfortunately, the sparser factors are poor approximations, as is seen by the
plot of drop tolerance versus norm(R'*R-S,1)/norm(S,1) in the next figure.
Drop tolerance vs nnz(cholinc(S,droptol))
1500
1000
500
0 −4
10
−3
−2
10
10
−1
10
0
10
Drop tolerance vs norm(R’*R−S)/norm(S)
0
10
−1
10
−2
10
−3
10
−4
10
−4
10
−3
10
−2
10
−1
10
0
10
Example 3.
The Hilbert matrices have (i,j) entries 1/(i+j-1) and are theoretically positive
definite:
H3 = hilb(3)
H3 =
1.0000
0.5000
0.3333
0.5000
0.3333
0.2500
0.3333
0.2500
0.2000
R3 = chol(H3)
R3 =
1.0000
0.5000
0
0.2887
0
0
0.3333
0.2887
0.0745
In practice, the Cholesky factorization breaks down for larger matrices:
H20 = sparse(hilb(20));
[R,p] = chol(H20);
p =
14
2-291
cholinc
For hilb(20), the Cholesky factorization failed in the computation of row 14
because of a numerically zero pivot. You can use the Cholesky-Infinity
factorization to avoid this error. When a zero pivot is encountered, cholinc
places an Inf on the main diagonal, zeros out the rest of the row, and continues
with the computation:
Rinf = cholinc(H20,'inf');
In this case, all subsequent pivots are also too small, so the remainder of the
upper triangular factor is:
full(Rinf(14:end,14:end))
ans =
Inf
0
0
0
0
Inf
0
0
0
0
Inf
0
0
0
0
Inf
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
0
Inf
0
0
0
0
0
0
0
Inf
0
0
0
0
0
0
0
Inf
Limitations
cholinc works on square sparse matrices only. For cholinc(X,'0') and
cholinc(X,'inf'), X must be real.
Algorithm
R = cholinc(X,droptol) is obtained from [L,U] = luinc(X,options), where
options.droptol = droptol and options.thresh = 0. The rows of the
uppertriangular U are scaled by the square root of the diagonal in that row, and
this scaled factor becomes R.
R = cholinc(X,options) is produced in a similar manner, except the rdiag
option translates into the udiag option and the milu option takes the value of
the michol option.
R = cholinc(X,'0') is based on the “KJI” variant of the Cholesky
factorization. Updates are made only to positions which are nonzero in the
upper triangle of X.
R = cholinc(X,'inf') is based on the algorithm in Zhang [2].
2-292
cholinc
See Also
chol, luinc, pcg
References
[1] Saad, Yousef, Iterative Methods for Sparse Linear Systems, PWS Publishing
Company, 1996. Chapter 10, “Preconditioning Techniques.”
[2] Zhang, Yin, Solving Large-Scale Linear Programs by Interior-Point
Methods Under the MATLAB Environment, Department of Mathematics and
Statistics, University of Maryland Baltimore County, Technical Report
TR96-01
2-293
cholupdate
Purpose
2cholupdate
Rank 1 update to Cholesky factorization
Syntax
R1 = cholupdate(R,x)
R1 = cholupdate(R,x,'+')
R1 = cholupdate(R,x,'-')
[R1,p] = cholupdate(R,x,'-')
Description
R1 = cholupdate(R,x) where R = chol(A) is the original Cholesky
factorization of A, returns the upper triangular Cholesky factor of A + x*x',
where x is a column vector of appropriate length. cholupdate uses only the
diagonal and upper triangle of R. The lower triangle of R is ignored.
R1 = cholupdate(R,x,'+') is the same as R1 = cholupdate(R,x).
R1 = cholupdate(R,x,'-') returns the Cholesky factor of A - x*x'. An
error message reports when R is not a valid Cholesky factor or when the
downdated matrix is not positive definite and so does not have a Cholesky
factoriza- tion.
[R1,p] = cholupdate(R,x,'-') will not return an error message. If p is 0,
R1 is the Cholesky factor of A - x*x'. If p is greater than 0, R1 is the Cholesky
factor of the original A. If p is 1, cholupdate failed because the downdated
matrix is not positive definite. If p is 2, cholupdate failed because the upper
triangle of R was not a valid Cholesky factor.
Remarks
Example
cholupdate works only for full matrices.
A = pascal(4)
A =
1
1
1
1
R = chol(A)
1
2
3
4
2-294
1
3
6
10
1
4
10
20
cholupdate
R =
1
0
0
0
1
1
0
0
1
2
1
0
1
3
3
1
x = [0 0 0 1]';
This is called a rank one update to A since rank(x*x') is 1:
A + x*x'
ans =
1
1
1
1
1
2
3
4
1
3
6
10
1
4
10
21
Instead of computing the Cholesky factor with R1 = chol(A + x*x'), we can
use cholupdate:
R1 = cholupdate(R,x)
R1 =
1.0000
0
0
0
1.0000
1.0000
0
0
1.0000
2.0000
1.0000
0
1.0000
3.0000
3.0000
1.4142
Next destroy the positive definiteness (and actually make the matrix singular)
by subtracting 1 from the last element of A. The downdated matrix is:
A - x*x'
ans =
1
1
1
1
1
2
3
4
1
3
6
10
1
4
10
19
2-295
cholupdate
Compare chol with cholupdate:
R1 = chol(A-x*x')
??? Error using ==> chol
Matrix must be positive definite.
R1 = cholupdate(R,x,'-')
??? Error using ==> cholupdate
Downdated matrix must be positive definite.
However, subtracting 0.5 from the last element of A produces a positive
definite matrix, and we can use cholupdate to compute its Cholesky factor:
x = [0 0 0 1/sqrt(2)]';
R1 = cholupdate(R,x,'-')
R1 =
1.0000
1.0000
1.0000
0
1.0000
2.0000
0
0
1.0000
0
0
0
1.0000
3.0000
3.0000
0.7071
Algorithm
cholupdate uses the algorithms from the LINPACK subroutines ZCHUD and
ZCHDD. cholupdate is useful since computing the new Cholesky factor from
scratch is an O ( N 3 ) algorithm, while simply updating the existing factor in
this way is an O ( N 2 ) algorithm.
See Also
chol, qrupdate
References
[1] Dongarra, J.J., J.R. Bunch, C.B. Moler, and G.W. Stewart, LINPACK Users'
Guide, SIAM, Philadelphia, 1979.
2-296
circshift
Purpose
2circshift
Shift array circularly
Syntax
B = circshift(A,shiftsize)
Description
B = circshift(A,shiftsize) circularly shifts the values in the array, A, by
shiftsize elements. shiftsize is a vector of integer scalars where the n-th
element specifies the shift amount for the n-th dimension of array A. If an
element in shiftsize is positive, the values of A are shifted down (or to the
right). If it is negative, the values of A are shifted up (or to the left). If it is 0,
the values in that dimension are not shifted.
Example
Circularly shift first dimension values down by 1.
A = [ 1 2 3;4 5 6; 7 8 9]
A =
1
2
3
4
5
6
7
8
9
B = circshift(A,1)
B =
7
8
9
1
2
3
4
5
6
Circularly shift first dimension values down by 1 and second dimension values
to the left by 1.
B = circshift(A,[1 -1]);
B =
8
9
7
2
3
1
5
6
4
See Also
fftshift, shiftdim
2-297
cla
Purpose
2cla
Clear current axes
Syntax
cla
cla reset
Description
cla deletes from the current axes all graphics objects whose handles are not
hidden (i.e., their HandleVisibility property is set to on).
cla reset deletes from the current axes all graphics objects regardless of the
setting of their HandleVisibility property and resets all axes properties,
except Position and Units, to their default values.
Remarks
The cla command behaves the same way when issued on the command line as
it does in callback routines – it does not recognize the HandleVisibility
setting of callback. This means that when issued from within a callback
routine, cla deletes only those objects whose HandleVisibility property is set
to on.
See Also
clf, hold, newplot, reset
“Axes Operations” for related functions
2-298
clabel
Purpose
Syntax
2clabel
Contour plot elevation labels
clabel(C,h)
clabel(C,h,v)
clabel(C,h,'manual')
clabel(C)
clabel(C,v)
clabel(C,'manual')
Description
The clabel function adds height labels to a two-dimensional contour plot.
clabel(C,h) rotates the labels and inserts them in the contour lines. The
function inserts only those labels that fit within the contour, depending on the
size of the contour.
clabel(C,h,v) creates labels only for those contour levels given in vector v,
then rotates the labels and inserts them in the contour lines.
clabel(C,h,'manual') places contour labels at locations you select with a
mouse. Press the left mouse button (the mouse button on a single-button
mouse) or the space bar to label a contour at the closest location beneath the
center of the cursor. Press the Return key while the cursor is within the figure
window to terminate labeling. The labels are rotated and inserted in the
contour lines.
clabel(C) adds labels to the current contour plot using the contour structure
C output from contour. The function labels all contours displayed and
randomly selects label positions.
clabel(C,v) labels only those contour levels given in vector v.
clabel(C,'manual') places contour labels at locations you select with a
mouse.
Remarks
When the syntax includes the argument h, this function rotates the labels and
inserts them in the contour lines (see Example). Otherwise, the labels are
displayed upright and a '+' indicates which contour line the label is
annotating.
2-299
clabel
Examples
Generate, draw, and label a simple contour plot.
[x,y] = meshgrid(–2:.2:2);
z = x.^exp(–x.^2–y.^2);
[C,h] = contour(x,y,z);
clabel(C,h);
2
1.5
0.6
−0.5
0.6
0.2
8
0.
0.4
0.6
0.4
0.2
1
0.6
−1
0
1
−1.5
1
0.2
See Also
0.8
−2
−2
−
0. 9.86
2 9e
−1
7
0.4
0.6
1
−1.5
0.8
−1
0.4
0.8
−0.5
−0.2
0
0.2
−9.869e−17
0.5
8
2
0.
−0.
1
0.5
1
1.5
2
contour, contourc, contourf
“Annotating Plots” for related functions
Drawing Text in a Box for an example that illustrates the use of contour labels
2-300
class
Purpose
2class
Create object or return class of object
Syntax
str
obj
obj
obj
Description
str = class(object) returns a string specifying the class of object.
=
=
=
=
class(object)
class(s,'class_name')
class(s,'class_name',parent1,parent2...)
class(struct([]),'class_name',parent1,parent2...)
The following table lists the object class names that may be returned. All
except the last one are MATLAB classes.
logical
Logical array of true and false values
char
Characters array
int8
8-bit signed integer array
uint8
8-bit unsigned integer array
int16
16-bit signed integer array
uint16
16-bit unsigned integer array
int32
32-bit signed integer array
uint32
32-bit unsigned integer array
int64
64-bit signed integer array
uint64
64-bit unsigned integer array
single
Single-precision floating point number array
double
Double-precision floating point number array
cell
Cell array
struct
Structure array
function handle
Array of values for calling functions indirectly
'class_name'
Custom MATLAB object class or Java class
obj = class(s,'class_name') creates an object of MATLAB class
'class_name' using structure s as a template. This syntax is valid only in a
2-301
class
function named class_name.m in a directory named @class_name (where
'class_name' is the same as the string passed into class).
obj = class(s,'class_name',parent1,parent2,...) creates an object of
MATLAB class 'class_name' that inherits the methods and fields of the
parent objects parent1, parent2, and so on. Structure s is used as a template
for the object.
obj = class(struct([]),'class_name',parent1,parent2,...) creates an
object of MATLAB class 'class_name' that inherits the methods and fields of
the parent objects parent1, parent2, and so on. Specifying the empty
structure, struct([]), as the first argument ensures that the object created
contains no fields other than those that are inherited from the parent objects.
Examples
To return in nameStr the name of the class of Java object j
nameStr = class(j)
To create a user-defined MATLAB object of class polynom
p = class(p,'polynom')
See Also
inferiorto, isa, superiorto
The “MATLAB Classes and Objects” and the “Calling Java from MATLAB”
chapters in Programming and Data Types.
2-302
clc
Purpose
2clc
Graphical
Interface
As an alternative to the clc function, use Clear Command Window in the
MATLAB desktop Edit menu.
Syntax
clc
Description
clc clears all input and output from the Command Window display, giving you
a “clean screen.”
Clear Command Window
After using clc, you cannot use the scroll bar to see the history of functions,
but still can use the up arrow to recall statements from the command history.
Examples
Use clc in an M-file to always display output in the same starting position on
the screen.
See Also
clear, clf, close, home
2-303
clear
Purpose
2clear
Graphical
Interface
As an alternative to the clear function, use Clear Workspace in the MATLAB
desktop Edit menu, or in the context menu in the Workspace browser.
Syntax
clear
clear name
clear name1 name2 name3 ...
clear global name
clear keyword
clear('name1','name2','name3',...)
Description
clear removes all variables from the workspace. This frees up system memory.
Remove items from workspace, freeing up system memory
clear name removes just the M-file or MEX-file function or variable name from
the workspace. You can use wildcards (*) to remove items selectively. For
example, clear my* removes any variables whose names begin with the string
my. It removes debugging breakpoints in M-files and reinitializes persistent
variables, since the breakpoints for a function and persistent variables are
cleared whenever the M-file is changed or cleared. If name is global, it is
removed from the current workspace, but left accessible to any functions
declaring it global. If name has been locked by mlock, it remains in memory.
Use a partial path to distinguish between different overloaded versions of a
function. For example, clear inline/display clears only the display method
for inline objects, leaving any other implementations in memory.
clear name1 name2 name3 ... removes name1, name2, and name3 from the
workspace.
clear global name removes the global variable name. If name is global, clear
name removes name from the current workspace, but leaves it accessible to any
functions declaring it global. Use clear global name to completely remove a
global variable.
2-304
clear
clear keyword clears the items indicated by keyword.
Keyword
Items Cleared
all
Removes all variables, functions, and MEX-files from
memory, leaving the workspace empty. Using clear all
removes debugging breakpoints in M-files and
reinitializes persistent variables, since the breakpoints
for a function and persistent variables are cleared
whenever the M-file is changed or cleared. When issued
from the Command Window prompt, also removes the
Java packages import list.
classes
The same as clear all, but also clears MATLAB class
definitions. If any objects exist outside the workspace
(for example, in user data or persistent variables in a
locked M-file), a warning is issued and the class
definition is not cleared. Issue a clear classes
function if the number or names of fields in a class are
changed.
functions
Clears all the currently compiled M-functions and
MEX-functions from memory. Using clear function
removes debugging breakpoints in the function M-file
and reinitializes persistent variables, since the
breakpoints for a function and persistent variables are
cleared whenever the M-file is changed or cleared.
global
Clears all global variables from the workspace.
import
Removes the Java packages import list. It can only be
issued from the Command Window prompt. It cannot be
used in a function.
variables
Clears all variables from the workspace.
clear('name1','name2','name3',...) is the function form of the syntax. Use
this form when the variable name or function name is stored in a string.
2-305
clear
Remarks
When you use clear in a function, it has the following effect on items in your
function and base workspaces:
• clear name—If name is the name of a function, the function is cleared in both
the function workspace and in your base workspace.
• clear functions—All functions are cleared in both the function workspace
and in your base workspace.
• clear global—All global variables are cleared in both the function
workspace and in your base workspace.
• clear all—All functions, global variables, and classes are cleared in both
the function workspace and in your base workspace.
Limitations
clear does not affect the amount of memory allocated to the MATLAB process
under UNIX.
Examples
Given a workspace containing the following variables
Name
Size
c
frame
gbl1
gbl2
xint
3x4
1x1
1x1
1x1
1x1
Bytes
1200
8
8
1
Class
cell array
java.awt.Frame
double array (global)
double array (global)
int8 array
you can clear a single variable, xint, by typing
clear xint
To clear all global variables, type
clear global
whos
Name
Size
c
frame
2-306
3x4
1x1
Bytes
1200
Class
cell array
java.awt.Frame
clear
To clear all compiled M- and MEX-functions from memory, type clear
functions. In the case shown below, clear functions was unable to clear one
M-file function from memory, testfun, because the function is locked.
clear functions
inmem
ans =
'testfun'
mislocked testfun
ans =
1
% Attempt to clear all functions.
% One M-file function remains in memory.
% This function is locked in memory.
Once you unlock the function from memory, you can clear it.
munlock testfun
clear functions
inmem
ans =
Empty cell array: 0-by-1
See Also
clc, close, import, mlock, munlock, pack, persistent, who, whos
2-307
clear (serial)
Purpose
2clear (serial)
Remove a serial port object from the MATLAB workspace
Syntax
clear obj
Arguments
obj
Description
clear obj removes obj from the MATLAB workspace.
Remarks
If obj is connected to the device and it is cleared from the workspace, then obj
remains connected to the device. You can restore obj to the workspace with the
instrfind function. A serial port object connected to the device has a Status
property value of open.
A serial port object or an array of serial port objects.
To disconnect obj from the device, use the fclose function. To remove obj from
memory, use the delete function. You should remove invalid serial port objects
from the workspace with clear.
If you use the help command to display help for clear, then you need to supply
the pathname shown below.
help serial/private/clear
Example
This example creates the serial port object s, copies s to a new variable scopy,
and clears s from the MATLAB workspace. s is then restored to the workspace
with instrfind and is shown to be identical to scopy.
s = serial('COM1');
scopy = s;
clear s
s = instrfind;
isequal(scopy,s)
ans =
1
See Also
Functions
delete, fclose, instrfind, isvalid
Properties
Status
2-308
clf
Purpose
2clf
Clear current figure window
Syntax
clf
clf reset
Description
clf deletes from the current figure all graphics objects whose handles are not
hidden (i.e., their HandleVisibility property is set to on).
clf reset deletes from the current figure all graphics objects regardless of the
setting of their HandleVisibility property and resets all figure properties,
except Position, Units, PaperPosition, and PaperUnits to their default
values.
Remarks
The clf command behaves the same way when issued on the command line as
it does in callback routines – it does not recognize the HandleVisibility
setting of callback. This means that when issued from within a callback
routine, clf deletes only those objects whose HandleVisibility property is set
to on.
See Also
cla, clc, hold, reset
“Figure Windows” for related functions
2-309
clipboard
Purpose
2clipboard
Graphical
Interface
As an alternative to clipboard, use the Import Wizard. To use the Import
Wizard to copy data from the clipboard, select Paste Special from the Edit
menu.
Syntax
clipboard('copy',data)
str = clipboard('paste')
data = clipboard('pastespecial')
Description
clipboard('copy', data) sets the clipboard contents to data. If data is not a
character array, clipboard uses mat2str to convert it to a string.
Copy and paste strings to and from the system clipboard.
str = clipboard('paste') returns the current contents of the clipboard as a
string or as an empty string (' '), if the current clipboard content cannot be
converted to a string.
data = clipboard('pastespecial') returns the current contents of the
clipboard as an array using uiimport.
Note Requires an active X display on Unix and Java elsewhere.
See Also
2-310
load, uiimport
clock
Purpose
2clock
Current time as a date vector
Syntax
c = clock
Description
c = clock returns a 6-element date vector containing the current date and
time in decimal form:
c = [year month day hour minute seconds]
The first five elements are integers. The seconds element is accurate to several
digits beyond the decimal point. The statement fix(clock) rounds to integer
display format.
See Also
cputime, datenum, datevec, etime, tic, toc
2-311
close
Purpose
2close
Delete specified figure
Syntax
close
close(h)
close name
close all
close all hidden
status = close(...)
Description
close deletes the current figure or the specified figure(s). It optionally returns
the status of the close operation.
close deletes the current figure (equivalent to close(gcf)).
close(h) deletes the figure identified by h. If h is a vector or matrix, close
deletes all figures identified by h.
close name deletes the figure with the specified name.
close all deletes all figures whose handles are not hidden.
close all hidden deletes all figures including those with hidden handles.
status = close(...) returns 1 if the specified windows have been deleted
and 0 otherwise.
Remarks
The close function works by evaluating the specified figure’s
CloseRequestFcn property with the statement:
eval(get(h,'CloseRequestFcn'))
The default CloseRequestFcn, closereq, deletes the current figure using
delete(get(0,'CurrentFigure')). If you specify multiple figure handles,
close executes each figure’s CloseRequestFcn in turn. If MATLAB encounters
an error that terminates the execution of a CloseRequestFcn, the figure is not
deleted. Note that using your computer’s window manager (i.e., the Close
menu item) also calls the figure’s CloseRequestFcn.
If a figure’s handle is hidden (i.e., the figure’s HandleVisibility property is set
to callback or off and the root ShowHiddenHandles property is set on), you
2-312
close
must specify the hidden option when trying to access a figure using the all
option.
To delete all figures unconditionally, use the statements:
set(0,'ShowHiddenHandles','on')
delete(get(0,'Children'))
The delete function does not execute the figure’s CloseRequestFcn; it simply
deletes the specified figure.
The figure CloseRequestFcn allows you to either delay or abort the closing of
a figure once the close function has been issued. For example, you can display
a dialog box to see if the user really wants to delete the figure or save and clean
up before closing.
See Also
delete, figure, gcf
The figure HandleVisibility property
The root ShowHiddenHandles property
“Figure Windows” for related functions
2-313
close
Purpose
2close
Close Audio Video Interleaved (AVI) file
Syntax
aviobj = close(aviobj)
Description
aviobj = close(aviobj) finishes writing and closes the AVI file associated
with aviobj, which is an AVI file object, created using the avifile function.
See Also
2-314
avifile, addframe, movie2avi
closereq
Purpose
2closereq
Default figure close request function
Syntax
closereq
Description
closereq delete the current figure.
See Also
The figure CloseRequestFcn property
“Figure Windows” for related functions
2-315
cmopts
Purpose
2cmopts
Graphical
Interface
As an alternative to cmopts, use preferences. Select File -> Preferences in the
MATLAB desktop, and then select General -> Source Control.
Syntax
cmopts
Description
cmopts returns the name of the source control system you selected using
Get name of source control system
preferences, which is one of the following:
clearcase
customverctrl
pvcs
rcs
sourcesafe
If you have not selected a source control system, cmopts returns
none
Specifying a Source Control System
To specify the source control system:
1 From the MATLAB Editor window or from a Simulink or Stateflow model
window, select File -> Preferences.
The Preferences dialog box opens.
2 In the left pane, click the + for General, and then select Source Control.
The currently selected system is shown.
3 Select the system you want to use from the Source control system list.
4 Click OK.
For more information, see source control preferences.
Examples
Type cmopts and MATLAB returns rcs, meaning the source control system
specified in preferences is RCS.
See Also
checkin, checkout, customverctrl
2-316
colamd
Purpose
2colamd
Column approximate minimum degree permutation
Syntax
p = colamd(S)
p = colamd(S,knobs)
[p,stats] = colamd(S)
[p,stats] = colamd(S,knobs)
Description
p = colamd(S) returns the column approximate minimum degree
permutation vector for the sparse matrix S. For a non-symmetric matrix S,
S(:,p) tends to have sparser LU factors than S. The Cholesky factorization of
S(:,p)' * S(:,p) also tends to be sparser than that of S'*S.
knobs is a two-element vector. If S is m-by-n, then rows with more than
(knobs(1))*n entries are ignored. Columns with more than (knobs(2))*m
entries are removed prior to ordering, and ordered last in the output
permutation p. If the knobs parameter is not present, then
knobs(1) = knobs(2) = spparms('wh_frac').
stats is an optional vector that provides data about the ordering and the
validity of the matrix S.
stats(1)
Number of dense or empty rows ignored by colamd
stats(2)
Number of dense or empty columns ignored by colamd
stats(3)
Number of garbage collections performed on the internal data
structure used by colamd (roughly of size
2.2*nnz(S) + 4*m + 7*n integers)
stats(4)
0 if the matrix is valid, or 1 if invalid
stats(5)
Rightmost column index that is unsorted or contains duplicate
entries, or 0 if no such column exists
stats(6)
Last seen duplicate or out-of-order row index in the column
index given by stats(5), or 0 if no such row index exists
stats(7)
Number of duplicate and out-of-order row indices
Although, MATLAB built-in functions generate valid sparse matrices, a user
may construct an invalid sparse matrix using the MATLAB C or Fortran APIs
and pass it to colamd. For this reason, colamd verifies that S is valid:
2-317
colamd
• If a row index appears two or more times in the same column, colamd ignores
the duplicate entries, continues processing, and provides information about
the duplicate entries in stats(4:7).
• If row indices in a column are out of order, colamd sorts each column of its
internal copy of the matrix S (but does not repair the input matrix S),
continues processing, and provides information about the out-of-order
entries in stats(4:7).
• If S is invalid in any other way, colamd cannot continue. It prints an error
message, and returns no output arguments (p or stats) .
The ordering is followed by a column elimination tree post-ordering.
Note colamd tends to be faster than colmmd and tends to return a better
ordering.
See Also
colmmd, colperm, spparms, symamd, symmmd, symrcm
References
[1] The authors of the code for colamd are Stefan I. Larimore and Timothy A.
Davis ([email protected]), University of Florida. The algorithm was
developed in collaboration with John Gilbert, Xerox PARC, and Esmond Ng,
Oak Ridge National Laboratory. Sparse Matrix Algorithms Research at the
University of Florida: http://www.cise.ufl.edu/research/sparse/
2-318
colmmd
Purpose
2colmmd
Sparse column minimum degree permutation
Syntax
p = colmmd(S)
Description
p = colmmd(S) returns the column minimum degree permutation vector for
the sparse matrix S. For a nonsymmetric matrix S, this is a column
permutation p such that S(:,p) tends to have sparser LU factors than S.
The colmmd permutation is automatically used by \ and / for the solution of
nonsymmetric and symmetric indefinite sparse linear systems.
Use spparms to change some options and parameters associated with heuristics
in the algorithm.
Algorithm
The minimum degree algorithm for symmetric matrices is described in the
review paper by George and Liu [1]. For nonsymmetric matrices, the MATLAB
minimum degree algorithm is new and is described in the paper by Gilbert,
Moler, and Schreiber [2]. It is roughly like symmetric minimum degree for
A'*A, but does not actually form A'*A.
Each stage of the algorithm chooses a vertex in the graph of A'*A of lowest
degree (that is, a column of A having nonzero elements in common with the
fewest other columns), eliminates that vertex, and updates the remainder of
the graph by adding fill (that is, merging rows). If the input matrix S is of size
m-by-n, the columns are all eliminated and the permutation is complete after n
stages. To speed up the process, several heuristics are used to carry out
multiple stages simultaneously.
Examples
The Harwell-Boeing collection of sparse matrices and the MATLAB demos
directory include a test matrix WEST0479. It is a matrix of order 479 resulting
from a model due to Westerberg of an eight-stage chemical distillation column.
The spy plot shows evidence of the eight stages. The colmmd ordering
scrambles this structure.
load west0479
A = west0479;
p = colmmd(A);
spy(A)
spy(A(:,p))
2-319
colmmd
A
A(:,p)
0
0
100
100
200
200
300
300
400
400
0
100
200
300
nz = 1887
400
0
100
200
300
nz = 1887
400
Comparing the spy plot of the LU factorization of the original matrix with that
of the reordered matrix shows that minimum degree reduces the time and
storage requirements by better than a factor of 2.8. The nonzero counts are
16777 and 5904, respectively.
spy(lu(A))
spy(lu(A(:,p)))
lu(A)
0
100
100
200
200
300
300
400
400
0
2-320
lu(A(:,p))
0
100
200
300
nz = 16777
400
0
100
200
300
nz = 5904
400
colmmd
See Also
colamd, colperm, lu, spparms, symamd, symmmd, symrcm
The arithmetic operator \
References
[1] George, Alan and Liu, Joseph, “The Evolution of the Minimum Degree
Ordering Algorithm,” SIAM Review, 1989, 31:1-19.
[2] Gilbert, John R., Cleve Moler, and Robert Schreiber, “Sparse Matrices in
MATLAB: Design and Implementation,” SIAM Journal on Matrix Analysis
and Applications 13, 1992, pp. 333-356.
2-321
colorbar
Purpose
2colorbar
Display colorbar showing the color scale
Syntax
colorbar
colorbar('vert')
colorbar('horiz')
colorbar(h)
h = colorbar(...)
colorbar(...,'peer',axes_handle)
Description
The colorbar function displays the current colormap in the current figure and
resizes the current axes to accommodate the colorbar.
colorbar updates the most recently created colorbar or, when the current axes
does not have a colorbar, colorbar adds a new vertical colorbar.
colorbar('vert') adds a vertical colorbar to the current axes.
colorbar('horiz') adds a horizontal colorbar to the current axes.
colorbar(h) uses the axes h to create the colorbar. The colorbar is horizontal
if the width of the axes is greater than its height, as determined by the axes
Position property.
h = colorbar(...) returns a handle to the colorbar, which is an axes graphics
object.
colorbar(...,'peer',axes_handle) creates a colorbar associated with the
axes axes_handle instead of the current axes.
Remarks
colorbar works with two-dimensional and three-dimensional plots.
Examples
Display a colorbar beside the axes.
surf(peaks(30))
colormap cool
2-322
colorbar
colorbar
8
6
10
8
4
6
4
2
2
0
−2
0
−4
−6
−2
−8
30
25
30
20
15
20
15
10
10
5
5
0
See Also
−4
25
−6
0
colormap
“Color Operations” for related functions
2-323
colordef
Purpose
2colordef
Sets default property values to display different color schemes
Syntax
colordef white
colordef black
colordef none
colordef(fig,color_option)
h = colordef('new',color_option)
Description
colordef enables you to select either a white or black background for graphics
display. It sets axis lines and labels to show up against the background color.
colordef white sets the axis background color to white, the axis lines and
labels to black, and the figure background color to light gray.
colordef black sets the axis background color to black, the axis lines and
labels to white, and the figure background color to dark gray.
colordef none sets the figure coloring to that used by MATLAB Version 4
(essentially a black background).
colordef(fig,color_option) sets the color scheme of the figure identified by
the handle fig to the color option 'white', 'black', or 'none'.
h = colordef('new',color_option) returns the handle to a new figure
created with the specified color options (i.e., 'white', 'black', or 'none').
Remarks
colordef affects only subsequently drawn figures, not those currently on the
display. This is because colordef works by setting default property values (on
the root or figure level). You can list the currently set default values on the root
level with the statement:
get(0,'defaults')
You can remove all default values using the reset command:
reset(0)
See the get and reset references pages for more information.
See Also
2-324
whitebg
colordef
“Color Operations” for related functions
2-325
colormap
Purpose
2colormap
Set and get the current colormap
Syntax
colormap(map)
colormap('default')
cmap = colormap
Description
A colormap is an m-by-3 matrix of real numbers between 0.0 and 1.0. Each row
is an RGB vector that defines one color. The kth row of the colormap defines the
k-th color, where map(k,:) = [r(k) g(k) b(k)]) specifies the intensity of red,
green, and blue.
colormap(map) sets the colormap to the matrix map. If any values in map are
outside the interval [0 1], MATLAB returns the error: Colormap must have
values in [0,1].
colormap('default') sets the current colormap to the default colormap.
cmap = colormap; retrieves the current colormap. The values returned are in
the interval [0 1].
Specifying Colormaps
M-files in the color directory generate a number of colormaps. Each M-file
accepts the colormap size as an argument. For example,
colormap(hsv(128))
creates an hsv colormap with 128 colors. If you do not specify a size, MATLAB
creates a colormap the same size as the current colormap.
Supported Colormaps
MATLAB supports a number of colormaps.
• autumn varies smoothly from red, through orange, to yellow.
• bone is a grayscale colormap with a higher value for the blue component.
This colormap is useful for adding an “electronic” look to grayscale images.
• colorcube contains as many regularly spaced colors in RGB colorspace as
possible, while attempting to provide more steps of gray, pure red, pure
green, and pure blue.
2-326
colormap
• cool consists of colors that are shades of cyan and magenta. It varies
smoothly from cyan to magenta.
• copper varies smoothly from black to bright copper.
• flag consists of the colors red, white, blue, and black. This colormap
completely changes color with each index increment.
• gray returns a linear grayscale colormap.
• hot varies smoothly from black, through shades of red, orange, and yellow,
to white.
• hsv varies the hue component of the hue-saturation-value color model. The
colors begin with red, pass through yellow, green, cyan, blue, magenta, and
return to red. The colormap is particularly appropriate for displaying
periodic functions. hsv(m) is the same as hsv2rgb([h ones(m,2)]) where h
is the linear ramp, h = (0:m–1)'/m.
• jet ranges from blue to red, and passes through the colors cyan, yellow, and
orange. It is a variation of the hsv colormap. The jet colormap is associated
with an astrophysical fluid jet simulation from the National Center for
Supercomputer Applications. See the “Examples” section.
• lines produces a colormap of colors specified by the axes ColorOrder
property and a shade of gray.
• pink contains pastel shades of pink. The pink colormap provides sepia tone
colorization of grayscale photographs.
• prism repeats the six colors red, orange, yellow, green, blue, and violet.
• spring consists of colors that are shades of magenta and yellow.
• summer consists of colors that are shades of green and yellow.
• white is an all white monochrome colormap.
• winter consists of colors that are shades of blue and green.
Examples
The images and colormaps demo, imagedemo, provides an introduction to
colormaps. Select Color Spiral from the menu. This uses the pcolor function
to display a 16-by-16 matrix whose elements vary from 0 to 255 in a rectilinear
spiral. The hsv colormap starts with red in the center, then passes through
yellow, green, cyan, blue, and magenta before returning to red at the outside
end of the spiral. Selecting Colormap Menu gives access to a number of other
colormaps.
2-327
colormap
The rgbplot function plots colormap values. Try rgbplot(hsv),
rgbplot(gray), and rgbplot(hot).
The following commands display the flujet data using the jet colormap.
load flujet
image(X)
colormap(jet)
The demos directory contains a CAT scan image of a human spine. To view the
image, type the following commands:
load spine
image(X)
2-328
colormap
colormap bone
Algorithm
Each figure has its own Colormap property. colormap is an M-file that sets and
gets this property.
See Also
brighten, caxis, colormapeditor, colorbar, contrast, hsv2rgb, pcolor,
rgb2hsv, rgbplot
The Colormap property of figure graphics objects.
“Color Operations” for related functions
Coloring Mesh and Surface Plots for more information about colormaps and
other coloring methods.
2-329
colormapeditor
Purpose
2colormapeditor
Start colormap editor
Syntax
colormapeditor
Description
colormapeditor displays the current figure’s colormap as a strip of
rectangular cells in the colormap editor. Node pointers are colored cells below
the colormap strip that indicate points in the colormap where the rate of the
variation of R, G, and B values change. You can also work in the HSV
colorspace by setting the Interpolating Colorspace selector to HSV.
You can also start the colormap editor by selecting Colormap from the Edit
menu.
Node Pointer Operations
You can select and move node pointers to change a range of colors in the
colormap. The color of a node pointer remains constant as you move it, but the
colormap changes by linearly interpolating the RGB values between nodes.
Change the color at a node by double-clicking the node pointer. MATLAB
displays a color picker from which you can select a new color. After you select
a new color at a node, MATLAB reinterpolates the colors in between nodes.
2-330
Operation
How to Perform
Add a node
Click below the corresponding cell in the colormap
strip
Select a node
Left-click on the node
Select multiple
nodes
Adjacent: left-click on first node, Shift+click on the
last node
Nonadjacent: left-click on first node, Ctrl+click on
subsequent nodes
Move a node
Select and drag with the mouse or select and use
the left and right arrow keys.
colormapeditor
Operation
How to Perform
Move multiple
nodes
Select multiple nodes and use the left and right
arrow keys to move nodes as a group. Movement
stops when one of the selected nodes hits an
unselected node or an end node.
Delete a node
Select the node and then press the Delete key, or
select Delete from the Edit menu, or type Ctrl+x.
Delete multiple
nodes
Select the nodes and then press the Delete key, or
select Delete from the Edit menu, or type Ctrl+x.
Display color picker
for a node
Double click on the node pointer.
Current Color Info
When you put the mouse over a color cell or node pointer, the colormap editor
displays the following information about that colormap element:
• The element’s index in the colormap
• The value from the graphics object color data that is mapped to the node’s
color (i.e., data from the CData property of any image, patch, or surface
objects in the figure)
• The color’s RGB and HSV color value
2-331
colormapeditor
Colormap index for
color cell
Object’s CData for
color cell
RGB and HSV
values of selected
colormap element
Interpolating Colorspace
The colorspace determines what values are used to calculate the colors of cells
between nodes. For example, in the RGB colorspace, internode colors are
calculated by linearly interpolating the red, green, and blue intensity values
from one node to the next. Switching to the HSV colorspace causes the
colormap editor to recalculate the colors between nodes using the hue,
saturation, and value components of the color definition.
Note that when you switch from one colorspace to another, the color editor
preserves the number, color, and location of the node pointers, which can cause
the colormap to change.
Interpolating in HSV: Since hue is conceptually mapped about a color circle,
the interpolation between hue values can be ambiguous. To minimize this
ambiguity, the interpolation uses the shortest distance around the circle. For
example, interpolating between two nodes, one with at hue of 2 (slightly orange
red) and another with a hue of 356 (slightly magenta red), does not result in
hues 3,4,5...353,354,355 (orange/red-yellow-green-cyan-blue-magenta/red).
2-332
colormapeditor
Taking the shortest distance around the circle gives 357,358,1,2
(orange/red-red-magenta/red).
Color Data Min and Max
The Color Data Min and Color Data Max text fields enable you to specify
values for the axes CLim property. These values change the mapping of object
color data (the CData property of images, patches, and surfaces) to the
colormap. See Axes Color Limits — The Clim Property for discussion and
examples of how to use this property.
Examples
This example modifies a default MATLAB colormap so that ranges of data
values are displayed in specific ranges of color. The graph is a slice plane
illustrating a cross section of fluid flow through a jet nozzle. See the slice
reference page for more information on this type of graph.
Example Objectives
The objectives are as follows:
• Regions of flow from left to right (positive data) are mapped to colors from
yellow through orange to dark red. Yellow is slowest and dark red is the
fastest moving fluid.
• Regions that have a speed close to zero are colored green.
• Regions where the fluid is actually moving right to left (negative data) are
shades of blue (darker blue is faster).
The following picture shows the desired coloring of the slice plane. The colorbar
shows the data to color mapping.
2-333
colormapeditor
Running the Example
Note If you are viewing this documentation in the MATLAB help browser,
you can display the graph used in this example by running this M-file from
the MATLAB editor (select Run from the Debug menu).
Click Run Demo if you want to run a demonstration of the example.
Initially, the default colormap (jet) colored the slice plane, as illustrated in the
following picture. Note that this example uses a colormap that is 48 elements
to display wider bands of color (the default is 64 elements).
2-334
colormapeditor
1 Start the colormap editor using the colormapeditor command. The color
map editor displays the current figure’ s colormap, as shown in the following
picture.
2-335
colormapeditor
2 Since we want the regions of left-to-right flow (positive speed) to range from
yellow to dark red, we can delete the cyan node pointer. To do this, first
select it by clicking with the left mouse button and press Delete. The
colormap now looks like this.
2-336
colormapeditor
The Immediate Apply box is checked so the graph displays the results of
the changes made to the colormap.
2-337
colormapeditor
3 We want the fluid speed values around zero to stand out, so we need to find
the color cell where the negative-to-positive transition occurs. Dragging the
cursor over the color strip enables you to read the data values in the
Current Color Info panel.
In this case, cell 10 is the first positive value, so we click below that cell and
create a node pointer. Double-clicking on the node pointer displays the color
picker. Set the color of this node to green.
2-338
colormapeditor
The graph continues to update to the modified colormap.
2-339
colormapeditor
4 In the current state, the colormap colors are interpolated from the green
node to the yellowish node about 20 cells away. We actually want only the
single cell that is centered around zero to be colored green. To limit the color
green to one cell, move the blue and yellow node pointers next to the green
pointer.
5 Before making further adjustments to the colormap, we need to move the
green cell so that it is centered around zero. Use the colorbar to locate the
green cell.
2-340
colormapeditor
Note that green cell is not
centered around zero.
To recenter the green cell around zero, select the blue, green, and yellow
node pointers (left-click on blue, Shift+click on yellow) and move them as a
group using the left arrow key. Watch the colorbar in the figure window to
see when the green color is centered around zero.
2-341
colormapeditor
The slice plane now has the desired range of colors for negative, zero, and
positive data.
2-342
colormapeditor
Green cell is now centered
around zero.
6 Increase the orange-red coloring in the slice by moving the red node pointer
towards the yellow node.
2-343
colormapeditor
7 Darken the end points to bring out more detail in the extremes of the data.
Double-click on the end nodes to display the color picker. Set the red end
point to the RGB value [50 0 0] and set the blue end point to the RGB value
[0 0 50].
The slice plane coloring now matches the example objectives.
2-344
colormapeditor
See Also
colormap
Color Operations for related functions.
2-345
ColorSpec
Purpose
2ColorSpec
Description
ColorSpec is not a command; it refers to the three ways in which you specify
color in MATLAB:
Color specification
• RGB triple
• Short name
• Long name
The short names and long names are MATLAB strings that specify one of eight
predefined colors. The RGB triple is a three-element row vector whose
elements specify the intensities of the red, green, and blue components of the
color; the intensities must be in the range [0 1]. The following table lists the
predefined colors and their RGB equivalents.
RGB Value
Short Name
Long Name
[1 1 0]
y
yellow
[1 0 1]
m
magenta
[0 1 1]
c
cyan
[1 0 0]
r
red
[0 1 0]
g
green
[0 0 1]
b
blue
[1 1 1]
w
white
[0 0 0]
k
black
Remarks
The eight predefined colors and any colors you specify as RGB values are not
part of a figure’s colormap, nor are they affected by changes to the figure’s
colormap. They are referred to as fixed colors, as opposed to colormap colors.
Examples
To change the background color of a figure to green, specify the color with a
short name, a long name, or an RGB triple. These statements generate
equivalent results:
whitebg('g')
2-346
ColorSpec
whitebg('green')
whitebg([0 1 0]);
You can use ColorSpec anywhere you need to define a color. For example, this
statement changes the figure background color to pink:
set(gcf,'Color',[1,0.4,0.6])
See Also
bar, bar3, colordef, colormap, fill, fill3, whitebg
“Color Operations” for related functions
2-347
colperm
Purpose
2colperm
Sparse column permutation based on nonzero count
Syntax
j = colperm(S)
Description
j = colperm(S) generates a permutation vector j such that the columns of
S(:,j) are ordered according to increasing count of nonzero entries. This is
sometimes useful as a preordering for LU factorization; in this case use
lu(S(:,j)).
If S is symmetric, then j = colperm(S) generates a permutation j so that both
the rows and columns of S(j,j) are ordered according to increasing count of
nonzero entries. If S is positive definite, this is sometimes useful as a
preordering for Cholesky factorization; in this case use chol(S(j,j)).
Algorithm
The algorithm involves a sort on the counts of nonzeros in each column.
Examples
The n-by-n arrowhead matrix
A = [ones(1,n); ones(n-1,1) speye(n-1,n-1)]
has a full first row and column. Its LU factorization, lu(A), is almost
completely full. The statement
j = colperm(A)
returns j = [2:n 1]. So A(j,j) sends the full row and column to the bottom
and the rear, and lu(A(j,j)) has the same nonzero structure as A itself.
On the other hand, the Bucky ball example,
B = bucky
has exactly three nonzero elements in each row and column, so
j = colperm(B) is the identity permutation and is no help at all for reducing
fill-in with subsequent factorizations.
See Also
2-348
chol, colamd, colmmd, lu, spparms, symamd, symmmd, symrcm
comet
Purpose
2comet
Two-dimensional comet plot
Syntax
comet(y)
comet(x,y)
comet(x,y,p)
Description
A comet plot is an animated graph in which a circle (the comet head) traces the
data points on the screen. The comet body is a trailing segment that follows the
head. The tail is a solid line that traces the entire function.
comet(y) displays a comet plot of the vector y.
comet(x,y) displays a comet plot of vector y versus vector x.
comet(x,y,p) specifies a comet body of length p*length(y). p defaults to 0.1.
Remarks
Note that the trace left by comet is created by using an EraseMode of none,
which means you cannot print the plot (you get only the comet head) and it
disappears if you cause a redraw (e.g., by resizing the window).
Examples
Create a simple comet plot:
t = 0:.01:2*pi;
x = cos(2∗t).*(cos(t).^2);
y = sin(2∗t).*(sin(t).^2);
comet(x,y);
See Also
comet3
“Direction and Velocity Plots” for related functions
2-349
comet3
Purpose
2comet3
Three-dimensional comet plot
Syntax
comet3(z)
comet3(x,y,z)
comet3(x,y,z,p)
Description
A comet plot is an animated graph in which a circle (the comet head) traces the
data points on the screen. The comet body is a trailing segment that follows the
head. The tail is a solid line that traces the entire function.
comet3(z) displays a three-dimensional comet plot of the vector z.
comet3(x,y,z) displays a comet plot of the curve through the points
[x(i),y(i),z(i)].
comet3(x,y,z,p) specifies a comet body of length p∗length(y).
Remarks
Note that the trace left by comet3 is created by using an EraseMode of none,
which means you cannot print the plot (you get only the comet head) and it
disappears if you cause a redraw (e.g., by resizing the window).
Examples
Create a three-dimensional comet plot.
t = -10*pi:pi/250:10*pi;
comet3((cos(2*t).^2).*sin(t),(sin(2*t).^2).*cos(t),t);
See Also
comet
“Direction and Velocity Plots” for related functions
2-350
compan
Purpose
2compan
Companion matrix
Syntax
A = compan(u)
Description
A = compan(u) returns the corresponding companion matrix whose first row is
-u(2:n)/u(1), where u is a vector of polynomial coefficients. The eigenvalues
of compan(u) are the roots of the polynomial.
Examples
The polynomial ( x – 1 ) ( x – 2 ) ( x + 3 ) = x 3 – 7x + 6 has a companion matrix
given by
u = [1 0 -7 6]
A = compan(u)
A =
0
7
-6
1
0
0
0
1
0
The eigenvalues are the polynomial roots:
eig(compan(u))
ans =
-3.0000
2.0000
1.0000
This is also roots(u).
See Also
eig, poly, polyval, roots
2-351
compass
Purpose
2compass
Plot arrows emanating from the origin
Syntax
compass(X,Y)
compass(Z)
compass(...,LineSpec)
h = compass(...)
Description
A compass plot displays direction or velocity vectors as arrows emanating from
the origin. X, Y, and Z are in Cartesian coordinates and plotted on a circular
grid.
compass(X,Y) displays a compass plot having n arrows, where n is the number
of elements in X or Y. The location of the base of each arrow is the origin. The
location of the tip of each arrow is a point relative to the base and determined
by [X(i),Y(i)].
compass(Z) displays a compass plot having n arrows, where n is the number of
elements in Z. The location of the base of each arrow is the origin. The location
of the tip of each arrow is relative to the base as determined by the real and
imaginary components of Z. This syntax is equivalent to
compass(real(Z),imag(Z)).
compass(...,LineSpec) draws a compass plot using the line type, marker
symbol, and color specified by LineSpec.
h = compass(...) returns handles to line objects.
Examples
Draw a compass plot of the eigenvalues of a matrix.
Z = eig(randn(20,20));
compass(Z)
2-352
compass
90
5.2689
60
120
4.2151
3.1613
30
150
2.1076
1.0538
180
0
210
330
240
300
270
See Also
feather, LineSpec, rose
“Direction and Velocity Plots” for related functions
Compass Plots for another example
2-353
complex
Purpose
2complex
Construct complex data from real and imaginary components
Syntax
c = complex(a,b)
c = complex(a)
Description
c = complex(a,b) creates a complex output, c, from the two real inputs.
c = a + bi
The output is the same size as the inputs, which must be scalars or equally
sized vectors, matrices, or multi-dimensional arrays of the same data type.
Note If b is all zeros, c is complex and the value of all its imaginary
components is 0. In contrast, the result of the addition a+0i returns a strictly
real result.
c = complex(a) for real a returns the complex result c with real part a and 0
as the value of all imaginary components. Even though the value of all
imaginary components is 0, c is complex and isreal(c) returns false.
The complex function provides a useful substitute for expressions such as
a + i*b
or
a + j*b
in cases when the names “i” and “j” may be used for other variables (and do
not equal – 1 ), when a and b are not double-precision, or when b is all zero.
Example
Create complex uint8 vector from two real uint8 vectors.
a = uint8([1;2;3;4])
b = uint8([2;2;7;7])
c = complex(a,b)
c =
1.0000
2.0000
3.0000
4.0000
2-354
+
+
+
+
2.0000i
2.0000i
7.0000i
7.0000i
complex
See Also
abs, angle, conj, i, imag, isreal, j, real
2-355
computer
Purpose
2computer
Identify information about computer on which MATLAB is running
Syntax
str = computer
[str,maxsize] = computer
[str,maxsize,endian] = computer
Description
str = computer returns the string str with the computer type on which
MATLAB is running.
[str,maxsize] = computer returns the integer maxsize, which contains the
maximum number of elements allowed in an array with this version of
MATLAB.
[str,maxsize,endian] = computer also returns either 'L' for little endian
byte ordering or 'B' for big endian byte ordering.
The list of supported computers changes as new computers are added and
others become obsolete. A typical list follows.
str
Computer
ALPHA
Compaq Alpha (OSF1)
HP700
HP 9000/700 (HP-UX 10.20)
HPUX
HP PA-RISC (HP-UX 11.00)
IBM_RS
IBM RS6000 workstation (AIX)
GLNX86
Linux on PC
PCWIN
Microsoft Windows
SGI
Silicon Graphics (IRIX/IRIX64)
SOL2
Sun Solaris 2 SPARC workstation
Remarks
SGI64 users prior to R12 must migrate to SGI with R12.
LNX86 users prior to R12 must migrate to GLNX86 with R12.
See Also
ispc, isunix
2-356
cond
Purpose
2cond
Condition number with respect to inversion
Syntax
c = cond(X)
c = cond(X,p)
Description
The condition number of a matrix measures the sensitivity of the solution of a
system of linear equations to errors in the data. It gives an indication of the
accuracy of the results from matrix inversion and the linear equation solution.
Values of cond(X) and cond(X,p) near 1 indicate a well-conditioned matrix.
c = cond(X) returns the 2-norm condition number, the ratio of the largest
singular value of X to the smallest.
c = cond(X,p) returns the matrix condition number in p-norm:
norm(X,p) * norm(inv(X),p
If p is...
Then cond(X,p) returns the...
1
1-norm condition number
2
2-norm condition number
'fro'
Frobenius norm condition number
inf
Infinity norm condition number
Algorithm
The algorithm for cond (when p = 2) uses the singular value decomposition,
svd.
See Also
condeig, condest, norm, normest, rank, rcond, svd
References
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra,
J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen,
LAPACK User’s Guide
(http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition,
SIAM, Philadelphia, 1999.
2-357
condeig
Purpose
2condeig
Condition number with respect to eigenvalues
Syntax
c = condeig(A)
[V,D,s] = condeig(A)
Description
c = condeig(A) returns a vector of condition numbers for the eigenvalues of A.
These condition numbers are the reciprocals of the cosines of the angles
between the left and right eigenvectors.
[V,D,s] = condeig(A) is equivalent to
[V,D] = eig(A);
s = condeig(A);
Large condition numbers imply that A is near a matrix with multiple
eigenvalues.
See Also
2-358
balance, cond, eig
condest
Purpose
2condest
1-norm condition number estimate
Syntax
c = condest(A)
[c,v] = condest(A)
Description
c = condest(A) computes a lower bound C for the 1-norm condition number of
a square matrix A.
c = condest(A,t) changes t, a positive integer parameter equal to the
number of columns in an underlying iteration matrix. Increasing the number
of columns usually gives a better condition estimate but increases the cost. The
default is t = 2, which almost always gives an estimate correct to within a
factor 2.
[c,v] = condest(A) also computes a vector v which is an approximate null
vector if c is large. v satisfies norm(A*v,1) = norm(A,1)*norm(v,1)/c.
Note condest invokes rand. If repeatable results are required then invoke
rand('state',j), for some j, before calling this function.
This function is particularly useful for sparse matrices.
condest uses block 1-norm power method of Higham and Tisseur [1].
See Also
cond, norm, normest
Reference
[1] Higham, N. J. and F. Tisseur, “A Block Algorithm for Matrix 1-Norm
Estimation, with an Application to 1-Norm Pseudospectra,” SIAM Journal
Matrix Anal. Appl., Vol. 21, No. 4, 2000, pp.1185-1201.
2-359
coneplot
Purpose
2coneplot
Plot velocity vectors as cones in a 3-D vector field
Syntax
coneplot(X,Y,Z,U,V,W,Cx,Cy,Cz)
coneplot(U,V,W,Cx,Cy,Cz)
coneplot(...,s)
coneplot(...,color)
coneplot(...,'quiver')
coneplot(...,'method')
coneplot(X,Y,Z,U,V,W,'nointerp')
h = coneplot(...)
Description
coneplot(X,Y,Z,U,V,W,Cx,Cy,Cz) plots velocity vectors as cones pointing in
the direction of the velocity vector and having a length proportional to the
magnitude of the velocity vector.
• X, Y, Z define the coordinates for the vector field.
• U, V, W define the vector field. These arrays must be the same size, monotonic,
and 3-D plaid (such as the data produced by meshgrid).
• Cx, Cy, Cz define the location of the cones in vector field. The section Starting
Points for Stream Plots in Visualization Techniques provides more
information on defining starting points.
coneplot(U,V,W,Cx,Cy,Cz) (omitting the X, Y, and Z arguments) assumes
[X,Y,Z] = meshgrid(1:n,1:m,1:p) where [m,n,p]= size(U).
coneplot(...,s) MATLAB automatically scales the cones to fit the graph and
then stretches them by the scale factor s. If you do not specify a value for s,
MATLAB uses a value of 1. Use s = 0 to plot the cones without automatic
scaling.
coneplot(...,color) interpolates the array color onto the vector field and
then colors the cones according to the interpolated values. The size of the color
array must be the same size as the U, V, W arrays. This option works only with
cones (i.e., not with the quiver option).
coneplot(...,'quiver') draws arrows instead of cones (see quiver3 for an
illustration of a quiver plot).
2-360
coneplot
coneplot(...,'method') specifies the interpolation method to use. method
can be: linear, cubic, nearest. linear is the default (see interp3 for a
discussion of these interpolation methods)
coneplot(X,Y,Z,U,V,W,'nointerp') does not interpolate the positions of the
cones into the volume. The cones are drawn at positions defined by X, Y, Z and
are oriented according to U, V, W. Arrays X, Y, Z, U, V, W must all be the same size.
h = coneplot(...) returns the handle to the patch object used to draw the
cones. You can use the set command to change the properties of the cones.
Remarks
coneplot automatically scales the cones to fit the graph, while keeping them
in proportion to the respective velocity vectors.
It is usually best to set the data aspect ratio of the axes before calling coneplot.
You can set the ratio using the daspect command,
daspect([1,1,1])
Examples
This example plots the velocity vector cones for vector volume data
representing the motion of air through a rectangular region of space. The final
graph employs a number of enhancements to visualize the data more
effectively. These include:
• Cone plots indicate the magnitude and direction of the wind velocity.
• Slice planes placed at the limits of the data range provide a visual context for
the cone plots within the volume.
• Directional lighting provides visual queues as to the orientation of the cones.
• View adjustments compose the scene to best reveal the information content
of the data by selecting the view point, projection type, and magnification.
1. Load and Inspect Data
The winds data set contains six 3-D arrays: u, v, and w specify the vector
components at each of the coordinate specified in x, y, and z. The coordinates
define a lattice grid structure where the data is sampled within the volume.
2-361
coneplot
It is useful to establish the range of the data to place the slice planes and to
specify where you want the cone plots (min, max).
load
xmin
xmax
ymin
ymax
zmin
wind
= min(x(:));
= max(x(:));
= min(y(:));
= max(y(:));
= min(z(:));
2. Create the Cone Plot
• Decide where in data space you want to plot cones. This example selects the
full range of x and y in eight steps and the range 3 to 15 in four steps in z
(linspace, meshgrid).
• Use daspect to set the data aspect ratio of the axes before calling coneplot
so MATLAB can determine the proper size of the cones.
• Draw the cones, setting the scale factor to 5 to make the cones larger than
the default size.
• Set the coloring of each cone (FaceColor, EdgeColor).
daspect([2,2,1])
xrange = linspace(xmin,xmax,8);
yrange = linspace(ymin,ymax,8);
zrange = 3:4:15;
[cx cy cz] = meshgrid(xrange,yrange,zrange);
hcones = coneplot(x,y,z,u,v,w,cx,cy,cz,5);
set(hcones,'FaceColor','red','EdgeColor','none')
2-362
coneplot
3. Add the Slice Planes
• Calculate the magnitude of the vector field (which represents wind speed) to
generate scalar data for the slice command.
• Create slice planes along the x-axis at xmin and xmax, along the y-axis at
ymax, and along the z-axis at zmin.
• Specify interpolated face color so the slice coloring indicates wind speed and
do not draw edges (hold, slice, FaceColor, EdgeColor).
hold on
wind_speed = sqrt(u.^2 + v.^2 + w.^2);
hsurfaces = slice(x,y,z,wind_speed,[xmin,xmax],ymax,zmin);
set(hsurfaces,'FaceColor','interp','EdgeColor','none')
hold off
4. Define the View
• Use the axis command to set the axis limits equal to the range of the data.
• Orient the view to azimuth = 30 and elevation = 40 (rotate3d is a useful
command for selecting the best view).
• Select perspective projection to provide a more realistic looking volume
(camproj).
• Zoom in on the scene a little to make the plot as large as possible (camzoom).
axis tight; view(30,40); axis off
camproj perspective; camzoom(1.5)
5. Add Lighting to the Scene
The light source affects both the slice planes (surfaces) and the cone plots
(patches). However, you can set the lighting characteristics of each
independently.
• Add a light source to the right of the camera and use Phong lighting give the
cones and slice planes a smooth, three-dimensional appearance (camlight,
lighting).
• Increase the value of the AmbientStrength property for each slice plane to
improve the visibility of the dark blue colors. (Note that you can also specify
a different colormap to change to coloring of the slice planes.)
2-363
coneplot
• Increase the value of the DiffuseStrength property of the cones to brighten
particularly those cones not showing specular reflections.
camlight right; lighting phong
set(hsurfaces,'AmbientStrength',.6)
set(hcones,'DiffuseStrength',.8)
See Also
isosurface, patch, reducevolume, smooth3, streamline, stream2, stream3,
subvolume
[2] “Volume Visualization” for related functions
2-364
conj
Purpose
2conj
Complex conjugate
Syntax
ZC = conj(Z)
Description
ZC = conj(Z) returns the complex conjugate of the elements of Z.
Algorithm
If Z is a complex array:
conj(Z) = real(Z) - i*imag(Z)
See Also
i, j, imag, real
2-365
continue
Purpose
2continue
Pass control to the next iteration of for or while loop
Syntax
continue
Description
continue passes control to the next iteration of the for or while loop in which
it appears, skipping any remaining statements in the body of the loop.
In nested loops, continue passes control to the next iteration of the for or
while loop enclosing it.
Examples
The example below shows a continue loop that counts the lines of code in the
file, magic.m, skipping all blank lines and comments. A continue statement is
used to advance to the next line in magic.m without incrementing the count
whenever a blank line or comment line is encountered.
fid = fopen('magic.m','r');
count = 0;
while ~feof(fid)
line = fgetl(fid);
if isempty(line) | strncmp(line,'%',1)
continue
end
count = count + 1;
end
disp(sprintf('%d lines',count));
See Also
2-366
for, while, end, break, return
contour
Purpose
2contour
Two-dimensional contour plot
Syntax
contour(Z)
contour(Z,n)
contour(Z,v)
contour(X,Y,Z)
contour(X,Y,Z,n)
contour(X,Y,Z,v)
contour(...,LineSpec)
[C,h] = contour(...)
Description
A contour plot displays isolines of matrix Z. Label the contour lines using
clabel.
contour(Z) draws a contour plot of matrix Z, where Z is interpreted as heights
with respect to the x-y plane. Z must be at least a 2-by-2 matrix. The number
of contour levels and the values of the contour levels are chosen automatically
based on the minimum and maximum values of Z. The ranges of the x- and
y-axis are [1:n] and [1:m], where [m,n] = size(Z).
contour(Z,n) draws a contour plot of matrix Z with n contour levels.
contour(Z,v) draws a contour plot of matrix Z with contour lines at the data
values specified in vector v. The number of contour levels is equal to length(v).
To draw a single contour of level i, use contour(Z,[i i]).
contour(X,Y,Z), contour(X,Y,Z,n), and contour(X,Y,Z,v) draw contour
plots of Z. X and Y specify the x- and y-axis limits. When X and Y are matrices,
they must be the same size as Z, in which case they specify a surface as surf
does.
contour(...,LineSpec) draws the contours using the line type and color
specified by LineSpec. contour ignores marker symbols.
[C,h] = contour(...) returns the contour matrix C (see contourc) and a
vector of handles to graphics objects. clabel uses the contour matrix C to create
the labels. contour creates patch graphics objects unless you specify LineSpec,
in which case contour creates line graphics objects.
2-367
contour
Remarks
If you do not specify LineSpec, colormap and caxis control the color.
If X or Y is irregularly spaced, contour calculates contours using a regularly
spaced contour grid, then transforms the data to X or Y.
Examples
To view a contour plot of the function
z = xe ( – x
2
– y2 )
over the range –2 ≤ x ≤ 2, –2 ≤ y ≤ 3, create matrix Z using the statements
[X,Y] = meshgrid(–2:.2:2,–2:.2:3);
Z = X.∗exp(–X.^2–Y.^2);
Then, generate a contour plot of Z.
[C,h] = contour(X,Y,Z);
clabel(C,h)
colormap cool
3
2.5
2
1.5
0.1
1
−0.
1
0
0.2
−0.1
2
−0.
0.5
0.4
0
0.3
.3
−0.5
0.1
−0
−0.2
0.2
0.1
−1
−0.1
0
−1.5
−2
−2
−1.5
−1
−0.5
0
0.5
1
1.5
2
View the same function over the same range with 20 evenly spaced contour
lines and colored with the default colormap jet.
2-368
contour
contour(X,Y,Z,20)
3
2.5
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
−2
−1.5
−1
−0.5
0
0.5
1
1.5
2
Use interp2 to create smoother contours. Also set the contour label text
BackgroundColor to a light yellow and the EdgeColor to light gray.
Z = magic(4);
[C,h] = contour(interp2(Z,4));
h = clabel(C,h);
set(h,'BackgroundColor',[1 1 .6],...
'Edgecolor',[.7 .7 .7])
2-369
contour
6
6
8
12
40
4
10
8
2
10
45
14
14
12
10
35
8
8
10
8
8
8
8
30
25
10
20
6
10
10
8
8
10
10
15
4
20
25
30
12
5
4
6
8
10
See Also
12
14
5
8
6
10
15
35
40
clabel, contour3, contourc, contourf, interp2, quiver
“Contour Plots” category for related functions
Contour Plots section for more examples
2-370
45
contour3
Purpose
2contour3
Three-dimensional contour plot
Syntax
contour3(Z)
contour3(Z,n)
contour3(Z,v)
contour3(X,Y,Z)
contour3(X,Y,Z,n)
contour3(X,Y,Z,v)
contour3(...,LineSpec)
[C,h] = contour3(...)
Description
contour3 creates a three-dimensional contour plot of a surface defined on a
rectangular grid.
contour3(Z) draws a contour plot of matrix Z in a three-dimensional view. Z is
interpreted as heights with respect to the x-y plane. Z must be at least a 2-by-2
matrix. The number of contour levels and the values of contour levels are
chosen automatically. The ranges of the x- and y-axis are [1:n] and [1:m],
where [m,n] = size(Z).
contour3(Z,n) draws a contour plot of matrix Z with n contour levels in a
three-dimensional view.
contour3(Z,v) draws a contour plot of matrix Z with contour lines at the
values specified in vector v. The number of contour levels is equal to length(v).
To draw a single contour of level i, use contour(Z,[i i]).
contour3(X,Y,Z), contour3(X,Y,Z,n), and contour3(X,Y,Z,v) use X and Y
to define the x- and y-axis limits. If X is a matrix, X(1,:) defines the x-axis. If
Y is a matrix, Y(:,1) defines the y-axis. When X and Y are matrices, they must
be the same size as Z, in which case they specify a surface as surf does.
contour3(...,LineSpec) draws the contours using the line type and color
specified by LineSpec.
[C,h] = contour3(...) returns the contour matrix C as described in the
function contourc and a column vector containing handles to graphics objects.
contour3 creates patch graphics objects unless you specify LineSpec, in which
case contour3 creates line graphics objects.
2-371
contour3
Remarks
If you do not specify LineSpec, colormap and caxis control the color.
If X or Y is irregularly spaced, contour3 calculates contours using a regularly
spaced contour grid, then transforms the data to X or Y.
Examples
Plot the three-dimensional contour of a function and superimpose a surface
plot to enhance visualization of the function.
[X,Y] = meshgrid([-2:.25:2]);
Z = X.*exp(-X.^2-Y.^2);
contour3(X,Y,Z,30)
surface(X,Y,Z,’EdgeColor’,[.8 .8 .8],’FaceColor’,’none’)
grid off
view(-15,25)
colormap cool
0.5
0
−0.5
2
1
0
−1
−2
See Also
−2
−1.5
−1
−0.5
0
contour, contourc, meshc, meshgrid, surfc
“Contour Plots” category for related functions
Contour Plots section for more examples
2-372
0.5
1
1.5
2
contourc
Purpose
2contourc
Low-level contour plot computation
Syntax
C
C
C
C
C
C
Description
contourc calculates the contour matrix C used by contour, contour3, and
contourf. The values in Z determine the heights of the contour lines with
=
=
=
=
=
=
contourc(Z)
contourc(Z,n)
contourc(Z,v)
contourc(x,y,Z)
contourc(x,y,Z,n)
contourc(x,y,Z,v)
respect to a plane. The contour calculations use a regularly spaced grid
determined by the dimensions of Z.
C = contourc(Z) computes the contour matrix from data in matrix Z, where Z
must be at least a 2-by-2 matrix. The contours are isolines in the units of Z. The
number of contour lines and the corresponding values of the contour lines are
chosen automatically.
C = contourc(Z,n) computes contours of matrix Z with n contour levels.
C = contourc(Z,v) computes contours of matrix Z with contour lines at the
values specified in vector v. The length of v determines the number of contour
levels. To compute a single contour of level i, use contourc(Z,[i i]).
C = contourc(x,y,Z), C = contourc(x,y,Z,n), and C = contourc(x,y,Z,v)
compute contours of Z using vectors x and y to determine the x- and y-axis
limits. x and y must be monotonically increasing.
Remarks
C is a two-row matrix specifying all the contour lines. Each contour line defined
in matrix C begins with a column that contains the value of the contour
(specified by v and used by clabel), and the number of (x,y) vertices in the
contour line. The remaining columns contain the data for the (x,y)pairs.
C = [ value1 xdata(1) xdata(2)...value2 xdata(1) xdata(2)...;
dim1
ydata(1) ydata(2)...dim2
ydata(1) ydata(2)...]
Specifying irregularly spaced x and y vectors is not the same as contouring
irregularly spaced data. If x or y is irregularly spaced, contourc calculates
2-373
contourc
contours using a regularly spaced contour grid, then transforms the data to x
or y.
See Also
clabel, contour, contour3, contourf
“Contour Plots” for related functions
The Contouring Algorithm for more information
2-374
contourf
Purpose
2contourf
Filled two-dimensional contour plot
Syntax
contourf(Z)
contourf(Z,n)
contourf(Z,v)
contourf(X,Y,Z)
contourf(X,Y,Z,n)
contourf(X,Y,Z,v)
[C,h,CF] = contourf(...)
Description
A filled contour plot displays isolines calculated from matrix Z and fills the
areas between the isolines using constant colors. The color of the filled areas
depends on the current figure’s colormap.
contourf(Z) draws a contour plot of matrix Z, where Z is interpreted as
heights with respect to a plane. Z must be at least a 2-by-2 matrix. The number
of contour lines and the values of the contour lines are chosen automatically.
contourf(Z,n) draws a contour plot of matrix Z with n contour levels.
contourf(Z,v) draws a contour plot of matrix Z with contour levels at the
values specified in vector v.
contourf(X,Y,Z), contourf(X,Y,Z,n), and contourf(X,Y,Z,v) produce
contour plots of Z using X and Y to determine the x- and y-axis limits. When X
and Y are matrices, they must be the same size as Z, in which case they specify
a surface as surf does.
[C,h,CF] = contourf(...) returns the contour matrix C as calculated by the
function contourc and used by clabel, a vector of handles h to patch graphics
objects, and a contour matrix CF for the filled areas.
Remarks
If X or Y is irregularly spaced, contourf calculates contours using a regularly
spaced contour grid, then transforms the data to X or Y.
Examples
Create a filled contour plot of the peaks function.
[C,h] = contourf(peaks(20),10);
2-375
contourf
colormap autumn
20
18
16
14
12
10
8
6
4
2
2
See Also
4
6
8
10
12
clabel, contour, contour3, contourc, quiver
“Contour Plots” for related functions
2-376
14
16
18
20
contourslice
Purpose
2contourslice
Draw contours in volume slice planes
Syntax
contourslice(X,Y,Z,V,Sx,Sy,Sz)
contourslice(X,Y,Z,V,Xi,Yi,Zi)
contourslice(V,Sx,Sy,Sz), contourslice(V,Xi,Yi,Zi)
contourslice(...,n)
contourslice(...,cvals)
contourslice(...,[cv cv])
contourslice(...,'method')
h = contourslice(...)
Description
contourslice(X,Y,Z,V,Sx,Sy,Sz) draws contours in the x-, y-, and z-axis
aligned planes at the points in the vectors Sx, Sy, Sz. The arrays X, Y, and Z
define the coordinates for the volume V and must be monotonic and 3-D plaid
(such as the data produced by meshgrid) The color at each contour is
determined by the volume V, which must be an m-by-n-by-p volume array.
contourslice(X,Y,Z,V,Xi,Yi,Zi) draws contours through the volume V
along the surface defined by the arrays Xi,Yi,Zi.
contourslice(V,Sx,Sy,Sz) and contourslice(V,Xi,Yi,Zi) (omitting the X,
Y, and Z arguments) assumes [X,Y,Z] = meshgrid(1:n,1:m,1:p) where
[m,n,p]= size(v).
contourslice(...,n) draws n contour lines per plane, overriding the
automatic value.
contourslice(...,cvals) draws length(cval) contour lines per plane at the
values specified in vector cvals.
contourslice(...,[cv cv]) computes a single contour per plane at the level
cv.
contourslice(...,'method') specifies the interpolation method to use.
method can be: linear, cubic, nearest. nearest is the default except when the
contours are being drawn along the surface defined by Xi, Yi, Zi, in which case
linear is the default (see interp3 for a discussion of these interpolation
methods).
h = contourslice(...) returns a vector of handles to patch objects that are
used to implement the contour lines.
2-377
contourslice
Examples
This example uses the flow data set to illustrate the use of contoured slice
planes (type doc flow for more information on this data set). Notice that this
example:
• Specifies a vector of length = 9 for Sx, an empty vector for the Sy, and a
scalar value (0) for Sz. This creates nine contour plots along the x direction
in the y-z plane, and one in the x-y plane at z = 0.
• Uses linspace to define a ten-element linearly spaced vector of values from
-8 to 2 that specifies the number of contour lines to draw at each interval.
• Defines the view and projection type (camva, camproj, campos)
• Sets figure (gcf) and axes (gca) characteristics.
[x y z v] = flow;
h = contourslice(x,y,z,v,[1:9],[],[0],linspace(-8,2,10));
axis([0,10,-3,3,-3,3]); daspect([1,1,1])
camva(24); camproj perspective;
campos([-3,-15,5])
set(gcf,'Color',[.5,.5,.5],'Renderer','zbuffer')
set(gca,'Color','black','XColor','white', ...
'YColor','white','ZColor','white')
box on
2-378
contourslice
3
2
1
0
−1
−2
−3
3
2
1
8
9
10
7
0
6
5
−1
4
3
−2
2
1
See Also
isosurface, smooth3, subvolume, reducevolume
“Volume Visualization” for related functions
2-379
contrast
Purpose
2contrast
Grayscale colormap for contrast enhancement
Syntax
cmap = contrast(X)
cmap = contrast(X,m)
Description
The contrast function enhances the contrast of an image. It creates a new gray
colormap, cmap, that has an approximately equal intensity distribution. All
three elements in each row are identical.
cmap = contrast(X) returns a gray colormap that is the same length as the
current colormap.
cmap = contrast(X,m) returns an m-by-3 gray colormap.
Examples
Add contrast to the clown image defined by X.
load clown;
cmap = contrast(X);
image(X);
colormap(cmap);
See Also
brighten, colormap, image
“Colormaps” for related functions
2-380
conv
Purpose
2conv
Convolution and polynomial multiplication
Syntax
w = conv(u,v)
Description
w = conv(u,v) convolves vectors u and v. Algebraically, convolution is the
same operation as multiplying the polynomials whose coefficients are the
elements of u and v.
Definition
Let m = length(u) and n = length(v). Then w is the vector of length m+n-1
whose kth element is
w(k) =
∑ u ( j )v ( k + 1 – j )
j
The sum is over all the values of j which lead to legal subscripts for u(j) and
v(k+1-j), specifically j = max(1,k+1-n): min(k,m). When m = n, this gives
w(1) = u(1)*v(1)
w(2) = u(1)*v(2)+u(2)*v(1)
w(3) = u(1)*v(3)+u(2)*v(2)+u(3)*v(1)
...
w(n) = u(1)*v(n)+u(2)*v(n-1)+ ... +u(n)*v(1)
...
w(2*n-1) = u(n)*v(n)
Algorithm
The convolution theorem says, roughly, that convolving two sequences is the
same as multiplying their Fourier transforms. In order to make this precise, it
is necessary to pad the two vectors with zeros and ignore roundoff error. Thus,
if
X = fft([x zeros(1,length(y)-1)])
and
Y = fft([y zeros(1,length(x)-1)])
then conv(x,y) = ifft(X.*Y)
See Also
conv2, convn, deconv, filter
convmtx and xcorr in the Signal Processing Toolbox
2-381
conv2
Purpose
2conv2
Two-dimensional convolution
Syntax
C = conv2(A,B)
C = conv2(hcol,hrow,A)
C = conv2(...,'shape')
Description
C = conv2(A,B) computes the two-dimensional convolution of matrices A and
B. If one of these matrices describes a two-dimensional finite impulse response
(FIR) filter, the other matrix is filtered in two dimensions.
The size of C in each dimension is equal to the sum of the corresponding
dimensions of the input matrices, minus one. That is, if the size of A is [ma,na]
and the size of B is [mb,nb], then the size of C is [ma+mb-1,na+nb-1].
C = conv2(hcol,hrow,A) convolves A first with the vector hcol along the rows
and then with the vector hrow along the columns. If hcol is a column vector and
hrow is a row vector, this case is the same as C = conv2(hcol*hrow,A).
C = conv2(...,'shape') returns a subsection of the two-dimensional
convolution, as specified by the shape parameter:
Algorithm
full
Returns the full two-dimensional convolution (default).
same
Returns the central part of the convolution of the same size as A.
valid
Returns only those parts of the convolution that are computed
without the zero-padded edges. Using this option, C has size
[ma-mb+1,na-nb+1] when all(size(A) >= size(B)). Otherwise
conv2 returns [].
conv2 uses a straightforward formal implementation of the two-dimensional
convolution equation in spatial form. If a and b are functions of two discrete
variables, n 1 and n 2 , then the formula for the two-dimensional convolution of
a and b is
c ( n 1, n 2 ) =
∞
∑
∞
∑
k1 = –∞ k2 = –∞
a ( k 1, k 2 ) b ( n 1 – k 1, n 2 – k 2 )
In practice however, conv2 computes the convolution for finite intervals.
2-382
conv2
Note that matrix indices in MATLAB always start at 1 rather than 0.
Therefore, matrix elements A(1,1), B(1,1), and C(1,1) correspond to
mathematical quantities a(0,0), b(0,0), and c(0,0).
Examples
Example 1. For the 'same' case, conv2 returns the central part of the
convolution. If there are an odd number of rows or columns, the "center" leaves
one more at the beginning than the end.
This example first computes the convolution of A using the default ('full')
shape, then computes the convolution using the 'same' shape. Note that the
array returned using 'same' corresponds to the underlined elements of the
array returned using the default shape.
A = rand(3);
B = rand(4);
C = conv2(A,B)
% C is 6-by-6
C =
0.1838
0.6929
0.5627
0.9986
0.3089
0.3287
0.2374
1.2019
1.5150
2.3811
1.1419
0.9347
0.9727
1.5499
2.3576
3.4302
1.8229
1.6464
1.2644
2.1733
3.1553
3.5128
2.1561
1.7928
0.7890
1.3325
2.5373
2.4489
1.6364
1.2422
0.3750
0.3096
1.0602
0.8462
0.6841
0.5423
Cs = conv2(A,B,'same')
% Cs is the same size as A: 3-by-3
Cs =
2.3576 3.1553 2.5373
3.4302 3.5128 2.4489
1.8229 2.1561 1.6364
Example 2. In image processing, the Sobel edge finding operation is a
two-dimensional convolution of an input array with the special matrix
s = [1 2 1; 0 0 0; -1 -2 -1];
These commands extract the horizontal edges from a raised pedestal.
A = zeros(10);
A(3:7,3:7) = ones(5);
H = conv2(A,s);
mesh(H)
2-383
conv2
4
2
0
−2
−4
15
15
10
10
5
5
0
0
Transposing the filter s extracts the vertical edges of A.
V = conv2(A,s');
figure, mesh(V)
4
2
0
−2
−4
15
15
10
10
5
5
0
2-384
0
conv2
This figure combines both horizontal and vertical edges.
figure
mesh(sqrt(H.^2 + V.^2))
5
4
3
2
1
0
15
15
10
10
5
5
0
See Also
0
conv, convn, filter2
xcorr2 in the Signal Processing Toolbox
2-385
convhull
Purpose
Syntax
Description
2convhull
Convex hull
K = convhull(x,y)
[K,a] = convhull(x,y)
K = convhull(x,y) returns indices into the x and y vectors of the points on the
convex hull.
[K,a] = convhull(x,y) also returns the area of the convex hull.
Visualization
Examples
Use plot to plot the output of convhull.
xx = -1:.05:1; yy = abs(sqrt(xx));
[x,y] = pol2cart(xx,yy);
k = convhull(x,y);
plot(x(k),y(k),'r-',x,y,'b+')
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
0
Algorithm
0.1
0.2
0.3
0.4
0.5
0.6
0.7
convhull is based on Qhull [2]. It uses the Qhull joggle option ('QJ'). For
information about qhull, see http://www.geom.umn.edu/software/qhull/.
For copyright information, see
http://www.geom.umn.edu/software/download/COPYING.html.
2-386
convhull
See Also
convhulln, delaunay, plot, polyarea, voronoi
Reference
[1] Barber, C. B., D.P. Dobkin, and H.T. Huhdanpaa, "The Quickhull Algorithm for
Convex Hulls," ACM Transactions on Mathematical Software, Vol. 22, No. 4,
Dec. 1996, p. 469-483. Available in HTML format at
http://www.acm.org/pubs/citations/journals/toms/1996-22-4/p469-bar
ber/ and in PostScript format at
ftp://geom.umn.edu/pub/software/qhull-96.ps.
[2] National Science and Technology Research Center for Computation and
Visualization of Geometric Structures (The Geometry Center), University of
Minnesota. 1993.
2-387
convhulln
Purpose
2convhulln
n-D convex hull
Syntax
K = convhulln(X)
[K,v] = convhulln(X)
Description
K = convhulln(X) returns the indices K of the points in X that comprise the
facets of the convex hull of X. X is an m-by-n array representing m points in n-D
space. If the convex hull has p facets then K is p-by-n.
[K,v] = convhulln(X) also returns the volume v of the convex hull.
Visualization
Plotting the output of convhulln depends on the value of n:
• For n = 2, use plot as you would for convhull.
• For n = 3, you can use trisurf to plot the output. The calling sequence is
K = convhulln(X);
trisurf(K,(X(:,1),X(:,2),X(:,3))
For more control over the color of the facets, use patch to plot the output. For
an example, see “Tessellation and Interpolation of Scattered Data in Higher
Dimensions” in the MATLAB documentation.
• You cannot plot convhulln output for n > 3.
Algorithm
convhulln is based on Qhull [2]. It uses the Qhull joggle option ('QJ'). For
information about qhull, see http://www.geom.umn.edu/software/qhull/.
For copyright information, see
http://www.geom.umn.edu/software/download/COPYING.html.
See Also
convhull, delaunayn, dsearchn, tsearchn, voronoin
Reference
[1] Barber, C. B., D.P. Dobkin, and H.T. Huhdanpaa, "The Quickhull Algorithm for
Convex Hulls," ACM Transactions on Mathematical Software, Vol. 22, No. 4,
Dec. 1996, p. 469-483. Available in HTML format at
http://www.acm.org/pubs/citations/journals/toms/1996-22-4/p469-bar
ber/ and in PostScript format at
ftp://geom.umn.edu/pub/software/qhull-96.ps.
2-388
convhulln
[2] National Science and Technology Research Center for Computation and
Visualization of Geometric Structures (The Geometry Center), University of
Minnesota. 1993.
2-389
convn
Purpose
2convn
N-dimensional convolution
Syntax
C = convn(A,B)
C = convn(A,B,'shape')
Description
C = convn(A,B) computes the N-dimensional convolution of the arrays A and
B. The size of the result is size(A)+size(B)-1.
C = convn(A,B,'shape') returns a subsection of the N-dimensional
convolution, as specified by the shape parameter:
'full'
Returns the full N-dimensional convolution (default).
'same'
Returns the central part of the result that is the same size as A.
'valid'
Returns only those parts of the convolution that can be computed
without assuming that the array A is zero-padded. The size of the
result is
max(size(A)-size(B) + 1, 0)
See Also
2-390
conv, conv2
copyfile
Purpose
2copyfile
Graphical
Interface
As an alternative to the copyfile function, use the Current Directory browser.
Select the files and then select copy and paste commands from the Edit menu.
Syntax
copyfile('source','destination')
copyfile('source','destination','f')
[status,message,messageid] = copyfile('source','destination','f')
Description
copyfile('source','destination') copies the file or directory, source (and
all its contents) to the file or directory, destination, where source and
destination are the absolute or relative pathnames for the directory or file. If
source is a directory, destination cannot be a file. If source is a directory,
copyfile copies the contents of source, not the directory itself. To rename a
file or directory when copying it, make destination a different name than
source. If destination already exists, copyfile replaces it without warning.
Use the wildcard * at the end of source to copy all matching files. Note that the
read-only and archive attributes of source are not preserved in destination.
Copy file or directory
copyfile('source','destination','f') copies source to destination,
regardless of the read-only attribute of destination.
[status,message,messageid] = copyfile('source','destination','f')
copies source to destination, returning the status, a message, and the
MATLAB error message ID (see error and lasterr). Here, status is 1 for
success and is 0 for no error. Only one output argument is required and the f
input argument is optional.
Examples
Copy File in Current Directory, Assigning a New Name to It
To make a copy of a file myfun.m in the current directory, assigning it the name
myfun2.m, type
copyfile('myfun.m','myfun2.m')
Copy File to Another Directory
To copy myfun.m to the directory d:/work/myfiles, keeping the same filename,
type
copyfile('myfun.m','d:/work/myfiles')
2-391
copyfile
Copy All Matching Files by Using a Wildcard
To copy all files in the directory myfiles whose names begin with my to the
directory newprojects, where newprojects is at the same level as the current
directory, type
copyfile('myfiles/my*','../newprojects')
Copy Directory and Return Status
In this example, all files and subdirectories in the current directory’s myfiles
directory are copied to the directory d:/work/myfiles. Note that before
running the copyfile function, d:/work does not contain the directory
myfiles. It is created because myfiles is appended to destination in the
copyfile function:
[s,mess,messid]=copyfile('myfiles','d:/work/myfiles')
s =
1
mess =
''
messid =
''
The message returned indicates that copyfile was successful.
Copy File to Read-Only Directory
Copy myfile.m from the current directory to d:/work/restricted, where
restricted is a read-only directory:
copyfile('myfile.m','d:/work/restricted','f')
After the copy, myfile.m exists in d:/work/restricted.
See Also
2-392
delete, dir, fileattrib, filebrowser, mkdir, movefile, rmdir
copyobj
Purpose
2copyobj
Copy graphics objects and their descendants
Syntax
new_handle = copyobj(h,p)
Description
copyobj creates copies of graphics objects. The copies are identical to the
original objects except the copies have different values for their Parent
property and a new handle. The new parent must be appropriate for the copied
object (e.g., you can copy a line object only to another axes object).
new_handle = copyobj(h,p) copies one or more graphics objects identified by
h and returns the handle of the new object or a vector of handles to new objects.
The new graphics objects are children of the graphics objects specified by p.
Remarks
h and p can be scalars or vectors. When both are vectors, they must be the same
length and the output argument, new_handle, is a vector of the same length.
In this case, new_handle(i) is a copy of h(i) with its Parent property set to
p(i).
When h is a scalar and p is a vector, h is copied once to each of the parents in p.
Each new_handle(i) is a copy of h with its Parent property set to p(i), and
length(new_handle) equals length(p).
When h is a vector and p is a scalar, each new_handle(i) is a copy of h(i) with
its Parent property set to p. The length of new_handle equals length(h).
Graphics objects are arranged as a hierarchy. Here, each graphics object is
shown connected below its appropriate parent object.
Root
Figure
Axes
Uicontrol
Uimenu
Image
Light
Line
Uicontextmenu
Patch
Rectangle
Surface
Text
2-393
copyobj
Examples
Copy a surface to a new axes within a different figure.
h = surf(peaks);
colormap hot
figure
% Create a new figure
axes
% Create an axes object in the figure
new_handle = copyobj(h,gca);
colormap hot
view(3)
grid on
Note that while the surface is copied, the colormap (figure property), view, and
grid (axes properties) are not copies.
See Also
findobj, gcf, gca, gco, get, set
Parent property for all graphics objects
“Finding and Identifying Graphics Objects” for related functions
2-394
corrcoef
Purpose
2corrcoef
Correlation coefficients
Syntax
R = corrcoef(X)
R = corrcoef(x,y)
[R,P]=corrcoef(...)
[R,P,RLO,RUP]=corrcoef(...)
[...]=corrcoef(...,'param1',val1,'param2',val2,...)
Description
R = corrcoef(X) returns a matrix R of correlation coefficients calculated from
an input matrix X whose rows are observations and whose columns are
variables. The matrix R = corrcoef(X) is related to the covariance
matrix C = cov(X) by
C ( i, j )
R ( i, j ) = --------------------------------------C ( i, i )C ( j, j )
corrcoef(X) is the zeroth lag of the covariance function, that is, the zeroth lag
of xcov(x,'coeff') packed into a square array.
R = corrcoef(x,y) where x and y are column vectors is the same as
corrcoef([x y]).
[R,P]=corrcoef(...) also returns P, a matrix of p-values for testing the
hypothesis of no correlation. Each p-value is the probability of getting a
correlation as large as the observed value by random chance, when the true
correlation is zero. If P(i,j) is small, say less than 0.05, then the correlation
R(i,j) is significant.
[R,P,RLO,RUP]=corrcoef(...) also returns matrices RLO and RUP, of the same
size as R, containing lower and upper bounds for a 95% confidence interval for
each coefficient.
[...]=corrcoef(...,'param1',val1,'param2',val2,...) specifies
additional parameters and their values. Valid parameters are the following.
2-395
corrcoef
'alpha'
A number between 0 and 1 to specify a confidence level of
100*(1 - alpha)%. Default is 0.05 for 95% confidence intervals.
'rows'
Either 'all' (default) to use all rows, 'complete' to use rows
with no NaN values, or 'pairwise' to compute R(i,j) using
rows with no NaN values in either column i or j.
The p-value is computed by transforming the correlation to create a t statistic
having n-2 degrees of freedom, where n is the number of rows of X. The
confidence bounds are based on an asymptotic normal distribution of
0.5*log((1+R)/(1-R)), with an approximate variance equal to 1/(n-3).
These bounds are accurate for large samples when X has a multivariate normal
distribution. The 'pairwise' option can produce an R matrix that is not
positive definite.
Examples
Generate random data having correlation between column 4 and the other
columns.
x = randn(30,4);
%
x(:,4) = sum(x,2);
%
[r,p] = corrcoef(x) %
[i,j] = find(p<0.05);
[i,j]
%
Uncorrelated data
Introduce correlation.
Compute sample correlation and p-values.
% Find significant correlations.
Display their (row,col) indices.
r =
1.0000
-0.3566
0.1929
0.3457
-0.3566
1.0000
-0.1429
0.4461
0.1929
-0.1429
1.0000
0.5183
0.3457
0.4461
0.5183
1.0000
0.0531
1.0000
0.4511
0.0135
0.3072
0.4511
1.0000
0.0033
0.0613
0.0135
0.0033
1.0000
p =
1.0000
0.0531
0.3072
0.0613
ans =
4
4
2
2-396
2
3
4
corrcoef
3
See Also
4
cov, mean, std
xcorr, xcov in the Signal Processing Toolbox
2-397
cos
Purpose
2cos
Cosine
Syntax
Y = cos(X)
Description
The cos function operates element-wise on arrays. The function’s domains and
ranges include complex values. All angles are in radians.
Y = cos(X) returns the circular cosine for each element of X.
Examples
Graph the cosine function over the domain – π ≤ x ≤ π .
x = -pi:0.01:pi;
plot(x,cos(x)), grid on
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.6
−0.8
−1
−4
−3
−2
−1
0
1
2
3
4
The expression cos(pi/2) is not exactly zero but a value the size of the
floating-point accuracy, eps, because pi is only a floating-point approximation
to the exact value of π .
Definition
The cosine can be defined as
cos ( x + iy ) = cos ( x ) cosh ( y ) – i sin ( x )sinh ( y )
e iz + e – iz
cos ( z ) = ----------------------2
2-398
cos
Algorithm
cos uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
See Also
acos, acosh, cosh
2-399
cosh
Purpose
2cosh
Hyperbolic cosine
Syntax
Y = cosh(X)
Description
The cosh function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Y = cosh(X) returns the hyperbolic cosine for each element of X.
Examples
Graph the hyperbolic cosine function over the domain – 5 ≤ x ≤ 5 .
x = -5:0.01:5;
plot(x,cosh(x)), grid on
80
70
60
50
40
30
20
10
0
−5
Definition
0
5
The hyperbolic cosine can be defined as
z
–z
e +e
cosh( z) = ------------------2
Algorithm
cosh uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-400
cosh
See Also
acos, acosh, cos
2-401
cot
Purpose
2cot
Cotangent
Syntax
Y = cot(X)
Description
The cot function operates element-wise on arrays. The function’s domains and
ranges include complex values. All angles are in radians.
Y = cot(X) returns the cotangent for each element of X.
Examples
Graph the cotangent the domains – π < x < 0 and 0 < x < π.
x1 = -pi+0.01:0.01:-0.01;
x2 = 0.01:0.01:pi-0.01;
plot(x1,cot(x1),x2,cot(x2)), grid on
100
80
60
40
20
0
−20
−40
−60
−80
−100
−4
Definition
−3
−2
−1
0
1
2
3
4
The cotangent can be defined as
1
cot ( z ) = -----------------tan ( z )
Algorithm
cot uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-402
cot
See Also
acot, acoth, coth
2-403
coth
Purpose
2 coth
Hyperbolic cotangent
Syntax
Y = coth(X)
Description
The coth function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Y = coth(X) returns the hyperbolic cotangent for each element of X.
Examples
Graph the hyperbolic cotangent over the domains – π < x < 0 and 0 < x < π.
x1 = -pi+0.01:0.01:-0.01;
x2 = 0.01:0.01:pi-0.01;
plot(x1,coth(x1),x2,coth(x2)), grid on
150
100
50
0
−50
−100
−4
Definition
−3
−2
−1
0
1
2
3
4
The hyperbolic cotangent can be defined as
1
coth ( z ) = --------------------tanh ( z )
Algorithm
coth uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-404
coth
See Also
acot, acoth, cot
2-405
cov
Purpose
2cov
Covariance matrix
Syntax
C = cov(X)
C = cov(x,y)
Description
C = cov(x) where x is a vector returns the variance of the vector elements. For
matrices where each row is an observation and each column a variable, cov(x)
is the covariance matrix. diag(cov(x)) is a vector of variances for each
column, and sqrt(diag(cov(x))) is a vector of standard deviations.
C = cov(x,y), where x and y are column vectors of equal length, is equivalent
to cov([x y]).
Remarks
cov removes the mean from each column before calculating the result.
The covariance function is defined as
cov ( x 1 ,x 2 ) = E [ ( x 1 – µ 1 ) ( x 2 – µ 2 ) ]
where E is the mathematical expectation and µ i = Ex i .
Examples
Consider A = [-1 1 2 ; -2 3 1 ; 4 0 3]. To obtain a vector of variances for
each column of A:
v = diag(cov(A))'
v =
10.3333
2.3333
1.0000
Compare vector v with covariance matrix C:
C =
10.3333
-4.1667
3.0000
-4.1667
2.3333
-1.5000
3.0000
-1.5000
1.0000
The diagonal elements C(i,i) represent the variances for the columns of A.
The off-diagonal elements C(i,j) represent the covariances of columns i and
j.
See Also
corrcoef, mean, std
xcorr, xcov in the Signal Processing Toolbox
2-406
cplxpair
Purpose
2cplxpair
Sort complex numbers into complex conjugate pairs
Syntax
B
B
B
B
Description
B = cplxpair(A) sorts the elements along different dimensions of a complex
=
=
=
=
cplxpair(A)
cplxpair(A,tol)
cplxpair(A,[],dim)
cplxpair(A,tol,dim)
array, grouping together complex conjugate pairs.
The conjugate pairs are ordered by increasing real part. Within a pair, the
element with negative imaginary part comes first. The purely real values are
returned following all the complex pairs. The complex conjugate pairs are
forced to be exact complex conjugates. A default tolerance of 100*eps relative
to abs(A(i)) determines which numbers are real and which elements are
paired complex conjugates.
If A is a vector, cplxpair(A) returns A with complex conjugate pairs grouped
together.
If A is a matrix, cplxpair(A) returns A with its columns sorted and complex
conjugates paired.
If A is a multidimensional array, cplxpair(A) treats the values along the first
non-singleton dimension as vectors, returning an array of sorted elements.
B = cplxpair(A,tol) overrides the default tolerance.
B = cplxpair(A,[],dim) sorts A along the dimension specified by scalar dim.
B = cplxpair(A,tol,dim) sorts A along the specified dimension and overrides
the default tolerance.
Diagnostics
If there are an odd number of complex numbers, or if the complex numbers
cannot be grouped into complex conjugate pairs within the tolerance, cplxpair
generates the error message
Complex numbers can't be paired.
2-407
cputime
Purpose
2cputime
Elapsed CPU time
Syntax
cputime
Description
cputime returns the total CPU time (in seconds) used by MATLAB from the
time it was started. This number can overflow the internal representation and
wrap around.
Examples
The following code returns the CPU time used to run surf(peaks(40)).
t = cputime; surf(peaks(40)); e = cputime-t
e =
0.4667
See Also
2-408
clock, etime, tic, toc
cross
Purpose
2cross
Vector cross product
Syntax
C = cross(A,B)
C = cross(A,B,dim)
Description
C = cross(A,B) returns the cross product of the vectors A and B. That is,
C = A x B. A and B must be 3-element vectors. If A and B are multidimensional
arrays, cross returns the cross product of A and B along the first dimension of
length 3.
C = cross(A,B,dim) where A and B are multidimensional arrays, returns the
cross product of A and B in dimension dim . A and B must have the same size,
and both size(A,dim) and size(B,dim) must be 3.
Remarks
To perform a dot (scalar) product of two vectors of the same size, use
c = dot(a,b).
Examples
The cross and dot products of two vectors are calculated as shown:
a = [1 2 3];
b = [4 5 6];
c = cross(a,b)
c =
-3
6
-3
d = dot(a,b)
d =
32
See Also
dot
2-409
csc
Purpose
2csc
Cosecant
Syntax
Y = csc(x)
Description
The csc function operates element-wise on arrays. The function’s domains and
ranges include complex values. All angles are in radians.
Y = csc(x) returns the cosecant for each element of x.
Examples
Graph the cosecant over the domains – π < x < 0 and 0 < x < π .
x1 = -pi+0.01:0.01:-0.01;
x2 = 0.01:0.01:pi-0.01;
plot(x1,csc(x1),x2,csc(x2)), grid on
150
100
50
0
−50
−100
−150
−4
Definition
−3
−2
−1
0
1
2
3
4
The cosecant can be defined as
1
csc ( z ) = ----------------sin ( z )
Algorithm
csc uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-410
csc
See Also
acsc, acsch, csch
2-411
csch
Purpose
2 csch
Hyperbolic cosecant
Syntax
Y = csch(x)
Description
The csch function operates element-wise on arrays. The function’s domains
and ranges include complex values. All angles are in radians.
Y = csch(x) returns the hyperbolic cosecant for each element of x.
Examples
Graph the hyperbolic cosecant over the domains – π < x < 0 and 0 < x < π .
x1 = -pi+0.01:0.01:-0.01;
x2 = 0.01:0.01:pi-0.01;
plot(x1,csch(x1),x2,csch(x2)), grid on
100
80
60
40
20
0
−20
−40
−60
−80
−100
−4
Definition
−3
−2
−1
0
1
2
3
4
The hyperbolic cosecant can be defined as
1
csch ( z ) = -------------------sinh ( z )
Algorithm
csch uses FDLIBM, which was developed at SunSoft, a Sun Microsystems, Inc.
business, by Kwok C. Ng, and others. For information about FDLIBM, see
http://www.netlib.org.
2-412
csch
See Also
acsc, acsch, csc
2-413
csvread
Purpose
2csvread
Read a comma-separated value file
Syntax
M = csvread('filename')
M = csvread('filename',row,col)
M = csvread('filename',row,col,range)
Description
M = csvread('filename') reads a comma-separated value formatted file,
filename. The result is returned in M. The file can only contain numeric values.
M = csvread('filename',row,col) reads data from the comma-separated
value formatted file starting at the specified row and column. The row and
column arguments are zero-based, so that row=0 and col=0 specifies the first
value in the file.
M = csvread('filename',row,col,range) reads only the range specified.
Specify the range using the notation, [R1 C1 R2 C2] where (R1,C1) is the
upper-left corner of the data to be read and (R2,C2) is the lower-right corner.
The range can also be specified using spreadsheet notation as in range =
'A1..B7'.
Remarks
csvread fills empty delimited fields with zero. Data files having lines that end
with a nonspace delimiter, such as a semicolon, produce a result that has an
additional last column of zeros.
Examples
Given the file, csvlist.dat that contains the comma-separated values
02,
03,
05,
07,
11,
04,
06,
10,
14,
22,
06,
09,
15,
21,
33,
08,
12,
20,
28,
44,
10,
15,
25,
35,
55,
12
18
30
42
66
To read the entire file, use
csvread('csvlist.dat')
ans =
2
3
2-414
4
6
6
9
8
12
10
15
12
18
csvread
5
7
11
10
14
22
15
21
33
20
28
44
25
35
55
30
42
66
To read the matrix starting with zero-based row 2, column 0 and assign it to
the variable, m,
m = csvread('csvlist.dat', 2, 0)
m =
5
7
11
10
14
22
15
21
33
20
28
44
25
35
55
30
42
66
To read the matrix bounded by zero-based (2,0) and (3,3) and assign it to m,
m = csvread('csvlist.dat', 2, 0, [2,0,3,3])
m =
5
7
See Also
10
14
15
21
20
28
csvwrite, dlmread, textread, wk1read, file formats, importdata, uiimport
2-415
csvwrite
Purpose
2csvwrite
Write a comma-separated value file
Syntax
csvwrite('filename',M)
csvwrite('filename',M,row,col)
Description
csvwrite('filename',M) writes matrix M into filename as comma-separated
values.
csvwrite('filename',M,row,col) writes matrix M into filename starting at
the specified row and column offset. The row and column arguments are
zero-based, so that row=0 and C=0 specifies the first value in the file.
Examples
The following example creates a comma-separated value file from the matrix,
m.
m = [3 6 9 12 15; 5 10 15 20 25; 7 14 21 28 35; 11 22 33 44 55];
csvwrite('csvlist.dat',m)
type csvlist.dat
3,6,9,12,15
5,10,15,20,25
7,14,21,28,35
11,22,33,44,55
The next example writes the matrix to the file, starting at a column offset of 2.
csvwrite('csvlist.dat',m,0,2)
type csvlist.dat
,,3,6,9,12,15
,,5,10,15,20,25
,,7,14,21,28,35
,,11,22,33,44,55
See Also
2-416
csvread, dlmwrite, textread, wk1write, file formats, importdata, uiimport
cumprod
Purpose
2cumprod
Cumulative product
Syntax
B = cumprod(A)
B = cumprod(A,dim)
Description
B = cumprod(A) returns the cumulative product along different dimensions of
an array.
If A is a vector, cumprod(A) returns a vector containing the cumulative product
of the elements of A.
If A is a matrix, cumprod(A) returns a matrix the same size as A containing the
cumulative products for each column of A.
If A is a multidimensional array, cumprod(A) works on the first nonsingleton
dimension.
B = cumprod(A,dim) returns the cumulative product of the elements along the
dimension of A specified by scalar dim. For example, cumprod(A,1) increments
the first (row) index, thus working along the rows of A.
Examples
cumprod(1:5)
ans =
1 2 6
24
120
A = [1 2 3; 4 5 6];
See Also
cumprod(A)
ans =
1
2
4
10
3
18
cumprod(A,2)
ans =
1
2
4
20
6
120
cumsum, prod, sum
2-417
cumsum
Purpose
2cumsum
Cumulative sum
Syntax
B = cumsum(A)
B = cumsum(A,dim)
Description
B = cumsum(A) returns the cumulative sum along different dimensions of an
array.
If A is a vector, cumsum(A) returns a vector containing the cumulative sum of
the elements of A.
If A is a matrix, cumsum(A) returns a matrix the same size as A containing the
cumulative sums for each column of A.
If A is a multidimensional array, cumsum(A) works on the first nonsingleton
dimension.
B = cumsum(A,dim) returns the cumulative sum of the elements along the
dimension of A specified by scalar dim. For example, cumsum(A,1) works across
the first dimension (the rows).
Examples
cumsum(1:5)
ans =
[1 3
6
10
A = [1 2 3; 4 5 6];
See Also
2-418
cumsum(A)
ans =
1
5
2
7
3
9
cumsum(A,2)
ans =
1
4
3
9
6
15
cumprod, prod, sum
15]
cumtrapz
Purpose
2cumtrapz
Cumulative trapezoidal numerical integration
Syntax
Z = cumtrapz(Y)
Z = cumtrapz(X,Y)
Z = cumtrapz(... dim)
Description
Z = cumtrapz(Y) computes an approximation of the cumulative integral of Y
via the trapezoidal method with unit spacing. To compute the integral with
other than unit spacing, multiply Z by the spacing increment.
For vectors, cumtrapz(Y) is a vector containing the cumulative integral of Y.
For matrices, cumtrapz(Y) is a matrix the same size as Y with the cumulative
integral over each column.
For multidimensional arrays, cumtrapz(Y) works across the first nonsingleton
dimension.
Z = cumtrapz(X,Y) computes the cumulative integral of Y with respect to X
using trapezoidal integration. X and Y must be vectors of the same length, or X
must be a column vector and Y an array whose first nonsingleton dimension is
length(X). cumtrapz operates across this dimension.
If X is a column vector and Y an array whose first nonsingleton dimension is
length(X), cumtrapz(X,Y) operates across this dimension.
Z = cumtrapz(X,Y,dim) or cumtrapz(Y,DIM) integrates across the
dimension of Y specified by scalar dim. The length of X must be the same as
size(Y,dim).
Example
Y = [0 1 2; 3 4 5];
cumtrapz(Y,1)
ans =
0
0
1.5000
2.5000
0
3.5000
cumtrapz(Y,2)
ans =
0
0.5000
0
3.5000
2.0000
8.0000
2-419
cumtrapz
See Also
2-420
cumsum, trapz
curl
Purpose
2curl
Computes the curl and angular velocity of a vector field
Syntax
[curlx,curly,curlz,cav] = curl(X,Y,Z,U,V,W)
[curlx,curly,curlz,cav] = curl(U,V,W)
[curlz,cav]= curl(X,Y,U,V)
[curlz,cav]= curl(U,V)
[curlx,curly,curlz] = curl(...), [curlx,curly] = curl(...)
cav = curl(...)
Description
[curlx,curly,curlz,cav] = curl(X,Y,Z,U,V,W) computes the curl and
angular velocity perpendicular to the flow (in radians per time unit) of a 3-D
vector field U, V, W. The arrays X, Y, Z define the coordinates for U, V, W and must
be monotonic and 3-D plaid (as if produced by meshgrid).
[curlx,curly,curlz,cav] = curl(U,V,W) assumes X, Y, and Z are
determined by the expression:
[X Y Z] = meshgrid(1:n,1:m,1:p)
where [m,n,p] = size(U).
[curlz,cav]= curl(X,Y,U,V) computes the curl z-component and the
angular velocity perpendicular to z (in radians per time unit) of a 2-D vector
field U, V. The arrays X, Y define the coordinates for U, V and must be monotonic
and 2-D plaid (as if produced by meshgrid).
[curlz,cav]= curl(U,V) assumes X and Y are determined by the expression:
[X Y] = meshgrid(1:n,1:m)
where [m,n] = size(U).
[curlx,curly,curlz] = curl(...), curlx,curly] = curl(...) returns
only the curl.
cav = curl(...) returns only the curl angular velocity.
Examples
This example uses colored slice planes to display the curl angular velocity at
specified locations in the vector field.
2-421
curl
load wind
cav = curl(x,y,z,u,v,w);
slice(x,y,z,cav,[90 134],[59],[0]);
shading interp
daspect([1 1 1]); axis tight
colormap hot(16)
camlight
This example views the curl angular velocity in one plane of the volume and
plots the velocity vectors (quiver) in the same plane.
load wind
k = 4;
x = x(:,:,k); y = y(:,:,k); u = u(:,:,k); v = v(:,:,k);
cav = curl(x,y,u,v);
pcolor(x,y,cav); shading interp
hold on;
quiver(x,y,u,v,'y')
hold off
colormap copper
2-422
curl
See Also
streamribbon, divergence
“Volume Visualization” for related functions
Displaying Curl with Stream Ribbons for another example
2-423
customverctrl
Purpose
2customverctrl
Allow custom source control system
Syntax
customverctrl(filename, arguments)
Description
This function is supplied for customers who want to integrate a version control
system that is not supported with MATLAB. This function must conform to the
structure of one of the supported version control systems, for example RCS. See
the files clearcase.m, pvcs.m, rcs.m, and sourcesafe.m in
$matlabroot\toolbox\matlab\verctrl as examples.
See Also
checkin, checkout, cmopts, undocheckout
2-424
cylinder
Purpose
2cylinder
Generate cylinder
Syntax
[X,Y,Z] = cylinder
[X,Y,Z] = cylinder(r)
[X,Y,Z] = cylinder(r,n)
cylinder(...)
Description
cylinder generates x, y, and z coordinates of a unit cylinder. You can draw the
cylindrical object using surf or mesh, or draw it immediately by not providing
output arguments.
[X,Y,Z] = cylinder returns the x, y, and z coordinates of a cylinder with a
radius equal to 1. The cylinder has 20 equally spaced points around its
circumference.
[X,Y,Z] = cylinder(r) returns the x, y, and z coordinates of a cylinder using
r to define a profile curve. cylinder treats each element in r as a radius at
equally spaced heights along the unit height of the cylinder. The cylinder has
20 equally spaced points around its circumference.
[X,Y,Z] = cylinder(r,n) returns the x, y, and z coordinates of a cylinder
based on the profile curve defined by vector r. The cylinder has n equally
spaced points around its circumference.
cylinder(...), with no output arguments, plots the cylinder using surf.
Remarks
cylinder treats its first argument as a profile curve. The resulting surface
graphics object is generated by rotating the curve about the x-axis, and then
aligning it with the z-axis.
Examples
Create a cylinder with randomly colored faces.
cylinder
axis square
h = findobj('Type','surface');
2-425
cylinder
set(h,'CData',rand(size(get(h,'CData'))))
1
0.8
0.6
0.4
0.2
0
1
1
0.5
0.5
0
0
−0.5
−0.5
−1
−1
Generate a cylinder defined by the profile function 2+sin(t).
t = 0:pi/10:2*pi;
[X,Y,Z] = cylinder(2+cos(t));
surf(X,Y,Z)
axis square
2-426
cylinder
1
0.8
0.6
0.4
0.2
0
4
4
2
2
0
0
−2
−2
−4
See Also
−4
sphere, surf
“Polygons and Surfaces” for related functions
2-427
daspect
Purpose
2daspect
Set or query the axes data aspect ratio
Syntax
daspect
daspect([aspect_ratio])
daspect('mode')
daspect('auto')
daspect('manual')
daspect(axes_handle,...)
Description
The data aspect ratio determines the relative scaling of the data units along the
x-, y-, and z-axes.
daspect with no arguments returns the data aspect ratio of the current axes.
daspect([aspect_ratio]) sets the data aspect ratio in the current axes to the
specified value. Specify the aspect ratio as three relative values representing
the ratio of the x-, y-, and z-axis scaling (e.g., [1 1 3] means one unit in x is
equal in length to one unit in y and three unit in z).
daspect('mode') returns the current value of the data aspect ratio mode,
which can be either auto (the default) or manual. See Remarks.
daspect('auto') sets the data aspect ratio mode to auto.
daspect('manual') sets the data aspect ratio mode to manual.
daspect(axes_handle,...) performs the set or query on the axes identified by
the first argument, axes_handle. When you do not specify an axes handle,
daspect operates on the current axes.
Remarks
daspect sets or queries values of the axes object DataAspectRatio and
DataAspectRatioMode properties.
When the data aspect ratio mode is auto, MATLAB adjusts the data aspect
ratio so that each axis spans the space available in the figure window. If you
are displaying a representation of a real-life object, you should set the data
aspect ratio to [1 1 1] to produce the correct proportions.
Setting a value for data aspect ratio or setting the data aspect ratio mode to
manual disables the MATLAB stretch-to-fill feature (stretching of the axes to
2-428
daspect
fit the window). This means setting the data aspect ratio to a value, including
its current value,
daspect(daspect)
can cause a change in the way the graphs look. See the Remarks section of the
axes description for more information.
Examples
The following surface plot of the function z = xe ( – x – y ) is useful to illustrate
the data aspect ratio. First plot the function over the range –2 ≤ x ≤ 2, –2 ≤ y ≤ 2,
2
2
[x,y] = meshgrid([-2:.2:2]);
z = x.*exp(-x.^2 - y.^2);
surf(x,y,z)
0.5
0
−0.5
2
1
2
1
0
0
−1
−1
−2
−2
Querying the data aspect ratio shows how MATLAB has drawn the surface.
daspect
ans =
4 4
1
Setting the data aspect ratio to [1 1 1] produces a surface plot with equal
scaling along each axis.
2-429
daspect
daspect([1 1 1])
0.5
0
−0.5
2
1.5
2
1
0.5
1
0
−0.5
0
−1
−1
−1.5
−2
See Also
−2
axis, pbaspect, xlim, ylim, zlim
The axes properties DataAspectRatio, PlotBoxAspectRatio, XLim, YLim, ZLim
“Setting the Aspect Ratio and Axis Limits” for related functions
Axes Aspect Ratio for more information.
2-430
date
Purpose
2date
Current date string
Syntax
str = date
Description
str = date returns a string containing the date in dd-mmm-yyyy format.
See Also
clock, datenum, now
2-431
datenum
Examples
Convert a date string to a serial date number.
n = datenum('19-May-2001')
n =
730990
Specifying year, month, and day, convert a date to a serial date number.
n = datenum(2001,12,19)
n =
731204
Convert a date vector to a serial date number.
format bank
n = datenum([2001 5 19 18 0 0])
n =
730990.75
Convert a date string to a serial date number using the default pivot year
n = datenum('12-june-12')
n =
735032
Convert the same date string to a serial date number using 1900 as the pivot
year.
n = datenum('12-june-12', 1900)
n =
698507
See Also
datestr, datevec, now
2-433
datestr
Purpose
2datestr
Date string format
Syntax
str = datestr(DT,dateform)
str = datestr(DT,dateform,P)
Description
The datestr function converts serial date numbers (defined by datenum) and
date vectors (defined by datevec) into date strings.
str = datestr(DT,dateform) converts a single date vector, or each element of
an array of serial date numbers to a date string. Date strings with
two-character years, e.g., 12-june-12, are assumed to lie within the 100-year
period centered about the current year.
str = datestr(DT,dateform,P) uses the specified pivot year as the starting
year of the 100-year range in which a two-character year resides. The default
pivot year is the current year minus 50 years.
The optional argument dateform specifies the date format of the result.
dateform can be either a number or a string:
2-434
dateform
(number)
dateform (string)
Example
0
'dd-mmm-yyyy HH:MM:SS'
01-Mar-2000 15:45:17
1
'dd-mmm-yyyy'
01-Mar-2000
2
'mm/dd/yy'
03/01/00
3
'mmm'
Mar
4
'm'
M
5
'mm'
03
6
'mm/dd'
03/01
7
'dd'
01
8
'ddd'
Wed
9
'd'
W
datestr
dateform
(number)
dateform (string)
Example
10
'yyyy'
2000
11
'yy'
00
12
'mmmyy'
Mar00
13
'HH:MM:SS'
15:45:17
14
'HH:MM:SS PM'
3:45:17 PM
15
'HH:MM'
15:45
16
'HH:MM PM'
3:45 PM
17
'QQ-YY'
Q1-01
18
'QQ'
Q1
19
'dd/mm'
01/03
20
'dd/mm/yy'
01/03/00
21
'mmm.dd.yyyy HH:MM:SS'
Mar.01,2000 15:45:17
22
'mmm.dd.yyyy'
Mar.01.2000
23
'mm/dd/yyyy'
03/01/2000
24
'dd/mm/yyyy'
01/03/2000
25
'yy/mm/dd'
00/03/01
26
'yyyy/mm/dd'
2000/03/01
27
'QQ-YYYY’
Q1-2001
28
'mmmyyyy'
Mar2000
29 (ISO
8601)
'yyyy-mm-dd'
2000-03-01
30 (ISO
8601)
'yyyymmddTHHMMSS'
20000301T154517
31
'yyyy-mm-dd HH:MM:SS'
2000-03-01 15:45:17
2-435
datestr
NOTE dateform numbers 0, 1, 2, 6, 13, 14, 15, 16, and 23 produce a string
suitable for input to datenum or datevec. Other date string formats will not
work with these functions.
Time formats like 'h:m:s', 'h:m:s.s', 'h:m pm', ... can also be part of the
input array DT. If you do not specify dateform, or if you specify dateform as -1,
the date string format defaults to
See Also
2-436
1
if DT contains date information only, e.g., 01-Mar-1995
16
if DT contains time information only e.g., 03:45 PM
0
if DT is a date vector, or a string that contains both date and time
information e.g., 01-Mar-1995 03:45
date, datetick, datenum, datevec
datetick
Purpose
2datetick
Label tick lines using dates
Syntax
datetick(tickaxis)
datetick(tickaxis,dateform)
Description
datetick(tickaxis) labels the tick lines of an axis using dates, replacing the
default numeric labels. tickaxis is the string 'x', 'y', or 'z'. The default is
'x'. datetick selects a label format based on the minimum and maximum
limits of the specified axis.
datetick(tickaxis,dateform) formats the labels according to the integer
dateform (see table). To produce correct results, the data for the specified axis
must be serial date numbers (as produced by datenum).
dateform (number)
dateform (string)
Example
0
'dd-mmm-yyyy HH:MM:SS'
01-Mar-2000
15:45:17
1
'dd-mmm-yyyy'
01-Mar-2000
2
'mm/dd/yy'
03/01/00
3
'mmm'
Mar
4
'm'
M
5
'mm'
03
6
'mm/dd'
03/01
7
'dd'
01
8
'ddd'
Wed
9
'd'
W
10
'yyyy'
2000
11
'yy'
00
12
'mmmyy'
Mar00
13
'HH:MM:SS'
15:45:17
2-437
datetick
Remarks
dateform (number)
dateform (string)
Example
14
'HH:MM:SS PM'
3:45:17 PM
15
'HH:MM'
15:45
16
'HH:MM PM'
3:45 PM
17
'QQ-YY'
Q1–01
18
'QQ'
Q1
19
'dd/mm'
01/03
20
'dd/mm/yy'
01/03/00
21
'mmm.dd.yyyy HH:MM:SS'
Mar.01,2000
15:45:17
22
'mmm.dd.yyyy'
Mar.01.2000
23
'mm/dd/yyyy'
03/01/2000
24
'dd/mm/yyyy'
01/03/2000
25
'yy/mm/dd'
00/03/01
26
'yyyy/mm/dd'
2000/03/01
27
'QQ-YYYY’
Q1-2001
28
'mmmyyyy'
Mar2000
datetick calls datestr to convert date numbers to date strings.
To change the tick spacing and locations, set the appropriate axes property
(i.e., XTick, YTick, or ZTick) before calling datetick.
Example
Consider graphing population data based on the 1990 U.S. census:
t = (1900:10:1990)';
% Time interval
p = [75.995 91.972 105.711 123.203 131.669 ...
150.697 179.323 203.212 226.505 249.633]'; % Population
plot(datenum(t,1,1),p) % Convert years to date numbers and plot
grid on
2-438
datetick
datetick('x',11)
% Replace x-axis ticks with 2-digit year labels
260
240
220
200
180
160
140
120
100
80
60
00
See Also
20
40
60
80
00
The axes properties XTick, YTick, and ZTick.
datenum, datestr
“Annotating Plots” for related functions
2-439
datevec
Purpose
2datevec
Date components
C = datevec(A)
C = datevec(A,P)
[Y,M,D,H,MI,S] = datevec(A)
Description
C = datevec(A) splits its input into an n-by-6 array with each row containing
the vector [Y,M,D,H,MI,S]. The first five date vector elements are integers.
Input A can either consist of strings of the sort produced by the datestr
function, or scalars of the sort produced by the datenum and now functions. Date
strings with two-character years, e.g., 12-june-12, are assumed to lie within
the 100-year period centered about the current year.
C = datevec(A,P) uses the specified pivot year as the starting year of the
100-year range in which a two-character year resides. The default pivot year is
the current year minus 50 years.
[Y,M,D,H,MI,S] = datevec(A) returns the components of the date vector as
individual variables.
When creating your own date vector, you need not make the components
integers. Any components that lie outside their conventional ranges affect the
next higher component (so that, for instance, the anomalous June 31 becomes
July 1). A zeroth month, with zero days, is allowed.
Examples
An example of using a string as input:
datevec('12/24/1984')
ans =
1984
12
24
An example of using a serial date number as input:
t = datenum('12/24/1984')
t =
725000
datevec(t)
2-440
0
0
0
datevec
ans =
1984
See Also
12
24
0
0
0
clock, datenum, datestr, now
2-441
dbclear
Purpose
2dbclear
Graphical
Interface
As an alternative to the dbclear function, there are various ways to clear
breakpoints using the Editor/Debugger.
Syntax
dbclear
dbclear
dbclear
dbclear
dbclear
dbclear
dbclear
dbclear
dbclear
Description
dbclear all removes all breakpoints in all M-files, as well as pauses set for
error, warning, and naninf/infnan using dbstop.
Clear breakpoints
all
all in mfile
in mfile
in mfile at lineno
in mfile at subfun
if error
if warning
if naninf
if infnan
dbclear all in mfile removes breakpoints in mfile.
dbclear in mfile removes the breakpoint set at the first executable line in
mfile.
dbclear in mfile at lineno removes the breakpoint set at the line number
lineno in mfile.
dbclear in mfile at subfun removes the breakpoint set at the subfunction
subfun in mfile.
dbclear if error removes the pause set using dbstop if error.
dbclear if warning removes the pause set using dbstop if warning.
dbclear if naninf removes the pause set using dbstop if naninf.
dbclear if infnan removes the pause set using dbstop if infnan.
Remarks
2-442
The at, in, and if keywords, familiar to users of the UNIX debugger dbx, are
optional.
dbclear
See Also
dbcont, dbdown, dbquit, dbstack, dbstatus, dbstep, dbstop, dbtype, dbup,
partialpath
2-443
dbcont
Purpose
2dbcont
Graphical
Interface
As an alternative to the dbcont function, you can select Continue from the
Debug menu in the Editor/Debugger.
Syntax
dbcont
Description
dbcont resumes execution of an M-file from a breakpoint. Execution continues
Resume execution
until another breakpoint is encountered, an error occurs, or MATLAB returns
to the base workspace prompt.
See Also
2-444
dbclear, dbdown, dbquit, dbstack, dbstatus, dbstep, dbstop, dbtype, dbup
dbdown
Purpose
2dbdown
Graphical
Interface
As an alternative to the dbdown function, you can select a different workspace
from the Stack field in the Editor/Debugger toolbar.
Syntax
dbdown
Description
dbdown changes the current workspace context to the workspace of the called
M-file when a breakpoint is encountered. You must have issued the dbup
function at least once before you issue this function. dbdown is the opposite of
dbup.
Change local workspace context
Multiple dbdown functions change the workspace context to each successively
executed M-file on the stack until the current workspace context is the current
breakpoint. It is not necessary, however, to move back to the current
breakpoint to continue execution or to step to the next line.
See Also
dbclear, dbcont, dbquit, dbstack, dbstatus, dbstep, dbstop, dbtype, dbup
2-445
dblquad
Purpose
2dblquad
Numerically evaluate double integral
Syntax
q
q
q
q
Description
q = dblquad(fun,xmin,xmax,ymin,ymax) calls the quad function to evaluate
the double integral fun(x,y) over the rectangle xmin <= x <= xmax,
ymin <= y <= ymax. fun(x,y) must accept a vector x and a scalar y and return
a vector of values of the integrand.
=
=
=
=
dblquad(fun,xmin,xmax,ymin,ymax)
dblquad(fun,xmin,xmax,ymin,ymax,tol)
dblquad(fun,xmin,xmax,ymin,ymax,tol,method)
dblquad(fun,xmin,xmax,ymin,ymax,tol,method,p1,p2,...)
q = dblquad(fun,xmin,xmax,ymin,ymax,tol) uses a tolerance tol instead of
the default, which is 1.0e-6.
q = dblquad(fun,xmin,xmax,ymin,ymax,tol,method) uses the quadrature
function specified as method, instead of the default quad. Valid values for
method are @quadl or the function handle of a user-defined quadrature method
that has the same calling sequence as quad and quadl.
dblquad(fun,xmin,xmax,ymin,ymax,tol,method,p1,p2,...) passes the
additional parameters p1,p2,... to fun(x,y,p1,p2,...). Use [] as a
placeholder if you do not specify tol or method.
dblquad(fun,xmin,xmax,ymin,ymax,[],[],p1,p2,...) is the same as
dblquad(fun,xmin,xmax,ymin,ymax,1.e-6,@quad,p1,p2,...)
Example
fun can be an inline object
Q = dblquad(inline('y*sin(x)+x*cos(y)'), pi, 2*pi, 0, pi)
or a function handle
Q = dblquad(@integrnd, pi, 2*pi, 0, pi)
where integrnd.m is an M-file.
function z = integrnd(x, y)
z = y*sin(x)+x*cos(y);
2-446
dblquad
The integrnd function integrates y*sin(x)+x*cos(y) over the square
pi <= x <= 2*pi, 0 <= y <= pi. Note that the integrand can be evaluated
with a vector x and a scalar y .
Nonsquare regions can be handled by setting the integrand to zero outside of
the region. For example, the volume of a hemisphere is
dblquad(inline('sqrt(max(1-(x.^2+y.^2),0))'),-1,1,-1,1)
or
dblquad(inline('sqrt(1-(x.^2+y.^2)).*(x.^2+y.^2<=1)'),-1,1,-1,1
)
See Also
inline, quad, quadl, triplequad, @ (function handle)
2-447
dbmex
Purpose
2dbmex
Enable MEX-file debugging
Syntax
dbmex
dbmex
dbmex
dbmex
Description
dbmex on enables MEX-file debugging for UNIX platforms. It is not supported
on
off
stop
print
on the Sun Solaris platform. To use this option, first start MATLAB from
within a debugger by typing: matlab -Ddebugger, where debugger is the name
of the debugger.
dbmex off disables MEX-file debugging.
dbmex stop returns to the debugger prompt.
dbmex print displays MEX-file debugging information.
Remarks
On Sun Solaris platforms, dbmex is not supported. See the Technical Support
solution 23388 at
http://www.mathworks.com/support/solutions/data/23388.shtml for an
alternative method of debugging.
See Also
dbclear, dbcont, dbdown, dbquit, dbstack, dbstatus, dbstep, dbstop, dbtype,
dbup
2-448
dbquit
Purpose
2dbquit
Graphical
Interface
As an alternative to the dbquit function, you can select Exit Debug Mode from
the Debug menu in the Editor/Debugger.
Syntax
dbquit
Description
dbquit immediately terminates the debugger and returns control to the base
Quit debug mode
workspace prompt. The M-file being processed is not completed and no results
are returned.
All breakpoints remain in effect.
See Also
dbclear, dbcont, dbdown, dbstack, dbstatus, dbstep, dbstop, dbtype, dbup
2-449
dbstack
Purpose
2dbstack
Graphical
Interface
As an alternative to the dbstack function, you can view the Stack field in the
Editor/Debugger toolbar.
Syntax
dbstack
[ST,I] = dbstack
Description
dbstack displays the line numbers and M-file names of the function calls that
Display function call stack
led to the current breakpoint, listed in the order in which they were executed.
The line number of the most recently executed function call (at which the
current breakpoint occurred) is listed first, followed by its calling function,
which is followed by its calling function, and so on, until the topmost M-file
function is reached.
[ST,I] = dbstack returns the stack trace information in an m-by-1 structure
ST with the fields
name
Function name
line
Function line number
The current workspace index is returned in I.
Examples
dbstack
In /usr/local/matlab/toolbox/matlab/cond.m at line 13
In test1.m at line 2
In test.m at line 3
See Also
2-450
dbclear, dbcont, dbdown, dbquit, dbstatus, dbstep, dbstop, dbtype, dbup
dbstatus
Purpose
2dbstatus
Graphical
Interface
As an alternative to the dbstatus function, you can see breakpoint icons for a
file that is open in the Editor/Debugger.
Syntax
dbstatus
dbstatus function
s = dbstatus(...)
Description
dbstatus lists all breakpoints in effect including error, warning, and naninf.
List all breakpoints
dbstatus function displays a list of the line numbers for which breakpoints
are set in the specified M-file.
s = dbstatus(...) returns the breakpoint information in an m-by-1
structure with the fields
name
Function name
line
Function line number
cond
Condition string (error, warning, or
naninf)
Use dbstatus class/function or dbstatus private/function or
dbstatus class/private/function to determine the status for methods,
private functions, or private methods (for a class named class). In all these
forms you can further qualify the function name with a subfunction name as in
dbstatus function/subfunction.
See Also
dbclear, dbcont, dbdown, dbquit, dbstack, dbstep, dbstop, dbtype, dbup
2-451
dbstep
Purpose
2dbstep
Graphical
Interface
As an alternative to the dbstep function, you can select Step or Step In from
the Debug menu in the Editor/Debugger.
Syntax
dbstep
dbstep nlines
dbstep in
Description
This function allows you to debug an M-file by following its execution from the
current breakpoint. At a breakpoint, the dbstep function steps through
execution of the current M-file one line at a time or at the rate specified by
nlines.
Execute one or more lines from current breakpoint
dbstep, by itself, executes the next executable line of the current M-file. dbstep
steps over the current line, skipping any breakpoints set in functions called by
that line.
dbstep nlines executes the specified number of executable lines.
dbstep in steps to the next executable line. If that line contains a call to
another M-file, execution resumes with the first executable line of the called
file. If there is no call to an M-file on that line, dbstep in is the same as dbstep.
See Also
2-452
dbclear, dbcont, dbdown, dbquit, dbstack, dbstatus, dbstop, dbtype, dbup
dbstop
Purpose
2dbstop
Graphical
Interface
As an alternative to the dbstop function, you can use the Breakpoints menu
or the breakpoint alley in the Editor/Debugger.
Syntax
dbstop
dbstop
dbstop
dbstop
dbstop
dbstop
dbstop
dbstop
Description
dbstop in mfile temporarily stops execution of mfile when you run it, at the
first executable line, putting MATLAB in debug mode. mfile must be in a
directory that is on the search path or in the current directory. If you have
graphical debugging enabled, the MATLAB Debugger opens with a breakpoint
at the first executable line of mfile. You can then use the debugging utilities,
review the workspace, or issue any valid MATLAB function. Use dbcont or
dbstep to resume execution of mfile. Use dbquit to exit from the Debugger.
Set breakpoints in M-file function
in
in
in
if
if
if
if
if
mfile
mfile at lineno
mfile at subfun
error
all error
warning
naninf
infnan
dbstop in mfile at lineno temporarily stops execution of mfile when you
run it, just prior to execution of the line whose number is lineno, putting
MATLAB in debug mode. mfile must be in a directory that is on the search
path or in the current directory. If you have graphical debugging enabled, the
MATLAB Debugger opens mfile with a breakpoint at line lineno. If that line
is not executable, execution stops and the breakpoint is set at the next
executable line following lineno. When execution stops, you can use the
debugging utilities, review the workspace, or issue any valid MATLAB
function. Use dbcont or dbstep to resume execution of mfile. Use dbquit to
exit from the Debugger.
dbstop in mfile at subfun temporarily stops execution of mfile when you
run it, just prior to execution of the subfunction subfun, putting MATLAB in
debug mode. mfile must be in a directory that is on the search path or in the
current directory. If you have graphical debugging enabled, the MATLAB
Debugger opens mfile with a breakpoint at the subfunction specified by
2-453
dbstop
subfun. You can then use the debugging utilities, review the workspace, or
issue any valid MATLAB function. Use dbcont or dbstep to resume execution
of mfile. Use dbquit to exit from the Debugger.
dbstop if error stops execution when any M-file you subsequently run
produces a run-time error, putting MATLAB in debug mode, paused at the line
that generated the error. The M-file must be in a directory that is on the search
path or in the current directory. The errors that stop execution do not include
run-time errors that are detected within a try...catch block. You cannot
resume execution after an error. Use dbquit to exit from the Debugger.
dbstop if all error is the same as dbstop if error, except that it stops
execution on any type of run-time error, including errors that are detected
within a try...catch block.
dbstop if warning stops execution when any M-file you subsequently run
produces a run-time warning, putting MATLAB in debug mode, paused at the
line that generated the warning. The M-file must be in a directory that is on
the search path or in the current directory. Use dbcont or dbstep to resume
execution.
dbstop if naninf or dbstop if infnan stops execution when any M-file you
subsequently run encounters an infinite value (Inf) or a value that is not a
number (NaN), putting MATLAB in debug mode, paused at the line where Inf
or NaN was encountered. For convenience, you can use either naninf or
infnan—they perform in exactly the same manner. The M-file must be in a
directory that is on the search path or in the current directory. Use dbcont or
dbstep to resume execution. Use dbquit to exit from the Debugger.
Remarks
2-454
The at, in, and if keywords, familiar to users of the UNIX debugger dbx, are
optional.
dbstop
Examples
The file buggy, used in these examples, consists of three lines.
function z = buggy(x)
n = length(x);
z = (1:n)./x;
Stop at First Executable Line
The statements
dbstop in buggy
buggy(2:5)
stop execution at the first executable line in buggy
n = length(x);
The function
dbstep
advances to the next line, at which point you can examine the value of n.
Stop if Error
Because buggy only works on vectors, it produces an error if the input x is a full
matrix. The statements
dbstop if error
buggy(magic(3))
produce
??? Error using ==> ./
Matrix dimensions must agree.
Error in ==> c:\buggy.m
On line 3 ==> z = (1:n)./x;
K»
and put MATLAB in debug mode.
2-455
dbstop
Stop if InfNaN
In buggy, if any of the elements of the input x is zero, a division by zero occurs.
The statements
dbstop if naninf
buggy(0:2)
produce
Warning: Divide by zero.
> In c:\buggy.m at line 3
K»
and put MATLAB in debug mode.
See Also
2-456
break, dbclear, dbcont, dbdown, dbquit, dbstack, dbstatus, dbstep, dbtype,
dbup, keyboard, partialpath, return
dbtype
Purpose
2dbtype
Graphical
Interface
As an alternative to the dbtype function, you can see an M-file with line
numbers by opening it in the Editor/Debugger.
Syntax
dbtype function
dbtype function start:end
Description
dbtype function displays the contents of the specified M-file function with
line numbers preceding each line. function must be the name of an M-file
function or a MATLABPATH relative partial pathname.
List M-file with line numbers
dbtype function start:end displays the portion of the file specified by a
range of line numbers.
You cannot use dbtype for built-in functions.
Examples
To see only the input and output arguments for a function, that is, the first line
of the M-file, type
dtype function 1
For example,
dbtype fileparts 1
returns
1
See Also
function [path, fname, extension,version] = fileparts(name)
dbclear, dbcont, dbdown, dbquit, dbstack, dbstatus, dbstep, dbstop, dbup,
partialpath
2-457
dbup
Purpose
2dbup
Graphical
Interface
As an alternative to the dbup function, you can select a different workspace
from the Stack field in the toolbar of the Editor/Debugger.
Syntax
dbup
Description
This function allows you to examine the calling M-file by using any other
MATLAB function. In this way, you determine what led to the arguments’
being passed to the called function.
Change local workspace context
dbup changes the current workspace context (at a breakpoint) to the workspace
of the calling M-file.
Multiple dbup functions change the workspace context to each previous calling
M-file on the stack until the base workspace context is reached. (It is not
necessary, however, to move back to the current breakpoint to continue
execution or to step to the next line.)
See Also
2-458
dbclear, dbcont, dbdown, dbquit, dbstack, dbstatus, dbstep, dbstop, dbtype
dde23
Purpose
2dde23
Solve delay differential equations (DDEs) with constant delays
Syntax
sol = dde23(ddefun,lags,history,tspan)
sol = dde23(ddefun,lags,history,tspan,options)
sol = dde23(ddefun,lags,history,tspan,options,p1,p2,...)
Arguments
ddefun
Function that evaluates the right side of the differential
equations y′ ( t ) = f ( t, y ( t ), y ( t – τ 1 ), …, y ( t – τ k ) ). The function
must have the form
dydt = ddefun(t,y,Z)
where t corresponds to the current t , y is a column vector that
approximates y ( t ) , and Z(:,j) approximates y ( t – τ j ) for
delay τ j = lags(j). The output is a column vector
corresponding to f ( t, y ( t ), y ( t – τ 1 ), …, y ( t – τ k ) ).
lags
Vector of constant, positive delays τ 1, …, τ k .
history
Specify history in one of three ways:
• A function of t such that y = history(t) returns the
solution y ( t ) for t ≤ t0 as a column vector
• A constant column vector, if y ( t ) is constant
• The solution sol from a previous integration, if this call
continues that integration
Description
tspan
Interval of integration as a vector [t0,tf] with t0 < tf.
options
Optional integration argument. A structure you create using
the ddeset function. See ddeset for details.
p1,p2,...
Optional parameters that dde23 passes to ddefun, history if
it is a function, and any functions you specify in options.
sol = dde23(ddefun,lags,history,tspan) integrates the system of DDEs
y′ ( t ) = f ( t, y ( t ), y ( t – τ 1 ), …, y ( t – τ k ) )
on the interval [ t 0, t f ] , where τ 1, …, τ k are constant, positive delays and
t0 < t f .
2-459
dde23
dde23 returns the solution as a structure sol. Use the auxiliary function deval
and the output sol to evaluate the solution at specific points tint in the
interval tspan = [t0,tf].
yint = deval(sol,tint)
The structure sol returned by dde23 has the following fields.
sol.x
Mesh selected by dde23
sol.y
Approximation to y ( x ) at the mesh points in sol.x.
sol.yp
Approximation to y′ ( x ) at the mesh points in sol.x
sol.solver
Solver name, 'dde23'
sol = dde23(ddefun,lags,history,tspan,options) solves as above with
default integration properties replaced by values in options, an argument
created with ddeset. See ddeset and “Initial Value Problems for DDEs” in the
MATLAB documentation for details.
Commonly used options are scalar relative error tolerance 'RelTol' (1e-3 by
default) and vector of absolute error tolerances 'AbsTol' (all components are
1e-6 by default).
Use the 'Jumps' option to solve problems with discontinuities in the history or
solution. Set this option to a vector that contains the locations of
discontinuities in the solution prior to t0 (the history) or in coefficients of the
equations at known values of t after t0.
Use the 'Events' option to specify a function that dde23 calls to find where
functions g ( t, y ( t ), y ( t – τ 1 ), …, y ( t – τ k ) ) vanish. This function must be of the
form
[value,isterminal,direction] = events(t,y,Z)
and contain an event function for each event to be tested. For the kth event
function in events:
• value(k) is the value of the kth event function.
• isterminal(k) = 1 if you want the integration to terminate at a zero of this
event function and 0 otherwise.
2-460
dde23
• direction(k) = 0 if you want dde23 to compute all zeros of this event
function, +1 if only zeros where the event function increases, and -1 if only
zeros where the event function decreases.
If you specify the 'Events' option and events are detected, the output
structure sol also includes fields:
sol.xe
Row vector of locations of all events, i.e., times when an event
function vanished
sol.ye
Matrix whose columns are the solution values corresponding to
times in sol.xe
sol.ie
Vector containing indices that specify which event occurred at
the corresponding time in sol.xe
sol = dde23(ddefun,lags,history,tspan,options,p1,p2,...) passes the
parameters p1,p2,... to the DDE function as ddefun(t,y,z,p1,p2,...), to
the history function, if there is one, as history (t,p1,p2,...), and similarly
to all functions specified in options. Use options = [] as a place holder if no
options are set.
Examples
This example solves a DDE on the interval [0, 5] with lags 1 and 0.2. The
function ddex1de computes the delay differential equations, and ddex1hist
computes the history for t <= 0.
Note The demo ddex1 contains the complete code for this example. To see the
code in an editor, click the example name, or type edit ddex1 at the command
line. To run the example type ddex1 at the command line.
sol = dde23(@ddex1de,[1, 0.2],@ddex1hist,[0, 5]);
This code evaluates the solution at 100 equally spaced points in the interval
[0,5], then plots the result.
tint = linspace(0,5);
yint = deval(sol,tint);
plot(tint,yint);
2-461
dde23
ddex1 shows how you can code this problem using subfunctions. For more
examples see ddex2.
Algorithm
dde23 tracks discontinuities and integrates with the explicit Runge-Kutta (2,3)
pair and interpolant of ode23. It uses iteration to take steps longer than the
lags.
See Also
ddeget, ddeset, deval, @ (function_handle)
References
L.F. Shampine and S. Thompson, “Solving DDEs in MATLAB,” Applied
Numerical Mathematics, Vol. 37, 2001, pp. 441-458.
2-462
ddeadv
Purpose
2ddeadv
Set up advisory link
Syntax
rc
rc
rc
rc
Description
ddeadv sets up an advisory link between MATLAB and a server application.
When the data identified by the item argument changes, the string specified
by the callback argument is passed to the eval function and evaluated. If the
advisory link is a hot link, DDE modifies upmtx, the update matrix, to reflect
the data in item.
=
=
=
=
ddeadv(channel,'item','callback')
ddeadv(channel,'item','callback','upmtx')
ddeadv(channel,'item','callback','upmtx',format)
ddeadv(channel,'item','callback','upmtx',format,timeout)
If you omit optional arguments that are not at the end of the argument list, you
must substitute the empty matrix for the missing argument(s).
If successful, ddeadv returns 1 in variable, rc. Otherwise it returns 0.
Arguments
channel
Conversation channel from ddeinit.
item
String specifying the DDE item name for the advisory link.
Changing the data identified by item at the server triggers the
advisory link.
callback
String specifying the callback that is evaluated on update
notification. Changing the data identified by item at the server
causes callback to get passed to the eval function to be
evaluated.
upmtx
String specifying the name of a matrix that holds data sent
with an update notification. If upmtx is included, changing
item at the server causes upmtx to be updated with the revised
data. Specifying upmtx creates a hot link. Omitting upmtx or
specifying it as an empty string creates a warm link. If upmtx
exists in the workspace, its contents are overwritten. If upmtx
does not exist, it is created.
(optional)
2-463
ddeadv
format
(optional)
timeout
(optional)
Examples
Two-element array specifying the format of the data to be sent
on update. The first element specifies the Windows clipboard
format to use for the data. The only currently supported format
is cf_text, which corresponds to a value of 1. The second
element specifies the type of the resultant matrix. Valid types
are numeric (the default, which corresponds to a value of 0)
and string (which corresponds to a value of 1). The default
format array is [1 0].
Scalar specifying the time-out limit for this operation. timeout
is specified in milliseconds. (1000 milliseconds = 1 second). If
advisory link is not established within timeout milliseconds,
the function fails. The default value of timeout is three
seconds.
Set up a hot link between a range of cells in Excel (Row 1, Column 1 through
Row 5, Column 5) and the matrix x. If successful, display the matrix:
rc = ddeadv(channel, 'r1c1:r5c5', 'disp(x)', 'x');
Communication with Excel must have been established previously with a
ddeinit command.
See Also
2-464
ddeexec, ddeinit, ddepoke, ddereq, ddeterm, ddeunadv
ddeexec
Purpose
2ddeexec
Send string for execution
Syntax
rc = ddeexec(channel,'command')
rc = ddeexec(channel,'command','item')
rc = ddeexec(channel,'command','item',timeout)
Description
ddeexec sends a string for execution to another application via an established
DDE conversation. Specify the string as the command argument.
If you omit optional arguments that are not at the end of the argument list, you
must substitute the empty matrix for the missing argument(s).
If successful, ddeexec returns 1 in variable, rc. Otherwise it returns 0.
Arguments
channel
Conversation channel from ddeinit.
command
String specifying the command to be executed.
item
String specifying the DDE item name for execution. This
argument is not used for many applications. If your application
requires this argument, it provides additional information for
command. Consult your server documentation for more
information.
(optional)
timeout
(optional)
Examples
Scalar specifying the time-out limit for this operation. timeout
is specified in milliseconds. (1000 milliseconds = 1 second). The
default value of timeout is three seconds.
Given the channel assigned to a conversation, send a command to Excel:
rc = ddeexec(channel,'[formula.goto("r1c1")]')
Communication with Excel must have been established previously with a
ddeinit command.
See Also
ddeadv, ddeinit, ddepoke, ddereq, ddeterm, ddeunadv
2-465
ddeget
Purpose
2ddeget
Extract properties from options structure created with ddeset
Syntax
val = ddeget(options,'name')
val = ddeget(options,'name',default)
Description
val = ddeget(options,'name') extracts the value of the named property
from the structure options, returning an empty matrix if the property value is
not specified in options. It is sufficient to type only the leading characters that
uniquely identify the property. Case is ignored for property names. [] is a valid
options argument.
val = ddeget(options,'name',default) extracts the named property as
above, but returns val = default if the named property is not specified in
options. For example,
val = ddeget(opts,'RelTol',1e-4);
returns val = 1e-4 if the RelTol is not specified in opts.
See Also
2-466
dde23, ddeset
ddeinit
Purpose
2ddeinit
Initiate DDE conversation
Syntax
channel = ddeinit('service','topic')
Description
channel = ddeinit('service','topic') returns a channel handle assigned
to the conversation, which is used with other MATLAB DDE functions.
'service' is a string specifying the service or application name for the
conversation. 'topic' is a string specifying the topic for the conversation.
Examples
To initiate a conversation with Excel for the spreadsheet 'stocks.xls':
channel = ddeinit('excel','stocks.xls')
channel =
0.00
See Also
ddeadv, ddeexec, ddepoke, ddereq, ddeterm, ddeunadv
2-467
ddepoke
Purpose
2ddepoke
Send data to application
Syntax
rc = ddepoke(channel,'item',data)
rc = ddepoke(channel,'item',data,format)
rc = ddepoke(channel,'item',data,format,timeout)
Description
ddepoke sends data to an application via an established DDE conversation.
ddepoke formats the data matrix as follows before sending it to the server
application:
• String matrices are converted, element by element, to characters and the
resulting character buffer is sent.
• Numeric matrices are sent as tab-delimited columns and carriage-return,
line-feed delimited rows of numbers. Only the real part of nonsparse
matrices are sent.
If you omit optional arguments that are not at the end of the argument list, you
must substitute the empty matrix for the missing argument(s).
If successful, ddepoke returns 1 in variable, rc. Otherwise it returns 0.
Arguments
channel
Conversation channel from ddeinit.
item
String specifying the DDE item for the data sent. Item is the
server data entity that is to contain the data sent in the data
argument.
data
Matrix containing the data to send.
format
Scalar specifying the format of the data requested. The value
indicates the Windows clipboard format to use for the data
transfer. The only format currently supported is cf_text,
which corresponds to a value of 1.
(optional)
timeout
(optional)
2-468
Scalar specifying the time-out limit for this operation. timeout
is specified in milliseconds. (1000 milliseconds = 1 second). The
default value of timeout is three seconds.
ddepoke
Examples
Assume that a conversation channel with Excel has previously been
established with ddeinit. To send a 5-by-5 identity matrix to Excel, placing the
data in Row 1, Column 1 through Row 5, Column 5:
rc = ddepoke(channel, 'r1c1:r5c5', eye(5));
See Also
ddeadv, ddeexec, ddeinit, ddereq, ddeterm, ddeunadv
2-469
ddereq
Purpose
2ddereq
Request data from application
Syntax
data = ddereq(channel,'item')
data = ddereq(channel,'item',format)
data = ddereq(channel,'item',format,timeout)
Description
ddereq requests data from a server application via an established DDE
conversation. ddereq returns a matrix containing the requested data or an
empty matrix if the function is unsuccessful.
If you omit optional arguments that are not at the end of the argument list, you
must substitute the empty matrix for the missing argument(s).
If successful, ddereq returns a matrix containing the requested data in
variable, data. Otherwise, it returns an empty matrix.
Arguments
channel
Conversation channel from ddeinit.
item
String specifying the server application's DDE item name for
the data requested.
format
Two-element array specifying the format of the data requested.
The first element specifies the Windows clipboard format to
use. The only currently supported format is cf_text, which
corresponds to a value of 1. The second element specifies the
type of the resultant matrix. Valid types are numeric (the
default, which corresponds to 0) and string (which
corresponds to a value of 1). The default format array is [1 0].
(optional)
timeout
(optional)
Examples
Scalar specifying the time-out limit for this operation. timeout
is specified in milliseconds. (1000 milliseconds = 1 second). The
default value of timeout is three seconds.
Assume that we have an Excel spreadsheet stocks.xls. This spreadsheet
contains the prices of three stocks in row 3 (columns 1 through 3) and the
number of shares of these stocks in rows 6 through 8 (column 2). Initiate
conversation with Excel with the command:
channel = ddeinit('excel','stocks.xls')
2-470
ddereq
DDE functions require the rxcy reference style for Excel worksheets. In Excel
terminology the prices are in r3c1:r3c3 and the shares in r6c2:r8c2.
To request the prices from Excel:
prices = ddereq(channel,'r3c1:r3c3')
prices =
42.50
15.00
78.88
To request the number of shares of each stock:
shares = ddereq(channel, 'r6c2:r8c2')
shares =
100.00
500.00
300.00
See Also
ddeadv, ddeexec, ddeinit, ddepoke, ddeterm, ddeunadv
2-471
ddeset
Purpose
2ddeset
Create/alter delay differential equations (DDE) options structure
Syntax
options = ddeset('name1',value1,'name2',value2,...)
options = ddeset(oldopts,'name1',value1,...)
options = ddeset(oldopts,newopts)
ddeset
Description
options = ddeset('name1',value1,'name2',value2,...) creates an
integrator options structure options in which the named properties have the
specified values. Any unspecified properties have default values. It is sufficient
to type only the leading characters that uniquely identify the property. Case is
ignored for property names.
options = ddeset(oldopts,'name1',value1,...) alters an existing options
structure oldopts.
options = ddeset(oldopts,newopts) combines an existing options structure
oldopts with a new options structure newopts. Any new properties overwrite
corresponding old properties.
ddeset with no input arguments displays all property names and their possible
values.
DDE Properties
These properties are available:
Property
Value
Description
RelTol
Positive scalar
{1e-3}
Relative error tolerance that applies to all components
of the solution vector. The estimated error in each
integration step satisfies
|e(i)| <= max(RelTol*abs(y(i)),AbsTol(i)).
AbsTol
Positive scalar or
vector {1e-6}
Absolute error tolerance that applies to all components
of the solution vector. Elements of a vector of tolerances
apply to corresponding components of the solution
vector.
2-472
ddeset
Property
Value
Description
NormControl
on | {off}
Control error relative to norm of solution. Set this
property on to request that dde23 control the error in
each integration step with
norm(e) <= max(RelTol*norm(y),AbsTol). By default
dde23 uses a more stringent component-wise error
control.
Stats
on | {off}
Display computational cost statistics.
Events
Function
The solver uses the specified function to locate where
functions of t, y, Z vanish. See dde23 for details.
MaxStep
Positive scalar
{0.1*tspan}
Upper bound on the magnitude of the step size. The
default is one-tenth of the tspan interval.
InitialStep
Positive scalar
Suggested initial step size. The solver tries this first. By
default the solver determines an initial step size
automatically.
OutputFcn
Function
Installable output function. This output function is
called by the solver after each time step. When a solver
is called with no output arguments, OutputFcn defaults
to the function odeplot. Otherwise, OutputFcn defaults
to [].
To create or modify an output function, see ODE Solver
Output Properties in the “Differential Equations”
section of the MATLAB documentation.
OutputSel
Vector of integers
Output selection indices. Specifies the components of
the solution vector that dde23 passes to the OutputFcn.
The default is all components.
2-473
ddeset
Property
Value
Description
Jumps
Vector
Location of discontinuities in solution. Points t where
the history or solution may have a jump discontinuity in
a low-order derivative. See dde23 for details.
InitialY
Vector
Initial value of solution. By default the initial value of
the solution is the value returned by history at the
initial point. A different initial value can be supplied as
the value of the InitialY property.
See Also
2-474
dde23, ddeget, @ (function_handle)
ddeterm
Purpose
2ddeterm
Terminate DDE conversation
Syntax
rc = ddeterm(channel)
Description
rc = ddeterm(channel) accepts a channel handle returned by a previous call
to ddeinit that established the DDE conversation. ddeterm terminates this
conversation. rc is a return code where 0 indicates failure and 1 indicates
success.
Examples
To close a conversation channel previously opened with ddeinit:
rc = ddeterm(channel)
rc =
1.00
See Also
ddeadv, ddeexec, ddeinit, ddepoke, ddereq, ddeunadv
2-475
ddeunadv
Purpose
2ddeunadv
Release advisory link
Syntax
rc = ddeunadv(channel,'item')
rc = ddeunadv(channel,'item',format)
rc = ddeunadv(channel,'item',format,timeout)
Description
ddeunadv releases the advisory link between MATLAB and the server
application established by an earlier ddeadv call. The channel, item, and
format must be the same as those specified in the call to ddeadv that initiated
the link. If you include the timeout argument but accept the default format,
you must specify format as an empty matrix.
If successful, ddeunadv returns 1 in variable, rc. Otherwise it returns 0.
Arguments
channel
Conversation channel from ddeinit.
item
String specifying the DDE item name for the advisory link.
Changing the data identified by item at the server triggers the
advisory link.
format
Two-element array. This must be the same as the format
argument for the corresponding ddeadv call.
(optional)
timeout
(optional)
Example
Scalar specifying the time-out limit for this operation. timeout
is specified in milliseconds. (1000 milliseconds = 1 second). The
default value of timeout is three seconds.
To release an advisory link established previously with ddeadv:
rc = ddeunadv(channel, 'r1c1:r5c5')
rc =
1.00
See Also
2-476
ddeadv, ddeexec, ddeinit, ddepoke, ddereq, ddeterm
deal
Purpose
2deal
Deal inputs to outputs
Syntax
[Y1,Y2,Y3,...] = deal(X)
[Y1,Y2,Y3,...] = deal(X1,X2,X3,...)
Description
[Y1,Y2,Y3,...] = deal(X) copies the single input to all the requested
outputs. It is the same as Y1 = X, Y2 = X, Y3 = X, ...
[Y1,Y2,Y3,...] = deal(X1,X2,X3,...) is the same as Y1 = X1; Y2 = X2;
Y3 = X3; ...
Remarks
deal is most useful when used with cell arrays and structures via comma
separated list expansion. Here are some useful constructions:
[S.field] = deal(X) sets all the fields with the name field in the structure
array S to the value X. If S doesn't exist, use [S(1:m).field] = deal(X).
[X{:}] = deal(A.field) copies the values of the field with name field to
the cell array X. If X doesn't exist, use [X{1:m}] = deal(A.field).
[Y1,Y2,Y3,...] = deal(X{:}) copies the contents of the cell array X to the
separate variables Y1,Y2,Y3,...
[Y1,Y2,Y3,...] = deal(S.field) copies the contents of the fields with the
name field to separate variables Y1,Y2,Y3,...
Examples
Use deal to copy the contents of a 4-element cell array into four separate
output variables.
C = {rand(3) ones(3,1) eye(3) zeros(3,1)};
[a,b,c,d] = deal(C{:})
a =
0.9501
0.2311
0.6068
0.4860
0.8913
0.7621
0.4565
0.0185
0.8214
b =
2-477
deal
1
1
1
c =
1
0
0
0
1
0
0
0
1
d =
0
0
0
Use deal to obtain the contents of all the name fields in a structure array:
A.name = 'Pat'; A.number = 176554;
A(2).name = 'Tony'; A(2).number = 901325;
[name1,name2] = deal(A(:).name)
name1 =
Pat
name2 =
Tony
2-478
deblank
Purpose
2deblank
Strip trailing blanks from the end of a string
Syntax
str = deblank(str)
c = deblank(c)
Description
str = deblank(str) removes the trailing blanks from the end of a character
string str.
c = deblank(c), when c is a cell array of strings, applies deblank to each
element of c.
The deblank function is useful for cleaning up the rows of a character array.
Examples
A{1,1}
A{1,2}
A{2,1}
A{2,2}
=
=
=
=
'MATLAB
';
'SIMULINK
';
'Toolboxes
';
'The MathWorks
';
A =
'MATLAB
'
'Toolboxes
'
'SIMULINK
'
'The MathWorks
'
deblank(A)
ans =
'MATLAB'
'Toolboxes'
'SIMULINK'
'The MathWorks'
2-479
dec2base
Purpose
2dec2base
Decimal number to base conversion
Syntax
str = dec2base(d,base)
str = dec2base(d,base,n)
Description
str = dec2base(d,base) converts the nonnegative integer d to the specified
base.d must be a nonnegative integer smaller than 2^52, and base must be an
integer between 2 and 36. The returned argument str is a string.
str = dec2base(d,base,n) produces a representation with at least n digits.
Examples
The expression dec2base(23,2) converts 2310 to base 2, returning the string
'10111'.
See Also
base2dec
2-480
dec2bin
Purpose
2dec2bin
Decimal to binary number conversion
Syntax
str = dec2bin(d)
str = dec2bin(d,n)
Description
str = dec2bin(d) returns the binary representation of d as a string. d must
be a nonnegative integer smaller than 2^52.
str = dec2bin(d,n) produces a binary representation with at least n bits.
Examples
ans =
10111
See Also
bin2dec, dec2hex
2-481
dec2hex
Purpose
2dec2hex
Decimal to hexadecimal number conversion
Syntax
str = dec2hex(d)
str = dec2hex(d,n)
Description
str = dec2hex(d) converts the decimal integer d to its hexadecimal
representation stored in a MATLAB string. d must be a nonnegative integer
smaller than 2^52.
str = dec2hex(d,n) produces a hexadecimal representation with at least n
digits.
Examples
To convert decimal 1023 to hexadecimal,
dec2hex(1023)
ans =
3FF
See Also
2-482
dec2bin, format, hex2dec, hex2num
deconv
Purpose
2deconv
Deconvolution and polynomial division
Syntax
[q,r] = deconv(v,u)
Description
[q,r] = deconv(v,u) deconvolves vector u out of vector v, using long division.
The quotient is returned in vector q and the remainder in vector r such that v
= conv(u,q)+r.
If u and v are vectors of polynomial coefficients, convolving them is equivalent
to multiplying the two polynomials, and deconvolution is polynomial division.
The result of dividing v by u is quotient q and remainder r.
Examples
If
u = [1
v = [10
2
3
20
4]
30]
the convolution is
c = conv(u,v)
c =
10
40
100
160
170
120
Use deconvolution to recover u:
[q,r] = deconv(c,u)
q =
10
20
30
r =
0
0
0
0
0
0
This gives a quotient equal to v and a zero remainder.
Algorithm
deconv uses the filter primitive.
See Also
conv, residue
2-483
del2
Purpose
2del2
Discrete Laplacian
Syntax
L
L
L
L
Definition
If the matrix U is regarded as a function u ( x, y ) evaluated at the point on a
square grid, then 4*del2(U) is a finite difference approximation of Laplace’s
differential operator applied to u , that is:
=
=
=
=
del2(U)
del2(U,h)
del2(U,hx,hy)
del2(U,hx,hy,hz,...)
2
2
2
∇ u 1  d u d u
l = ----------- = ---  ---------- + ----------
4
4  dx 2 d y 2
where:
1
l ij = --- ( u i + 1, j + u i – 1, j + u i,
4
j+1
+ u i,
j – 1 ) – u i,
in the interior. On the edges, the same formula is applied to a cubic
extrapolation.
For functions of more variables u ( x, y, z, … ) , del2(U) is an approximation,
2
2
2
2

∇ u
1 d u d u d u
l = ----------- = ---------  ---------- + ---------- + ---------- + …
2 N 2 N  dx 2 d y 2 dz 2

where N is the number of variables in u .
Description
L = del2(U) where U is a rectangular array is a discrete approximation of
2
2
2
∇ u 1  d u d u
l = ----------- = ---  ---------- + ----------
4
4  dx 2 d y 2
The matrix L is the same size as U with each element equal to the difference
between an element of U and the average of its four neighbors.
2-484
del2
-L = del2(U) when U is an multidimensional array, returns an
approximation of
2
∇ u
----------2N
where N is ndims(u).
L = del2(U,h) where H is a scalar uses H as the spacing between points in each
direction (h=1 by default).
L = del2(U,hx,hy) when U is a rectangular array, uses the spacing specified
by hx and hy. If hx is a scalar, it gives the spacing between points in the
x-direction. If hx is a vector, it must be of length size(u,2) and specifies the
x-coordinates of the points. Similarly, if hy is a scalar, it gives the spacing
between points in the y-direction. If hy is a vector, it must be of length
size(u,1) and specifies the y-coordinates of the points.
L = del2(U,hx,hy,hz,...) where U is multidimensional uses the spacing
given by hx, hy, hz, ...
Examples
The function
u ( x, y ) = x 2 + y 2
has
∇2u = 4
For this function, 4*del2(U) is also 4.
[x,y] = meshgrid(-4:4,-3:3);
U = x.*x+y.*y
U =
25
18
13
10
20
13
8
5
17
10
5
2
16
9
4
1
17
10
5
2
20
13
8
5
25
18
13
10
9
4
1
0
1
4
9
10
5
2
1
2
5
10
13
8
5
4
5
8
13
18
13
10
9
10
13
18
25
20
17
16
17
20
25
2-485
del2
V = 4*del2(U)
V =
4
4
4
4
4
4
4
4
4
4
4
4
4
4
See Also
2-486
diff, gradient
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
4
delaunay
Purpose
2delaunay
Delaunay triangulation
Syntax
TRI = delaunay(x,y)
Definition
Given a set of data points, the Delaunay triangulation is a set of lines
connecting each point to its natural neighbors. The Delaunay triangulation is
related to the Voronoi diagram— the circle circumscribed about a Delaunay
triangle has its center at the vertex of a Voronoi polygon.
x
Delaunay triangle
Voronoi polygon
Description
TRI = delaunay(x,y) for the data points defined by vectors x and y, returns a
set of triangles such that no data points are contained in any triangle's
circumscribed circle. Each row of the m-by-3 matrix TRI defines one such
triangle and contains indices into x and y. If the original data points are
collinear or x is empty, the triangles cannot be computed and delaunay returns
an empty matrix.
Remarks
The Delaunay triangulation is used by: griddata (to interpolate scattered
data), voronoi (to compute the voronoi diagram), and is useful by itself to
create a triangular grid for scattered data points.
The functions dsearch and tsearch search the triangulation to find nearest
neighbor points or enclosing triangles, respectively.
Visualization
Use one of these functions to plot the output of delaunay:
2-487
delaunay
triplot
Displays the triangles defined in the m-by-3 matrix TRI. See
Example 1.
trisurf
Displays each triangle defined in the m-by-3 matrix TRI as a
surface in 3-D space. To see a 2-D surface, you can supply a
vector of some constant value for the third dimension. For
example
trisurf(TRI,x,y,zeros(size(x)))
See Example 2.
trimesh
Displays each triangle defined in the m-by-3 matrix TRI as a
mesh in 3-D space. To see a 2-D surface, you can supply a vector
of some constant value for the third dimension. For example,
trimesh(TRI,x,y,zeros(size(x)))
produces almost the same result as triplot, except in 3-D
space. See Example 2.
Examples
Example 1. Plot the Delaunay triangulation for 10 randomly generated points.
rand('state',0);
x = rand(1,10);
y = rand(1,10);
TRI = delaunay(x,y);
subplot(1,2,1),...
triplot(TRI,x,y)
axis([0 1 0 1]);
hold on;
plot(x,y,'or');
hold off
Compare the Voronoi diagram of the same points:
[vx, vy] = voronoi(x,y,TRI);
subplot(1,2,2),...
plot(x,y,'r+',vx,vy,'b-'),...
axis([0 1 0 1])
2-488
delaunay
Delaunay
triangulation
1
1
0.9
0.9
0.8
0.8
0.7
0.7
0.6
0.6
0.5
0.5
0.4
0.4
0.3
0.3
0.2
0.2
0.1
0.1
0
0
0.2
0.4
0.6
0.8
1
0
Voronoi
diagram
0
0.2
0.4
0.6
0.8
1
Example 2. Create a 2-D grid then use trisurf to plot its Delaunay
triangulation in 3-D space by using 0s for the third dimension.
[x,y] = meshgrid(1:15,1:15);
tri = delaunay(x,y);
trisurf(tri,x,y,zeros(size(x)))
2-489
delaunay
1
0.5
0
−0.5
−1
15
15
10
10
5
5
0
0
Next, generate peaks data as a 15-by-15 matrix, and use that data with the
Delaunay triangulation to produce a surface in 3-D space.
z = peaks(15);
trisurf(tri,x,y,z)
10
5
0
−5
−10
15
15
10
10
5
5
0
2-490
0
delaunay
You can use the same data with trimesh to produce a mesh in 3-D space.
trimesh(tri,x,y,z)
10
5
0
−5
−10
15
15
10
10
5
5
0
0
Algorithm
delaunay is based on Qhull . It uses the Qhull joggle option ('QJ'). For
information about qhull, see http://www.geom.umn.edu/software/qhull/.
For copyright information, see
http://www.geom.umn.edu/software/download/COPYING.html.
See Also
delaunay3, delaunayn, dsearch, griddata, plot, triplot, trimesh, trisurf,
tsearch, voronoi
References
[1] Barber, C. B., D.P. Dobkin, and H.T. Huhdanpaa, "The Quickhull Algorithm for
Convex Hulls," ACM Transactions on Mathematical Software, Vol. 22, No. 4,
Dec. 1996, p. 469-483. Available in HTML format at
http://www.acm.org/pubs/citations/journals/toms/1996-22-4/p469-bar
ber/ and in PostScript format at
ftp://geom.umn.edu/pub/software/qhull-96.ps.
[2] National Science and Technology Research Center for Computation and
Visualization of Geometric Structures (The Geometry Center), University of
Minnesota. 1993.
2-491
delaunay3
Purpose
2delaunay3
3-D Delaunay tessellation
Syntax
TES = delaunay3(x,y,z)
Description
TES = delaunay3(x,y,z) returns an array TES, each row of which contains the
indices of the points in (x,y,z) that make up a tetrahedron in the tessellation
of (x,y,z). TES is a numtes-by-4 array where numtes is the number of facets in
the tessellation. x, y, and z are vectors of equal length. If the original data
points are collinear or x, y, and z define an insufficient number of points, the
triangles cannot be computed and delaunay3 returns an empty matrix.
Visualization
Use tetramesh to plot delaunay3 output. tetramesh displays the tetrahedrons
defined in TES as mesh. tetramesh uses the default tranparency parameter
value 'FaceAlpha' = 0.9.
Example
This example generates a 3-D Delaunay tessellation, then uses tetramesh to
plot the tetrahedrons that form the corresponding simplex. camorbit rotates
the camera position to provide a meaningful view of the figure.
d = [-1 1];
[x,y,z] = meshgrid(d,d,d); % A cube
x = [x(:);0];
y = [y(:);0];
z = [z(:);0];
% [x,y,z] are corners of a cube plus the center.
Tes = delaunay3(x,y,z)
Tes =
9
3
2
2
2
7
7
8
8
8
2-492
1
9
9
3
3
9
3
7
2
2
5
1
1
9
9
5
9
9
9
9
6
5
6
4
1
6
5
6
6
4
delaunay3
8
8
3
7
9
3
4
9
X = [x(:) y(:) z(:)];
tetramesh(Tes,X);camorbit(20,0)
Algorithm
delaunay3 is based on Qhull [2]. It uses the Qhull joggle option ('QJ'). For
information about qhull, see http://www.geom.umn.edu/software/qhull/.
For copyright information, see
http://www.geom.umn.edu/software/download/COPYING.html.
See Also
delaunay, delaunayn
Reference
[1] Barber, C. B., D.P. Dobkin, and H.T. Huhdanpaa, "The Quickhull Algorithm for
Convex Hulls," ACM Transactions on Mathematical Software, Vol. 22, No. 4,
Dec. 1996, p. 469-483. Available in HTML format at
http://www.acm.org/pubs/citations/journals/toms/1996-22-4/p469-bar
ber/ and in PostScript format at
ftp://geom.umn.edu/pub/software/qhull-96.ps.
2-493
delaunay3
[2] National Science and Technology Research Center for Computation and
Visualization of Geometric Structures (The Geometry Center), University of
Minnesota. 1993.
2-494
delaunayn
Purpose
2delaunayn
n-D Delaunay tessellation
Syntax
T = delaunayn(X)
Description
T = delaunayn(X) computes a set of simplices such that no data points of X are
contained in any circumspheres of the simplices. The set of simplices forms the
Delaunay tessellation. X is an m-by-n array representing m points in n-D space.
T is a numt-by-(n+1) array where each row contains the indices into X of the
vertices of the corresponding simplex.
Visualization
Plotting the output of delaunayn depends of the value of n:
• For n = 2, use triplot, trisurf, or trimesh as you would for delaunay.
• For n = 3, use tetramesh as you would for delaunay3.
For more control over the color of the facets, use patch to plot the output. For
an example, see “Tessellation and Interpolation of Scattered Data in Higher
Dimensions” in the MATLAB documentation.
• You cannot plot delaunayn output for n > 3.
Example
This example generates an n-D Delaunay tessellation, where n = 3.
d = [-1 1];
[x,y,z] = meshgrid(d,d,d); % A cube
x = [x(:);0];
y = [y(:);0];
z = [z(:);0];
% [x,y,z] are corners of a cube plus the center.
X = [x(:) y(:) z(:)];
Tes = delaunayn(X)
Tes =
9
3
2
2
2
7
7
8
1
9
9
3
3
9
3
7
5
1
1
9
9
5
9
9
6
5
6
4
1
6
5
6
2-495
delaunayn
8
8
8
8
2
2
3
7
9
9
9
3
6
4
4
9
You can use tetramesh to visualize the tetrahedrons that form the
corresponding simplex. camorbit rotates the camera position to provide a
meaningful view of the figure.
tetramesh(Tes,X);camorbit(20,0)
Algorithm
delaunayn is based on Qhull [2],. It uses the Qhull joggle option ('QJ'). For
information about qhull, see http://www.geom.umn.edu/software/qhull/.
For copyright information, see
http://www.geom.umn.edu/software/download/COPYING.html.
See Also
convhulln, delaunayn, delaunay3, tetramesh, voronoin
Reference
[1] Barber, C. B., D.P. Dobkin, and H.T. Huhdanpaa, "The Quickhull Algorithm for
Convex Hulls," ACM Transactions on Mathematical Software, Vol. 22, No. 4,
Dec. 1996, p. 469-483. Available in HTML format at
2-496
delaunayn
http://www.acm.org/pubs/citations/journals/toms/1996-22-4/p469-bar
ber/ and in PostScript format at
ftp://geom.umn.edu/pub/software/qhull-96.ps.
[2] National Science and Technology Research Center for Computation and
Visualization of Geometric Structures (The Geometry Center), University of
Minnesota. 1993.
2-497
delete
Purpose
2delete
Graphical
Interface
As an alternative to the delete function, you can delete files using the Current
Directory browser.
Syntax
delete filename
delete(h)
delete('filename')
Description
delete filename deletes the named file from the disk. The filename may
Delete files or graphics objects
include an absolute pathname or a pathname relative to the current directory.
The filename may also include wildcards, (*).
delete(h) deletes the graphics object with handle h. The function deletes the
object without requesting verification even if the object is a window.
delete('filename') is the function form of delete. Use this form when the
filename is stored in a string.
Note MATLAB does not ask for confirmation when you enter the delete
command. To avoid accidentally losing files or graphics objects that you need,
make sure that you have accurately specified the items you want deleted.
Examples
To delete all files with a .mat extension in the ../mytests/ directory, type
delete('../mytests/*.mat')
To delete a directory, use rmdir rather than delete:
rmdir mydirectory
See Also
2-498
dir, edit, mkdir, rmdir, type
delete (COM)
Purpose
2delete (COM)
Delete a COM control or server
Syntax
delete(h)
Arguments
h
Handle for a COM object previously returned from actxcontrol, actxserver,
get, or invoke.
Description
Release all interfaces derived from the specified COM server or control, and
then delete the server or control itself. This is different from releasing an
interface, which releases and invalidates only that interface.
Examples
Create a Microsoft Calender application. Then create a TitleFont interface
and use it to change the appearance of the font of the calendar’s title:
f = figure('pos',[300 300 500 500]);
cal = actxcontrol('mscal.calendar', [0 0 500 500], f);
TFont = get(cal, 'TitleFont')
TFont =
Interface.mscal.calendar.TitleFont
set(TFont, 'Name', 'Viva BoldExtraExtended');
set(TFont, 'Bold', 0);
When you’re finished working with the title font, release the TitleFont
interface:
release(TFont);
Now create a GridFont interface and use it to modify the size of the calendar’s
date numerals:
GFont = get(cal, 'GridFont')
GFont =
Interface.mscal.calendar.GridFont
set(GFont, 'Size', 16);
When you’re done, delete the cal object and the figure window. Deleting the
cal object also releases all interfaces to the object (e.g., GFont):
2-499
delete (COM)
delete(cal);
delete(f);
clear f;
Note that, although the object and interfaces themselves have been destroyed,
the variables assigned to them still reside in the MATLAB workspace until you
remove them with clear.
whos
Name
GFont
TFone
cal
Size
Bytes
1x1
1x1
1x1
Grand total is 3 elements using 0 bytes
See Also
2-500
release, save, load, actxcontrol, actxserver
0
0
0
Class
handle
handle
handle
delete (serial)
Purpose
2delete (serial)
Remove a serial port object from memory
Syntax
delete(obj)
Arguments
obj
Description
delete(obj) removes obj from memory.
Remarks
When you delete obj, it becomes an invalid object. Because you cannot connect
an invalid serial port object to the device, you should remove it from the
workspace with the clear command. If multiple references to obj exist in the
workspace, then deleting one reference invalidates the remaining references.
A serial port object or an array of serial port objects.
If obj is connected to the device, it has a Status property value of open. If you
issue delete while obj is connected, then the connection is automatically
broken. You can also disconnect obj from the device with the fclose function.
If you use the help command to display help for delete, then you need to
supply the pathname shown below.
help serial/delete
Example
This example creates the serial port object s, connects s to the device, writes
and reads text data, disconnects s from the device, removes s from memory
using delete, and then removes s from the workspace using clear.
s = serial('COM1');
fopen(s)
fprintf(s,'*IDN?')
idn = fscanf(s);
fclose(s)
delete(s)
clear s
See Also
Functions
clear, fclose, isvalid
Properties
Status
2-501
delete (timer)
Purpose
2delete (timer)
Remove a timer object from memory
Syntax
delete(obj)
Description
delete(obj) removes timer object, obj, from memory. If obj is an array of
timer objects, delete removes all the objects from memory.
When you delete a timer object, it becomes invalid and cannot be reused. Use
the clear command to remove invalid timer objects from the workspace.
If multiple references to a timer object exist in the workspace, deleting the
timer object invalidates the remaining references. Use the clear command to
remove the remaining references to the object from the workspace.
See Also
2-502
clear, isvalid, timer
deleteproperty (COM)
Purpose
2deleteproperty (COM)
Remove custom property from COM object
Syntax
deleteproperty(h, 'propertyname')
Arguments
h
Handle for a COM object previously returned from actxcontrol, actxserver,
get, or invoke.
propertyname
A string specifying the name of the custom property to delete.
Description
Delete a property, propertyname, from the custom properties belonging to
object or interface, h. You can only delete properties that have been created
with addproperty.
Examples
Create an mwsamp control and add a new property named Position to it. Assign
an array value to the property:
f = figure('pos', [100 200 200 200]);
h = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200], f);
get(h)
Label: 'Label'
Radius: 20
addproperty(h, 'Position');
set(h, 'Position', [200 120]);
get(h)
Label: 'Label'
Radius: 20
Position: [200 120]
Delete the custom Position property:
deleteproperty(h, 'Position');
get(h)
Label: 'Label'
Radius: 20
See Also
addproperty, get, set, inspect
2-503
demo
Purpose
2demo
Access product demos via Help browser
Syntax
demo
demo subtopic
demo subtopic category
Description
demo opens the Demos panel in the Help browser. In the left pane, expand the
listing for a product area (for example, MATLAB). Within that product area,
expand the listing for a product or product category (for example, MATLAB
Graphics). Select a specific demo from the list (for example, Visualizing Sound).
In the right pane, view instructions for using the demo. For more information,
see Running Demonstrations. For platforms that do not support Java GUIs,
the demos are presented in a non-Java interface. To run a demo from the
command line, type the demo name. For playshow demos, that is those demos
in which the H1 line begins with two comment symbols (%%), type playshow
followed by the demo name.
demo subtopic opens the Demos panel in the Help browser with the specified
subtopic expanded. Subtopics are matlab, toolbox, simulink, and blockset.
demo subtopic product opens the Demos panel in the Help browser to the
specified product or category within the subtopic.
2-504
demo
Type demo to access the Demos panel in the Help browser.
View the demos for products installed on your system. When you choose a
demo, information about it appears in the display pane.
Examples
To run an M-file demo, click this link.
When you click this link, the M-file source code
for the demo appears in your editor.
Accessing Toolbox Demos
To find the demos relating to the Communications Toolbox, type
demo toolbox communication
The Help browser opens to the Demos panel with the Toolbox subtopic
expanded and with the Communications product highlighted and expanded to
show the available demos.
Accessing the Simulink Automotive Demos
To accesses the automotive demos within Simulink, type
demo simulink automotive
2-505
demo
The Demos panel opens with the Simulink subtopic and Automotive category
expanded.
Running a Demo from the Command Line
Type
vibes
to run a visualization demonstration showing an animated L-shaped
membrane.
Running a Playshow Demo from the Command Line
Type
quake
to run an earthquake data demo. Not much appears to happen. This is because
quake is a playshow demo. Verify this by viewing the M-file, quake.m, for
example, by typing
edit quake
The first line, that is, the H1 line for quake is
%% Loma Prieta Earthquake
The %% indicates that quake is a playshow demo. So to run it, type
playshow quake
and the earthquake demo runs.
See Also
2-506
help, helpbrowser, helpwin, lookfor
depdir
Purpose
2depdir
List the dependent directories of an M-file or P-file
Syntax
list = depdir('file_name');
[list,prob_files,prob_sym,prob_strings] = depdir('file_name');
[...] = depdir('file_name1','file_name2',...);
Description
The depdir function lists the directories of all of the functions that a specified
M-file or P-file needs to operate. This function is useful for finding all of the
directories that need to be included with a runtime application and for
determining the runtime path.
list = depdir('file_name') creates a cell array of strings containing the
directories of all the M-files and P-files that file_name.m or file_name.p uses.
This includes the second-level files that are called directly by file_name, as
well as the third-level files that are called by the second-level files, and so on.
[list,prob_files,prob_sym,prob_strings] = depdir('file_name')
creates three additional cell arrays containing information about any problems
with the depdir search. prob_files contains filenames that depdir was
unable to parse. prob_sym contains symbols that depdir was unable to find.
prob_strings contains callback strings that depdir was unable to parse.
[...] = depdir('file_name1','file_name2',...) performs the same
operation for multiple files. The dependent directories of all files are listed
together in the output cell arrays.
Example
See Also
list = depdir('mesh')
depfun
2-507
depfun
Purpose
2depfun
List the dependent functions of an M-file or P-file
Syntax
list = depfun('file_name');
[list,builtins,classes] = depfun('file_name');
[list,builtins,classes,prob_files,prob_sym,eval_strings,...
called_from,java_classes] = depfun('file_name');
[...] = depfun('file_name1','file_name2',...);
[...] = depfun('fig_file_name');
[...] = depfun(...,'-toponly');
Description
The depfun function lists all of the functions and scripts, as well as built-in
functions, that a specified M-file needs to operate. This is useful for finding all
of the M-files that you need to compile for a MATLAB runtime application.
list = depfun('file_name') creates a cell array of strings containing the
paths of all the files that file_name.m uses. This includes the second-level files
that are called directly by file_name.m, as well as the third-level files that are
called by the second-level files, and so on.
Note If depfun reports that “These files could not be parsed:” or if the
prob_files output below is nonempty, then the rest of the output of depfun
might be incomplete. You should correct the problematic files and invoke
depfun again.
[list,builtins,classes] = depfun('file_name') creates three cell arrays
containing information about dependent functions. list contains the paths of
all the files that file_name and its subordinates use. builtins contains the
built-in functions that file_name and its subordinates use. classes contains
the MATLAB classes that file_name and its subordinates use.
[list,builtins,classes,prob_files,prob_sym,eval_strings,...
called_from,java_classes] = depfun('file_name') creates additional cell
arrays or structure arrays containing information about any problems with the
depfun search and about where the functions in list are invoked. The
additional outputs are:
2-508
depfun
• prob_files, which indicates which files depfun was unable to parse, find, or
access. Parsing problems can arise from MATLAB syntax errors. prob_files
is a structure array whose fields are:
- name, which gives the names of the files
- listindex, which tells where the files appeared in list
- errmsg, which describes the problems
• prob_sym, which indicates which symbols depfun was unable to resolve as
functions or variables. It is a structure array whose fields are:
- fcn_id, which tells where the files appeared in list
- name, which gives the names of the problematic symbols
• eval_strings, which indicates usage of these evaluation functions: eval,
evalc, evalin, feval. When preparing a runtime application, you should
examine this output to determine whether an evaluation function invokes a
function that does not appear in list. The output eval_strings is a
structure array whose fields are:
- fcn_name, which give the names of the files that use evaluation functions
- lineno, which gives the line numbers in the files where the evaluation
functions appear
• called_from, a cell array of the same length as list. This cell array is
arranged so that
list(called_from{i})
returns all functions in file_name that invoke the function list{i}.
• java_classes, a cell array of Java class names that file_name and its
subordinates use
[...] = depfun('file_name1','file_name2',...) performs the same
operation for multiple files. The dependent functions of all files are listed
together in the output arrays.
[...] = depfun('fig_file_name') looks for dependent functions among the
callback strings of the GUI elements that are defined in the .fig or .mat file
named fig_file_name.
[...] = depfun(...,'-toponly') differs from the other syntaxes of depfun
in that it examines only the files listed explicitly as input arguments. It does
2-509
depfun
not examine the files on which they depend. In this syntax, the flag '-toponly'
must be the last input argument.
Notes
1 If depfun does not find a file called hginfo.mat on the path, then it creates
one. This file contains information about Handle Graphics callbacks.
2 If your application uses toolbar items from the MATLAB default figure
window, then you must include 'FigureToolBar.fig' in your input to
depfun.
3 If your application uses menu items from the MATLAB default figure
window, then you must include 'FigureMenuBar.fig' in your input to
depfun.
4 Because many built-in Handle Graphics functions invoke newplot, the list
produced by depfun always includes the functions on which newplot is
dependent:
- 'matlabroot\toolbox\matlab\graphics\newplot.m'
- 'matlabroot\toolbox\matlab\graphics\closereq.m'
- 'matlabroot\toolbox\matlab\graphics\gcf.m'
- 'matlabroot\toolbox\matlab\graphics\gca.m'
- 'matlabroot\toolbox\matlab\graphics\private\clo.m'
- 'matlabroot\toolbox\matlab\general\@char\delete.m'
- 'matlabroot\toolbox\matlab\lang\nargchk.m'
- 'matlabroot\toolbox\matlab\uitools\allchild.m'
- 'matlabroot\toolbox\matlab\ops\setdiff.m'
- 'matlabroot\toolbox\matlab\ops\@cell\setdiff.m'
- 'matlabroot\toolbox\matlab\iofun\filesep.m'
- 'matlabroot\toolbox\matlab\ops\unique.m'
- 'matlabroot\toolbox\matlab\elmat\repmat.m'
- 'matlabroot\toolbox\matlab\datafun\sortrows.m'
- 'matlabroot\toolbox\matlab\strfun\deblank.m'
- 'matlabroot\toolbox\matlab\ops\@cell\unique.m'
- 'matlabroot\toolbox\matlab\strfun\@cell\deblank.m'
- 'matlabroot\toolbox\matlab\datafun\@cell\sort.m'
- 'matlabroot\toolbox\matlab\strfun\cellstr.m'
- 'matlabroot\toolbox\matlab\datatypes\iscell.m'
- 'matlabroot\toolbox\matlab\strfun\iscellstr.m'
2-510
depfun
- 'matlabroot\toolbox\matlab\datatypes\cellfun.dll'
Examples
See Also
list = depfun('mesh'); % Files mesh.m depends on
list = depfun('mesh','-toponly') % Files mesh.m depends on
directly
[list,builtins,classes] = depfun('gca');
depdir, profile
2-511
det
Purpose
2det
Matrix determinant
Syntax
d = det(X)
Description
d = det(X) returns the determinant of the square matrix X. If X contains only
integer entries, the result d is also an integer.
Remarks
Using det(X) == 0 as a test for matrix singularity is appropriate only for
matrices of modest order with small integer entries. Testing singularity using
abs(det(X)) <= tolerance is not recommended as it is difficult to choose the
correct tolerance. The function cond(X) can check for singular and nearly
singular matrices.
Algorithm
The determinant is computed from the triangular factors obtained by Gaussian
elimination
[L,U] = lu(A)
s = det(L)
% This is always +1 or -1
det(A) = s*prod(diag(U))
Examples
The statement A = [1
2
3;
4
5
6;
7
8
9]
produces
A =
1
4
7
2
5
8
3
6
9
This happens to be a singular matrix, so d = det(A) produces d = 0.
Changing A(3,3) with A(3,3) = 0 turns A into a nonsingular matrix. Now
d = det(A) produces d = 27.
See Also
cond, condest, inv, lu, rref
The arithmetic operators \, /
2-512
detrend
Purpose
2detrend
Remove linear trends.
Syntax
y = detrend(x)
y = detrend(x,'constant')
y = detrend(x,'linear',bp)
Description
detrend removes the mean value or linear trend from a vector or matrix,
usually for FFT processing.
y = detrend(x) removes the best straight-line fit from vector x and returns it
in y. If x is a matrix, detrend removes the trend from each column.
y = detrend(x,'constant') removes the mean value from vector x or, if x is
a matrix, from each column of the matrix.
y = detrend(x,'linear',bp) removes a continuous, piecewise linear trend
from vector x or, if x is a matrix, from each column of the matrix. Vector bp
contains the indices of the breakpoints between adjacent linear segments. The
breakpoint between two segments is defined as the data point that the two
segments share.
breakpoints
detrend(x,'linear'), with no breakpoint vector specified, is the same as
detrend(x).
Example
sig = [0 1 -2 1 0 1 -2 1 0];
trend = [0 1 2 3 4 3 2 1 0];
x = sig+trend;
y = detrend(x,'linear',5)
%
%
%
%
signal with no linear trend
two-segment linear trend
signal with added trend
breakpoint at 5th element
2-513
detrend
y =
-0.0000
1.0000
-2.0000
1.0000
0.0000
1.0000
-2.0000
1.0000
-0.0000
Note that the breakpoint is specified to be the fifth element, which is the data
point shared by the two segments.
Algorithm
detrend computes the least-squares fit of a straight line (or composite line for
piecewise linear trends) to the data and subtracts the resulting function from
the data. To obtain the equation of the straight-line fit, use polyfit.
See Also
2-514
polyfit
deval
Purpose
2deval
Evaluate the solution of a differential equation problem
Syntax
sxint
sxint
sxint
sxint
Description
sxint = deval(sol,xint) and sxint = deval(xint,sol) evaluate the
solution of a differential equation problem. sol is a structure returned by one
=
=
=
=
deval(sol,xint)
deval(xint,sol)
deval(sol,xint,idx)
deval(xint,sol,idx)
of these solvers:
• An initial value problem solver (ode45, ode23, ode113, ode15s, ode23s,
ode23t, ode23tb),
• The delay differential equations solver (dde23),
• The boundary value problem solver (bvp4c).
xint is a point or a vector of points at which you want the solution. The
elements of xint must be in the interval [sol.x(1),sol.x(end)]. For each i,
sxint(:,i) is the solution at xint(i).
sxint = deval(sol,xint,idx) and sxint = deval(xint,sol,idx) evaluate
as above but return only the solution components with indices listed in idx.
Example
This example solves the system y′ = vdp1 ( t, y ) using ode45, and evaluates
and plots the first component of the solution at 100 points in the interval
[0,20].
sol = ode45(@vdp1,[0 20],[2 0]);
x = linspace(0,20,100);
y = deval(sol,x,1);
plot(x,y);
2-515
deval
2.5
2
1.5
1
0.5
0
−0.5
−1
−1.5
−2
−2.5
0
See Also
5
15
20
ODE solvers: ode45, ode23, ode113, ode15s, ode23s, ode23t, ode23tb
DDE solver: dde23
BVP solver: bvp4c
2-516
10
diag
Purpose
2diag
Diagonal matrices and diagonals of a matrix
Syntax
X
X
v
v
Description
X = diag(v,k) when v is a vector of n components, returns a square matrix X
of order n+abs(k), with the elements of v on the kth diagonal. k = 0 represents
the main diagonal, k > 0 above the main diagonal, and k < 0 below the main
=
=
=
=
diag(v,k)
diag(v)
diag(X,k)
diag(X)
diagonal.
k=0
k>0
k<0
X = diag(v) puts v on the main diagonal, same as above with k = 0.
v = diag(X,k) for matrix X, returns a column vector v formed from the
elements of the kth diagonal of X.
v = diag(X) returns the main diagonal of X, same as above with k = 0.
Examples
diag(diag(X)) is a diagonal matrix.
sum(diag(X)) is the trace of X.
The statement
diag(-m:m)+diag(ones(2*m,1),1)+diag(ones(2*m,1),-1)
produces a tridiagonal matrix of order 2*m+1.
2-517
diag
See Also
2-518
spdiags, tril, triu
dialog
Purpose
2dialog
Create and display dialog box
Syntax
h = dialog('PropertyName',PropertyValue,...)
Description
h = dialog('PropertyName',PropertyValue,...) returns a handle to a
dialog box. This function creates a figure graphics object and sets the figure
properties recommended for dialog boxes. You can specify any valid figure
property value.
See Also
errordlg, figure, helpdlg, inputdlg, pagedlg, printdlg, questdlg, uiwait,
uiresume, warndlg
“Predefined Dialog Boxes” for related functions
2-519
diary
Purpose
2diary
Save session to a file
Syntax
diary
diary('filename')
diary off
diary on
diary filename
Description
The diary function creates a log of keyboard input and the resulting output
(except it does not include graphics). The output of diary is an ASCII file,
suitable for printing or for inclusion in reports and other documents. If you do
not specify filename, MATLAB creates a file named diary in the current
directory.
diary toggles diary mode on and off. To see the status of diary, type
get(0,'Diary'). MATLAB returns either on or off indicating the diary
status.
diary('filename') writes a copy of all subsequent keyboard input and the
resulting output (except it does not include graphics) to the named file, where
filename is the full pathname or filename is in the current MATLAB
directory. If the file already exists, output is appended to the end of the file. You
cannot use a filename called off or on. To see the name of the diary file, use
get(0,'DiaryFile').
diary off suspends the diary.
diary on resumes diary mode using the current filename, or the default
filename diary if none has yet been specified.
diary filename is the unquoted form of the syntax.
See Also
2-520
Command History window in MATLAB Development Environment
documentation
diff
Purpose
2diff
Differences and approximate derivatives
Syntax
Y = diff(X)
Y = diff(X,n)
Y = diff(X,n,dim)
Description
Y = diff(X) calculates differences between adjacent elements of X.
If X is a vector, then diff(X) returns a vector, one element shorter than X, of
differences between adjacent elements:
[X(2)-X(1) X(3)-X(2) ... X(n)-X(n-1)]
If X is a matrix, then diff(X) returns a matrix of row differences:
[X(2:m,:)-X(1:m-1,:)]
In general, diff(X) returns the differences calculated along the first
non-singleton (size(X,dim) > 1) dimension of X.
Y = diff(X,n) applies diff recursively n times, resulting in the nth
difference. Thus, diff(X,2) is the same as diff(diff(X)).
Y = diff(X,n,dim) is the nth difference function calculated along the
dimension specified by scalar dim. If order n equals or exceeds the length of
dimension dim, diff returns an empty array.
Remarks
Since each iteration of diff reduces the length of X along dimension dim, it is
possible to specify an order n sufficiently high to reduce dim to a singleton
(size(X,dim) = 1) dimension. When this happens, diff continues calculating
along the next nonsingleton dimension.
Examples
The quantity diff(y)./diff(x) is an approximate derivative.
x = [1 2 3 4 5];
y = diff(x)
y =
1
1
1
1
z = diff(x,2)
z =
2-521
diff
0
0
0
Given,
A = rand(1,3,2,4);
diff(A) is the first-order difference along dimension 2.
diff(A,3,4) is the third-order difference along dimension 4.
See Also
2-522
gradient, prod, sum
dir
Purpose
2dir
Graphical
Interface
As an alternative to the dir function, use the Current Directory browser.
Syntax
dir
dir name
files = dir('name')
Description
dir lists the files in the current working directory.
Display directory listing
dir name lists the specified files. The name argument can be a pathname,
filename, or can include both. You can use absolute and relative pathnames
and wildcards (*).
files = dir('directory') returns the list of files in the specified directory
(or the current directory, if dirname is not specified) to an m-by-1 structure with
the fields
Examples
name
Filename
date
Modification date
bytes
Number of bytes allocated to the file
isdir
1 if name is a directory; 0 if not
List Directory Contents
To view the contents of the matlab/audio directory, type
dir $matlabroot/toolbox/matlab/audio
Using Wildcard and File Extension
To view the MAT files in your current working directory that include the term
java, type
dir *java*.mat
MATLAB returns
java_array.mat
javafrmobj.mat
testjava.mat
2-523
dir
Using Relative Pathname
To view the M-files in the MATLAB audio directory, type
dir(fullfile(matlabroot,'toolbox/matlab/audio/*.m'))
MATLAB returns
Contents.m
audiodevinfo.m
audioplayer.m
audioplayerreg.m
audiorecorder.m
audiouniquename.m
auread.m
auwrite.m
lin2mu.m
mu2lin.m
prefspanel.m
sound.m
soundsc.m
wavplay.m
wavread.m
wavrecord.m
wavwrite.m
Returning File List to Structure
To return the list of files to the variable audio_files, type
audio_files=dir(fullfile(matlabroot,'toolbox/matlab/audio/*.m')
)
MATLAB returns the information in a structure array.
audio_files =
19x1 struct array with fields:
name
date
bytes
isdir
Index into the structure to access a particular item. For example,
audio_files(3).name
ans =
audioplayer.m
See Also
2-524
cd, copyfile, delete, fileattrib, filebrowser, ls, mkdir, movefile, rmdir,
type, what
disp
Purpose
2disp
Display text or array
Syntax
disp(X)
Description
disp(X) displays an array, without printing the array name. If X contains a
text string, the string is displayed.
Another way to display an array on the screen is to type its name, but this
prints a leading “X =,” which is not always desirable.
Note that disp does not display empty arrays.
Examples
One use of disp in an M-file is to display a matrix with column labels:
disp('
Corn
disp(rand(5,3))
Oats
Hay')
which results in
Corn
0.2113
0.0820
0.7599
0.0087
0.8096
See Also
Oats
0.8474
0.4524
0.8075
0.4832
0.6135
Hay
0.2749
0.8807
0.6538
0.4899
0.7741
format, int2str, num2str, rats, sprintf
2-525
disp (serial)
Purpose
2disp (serial)
Display serial port object summary information
Syntax
obj
disp(obj)
Arguments
obj
Description
obj or disp(obj) displays summary information for obj.
Remarks
In addition to the syntax shown above, you can display summary information
for obj by excluding the semicolon when:
A serial port object or an array of serial port objects.
• Creating a serial port object
• Configuring property values using the dot notation
Use the display summary to quickly view the communication settings,
communication state information, and information associated with read and
write operations.
Example
The following commands display summary information for the serial port
object s.
s = serial('COM1')
s.BaudRate = 300
s
2-526
disp (timer)
Purpose
2disp (timer)
Display information about timer object
Syntax
obj
disp(obj)
Description
obj or disp(obj) displays summary information for timer object, obj.
If obj is an array of timer objects, disp outputs a table of summary information
about the timer objects in the array.
In addition to the syntax shown above, you can display summary information
for obj by excluding the semicolon when:
• Creating a timer object, using the timer function
• Configuring property values using the dot notation
Example
The following commands display summary information for the timer object t.
t = timer
Timer Object: timer-1
Timer Settings
ExecutionMode:
Period:
BusyMode:
Running:
singleShot
1
drop
off
Callbacks
TimerFcn:
ErrorFcn:
StartFcn:
StopFcn:
[]
[]
[]
[]
This example shows the summary information displayed for an array of timer
objects, t_arr.
disp(t_arr)
Timer Object Array
2-527
disp (timer)
Index:
1
2
See Also
2-528
timer, get
ExecutionMode:
singleShot
singleShot
Period:
1
1
TimerFcn:
[]
[]
Name:
timer-1
timer-2
display
Purpose
2display
Overloaded method to display an object
Syntax
display(X)
Description
display(X) prints the value of a variable or expression, X. MATLAB calls
display(X) when it interprets a variable or expression, X, that is not
terminated by a semicolon. For example, sin(A) calls display, while sin(A);
does not.
If X is an instance of a MATLAB class, then MATLAB calls the display method
of that class, if such a method exists. If the class has no display method or if X
is not an instance of a MATLAB class, then the MATLAB builtin display
function is called.
Examples
A typical implementation of display calls disp to do most of the work and looks
like this.
function display(X)
if isequal(get(0,'FormatSpacing'),'compact')
disp([inputname(1) ' =']);
disp(X)
else
disp(' ')
disp([inputname(1) ' =']);
disp(' ');
disp(X)
end
The expression magic(3), with no terminating semicolon, calls this function as
display(magic(3)).
magic(3)
ans =
8
3
4
1
5
9
6
7
2
As an example of a class display method, the function below implements the
display method for objects of the MATLAB class, polynom.
2-529
display
function display(p)
% POLYNOM/DISPLAY Command window display of a polynom
disp(' ');
disp([inputname(1),' = '])
disp(' ');
disp(['
' char(p)])
disp(' ');
The statement
p = polynom([1 0 -2 -5])
creates a polynom object. Since the statement is not terminated with a
semicolon, the MATLAB interpreter calls display(p), resulting in the output
p =
x^3 - 2*x - 5
See Also
2-530
disp, ans, sprintf, special characters
divergence
Purpose
2divergence
Computes the divergence of a vector field
Syntax
div
div
div
div
Description
div = divergence(X,Y,Z,U,V,W) computes the divergence of a 3-D vector
field U, V, W. The arrays X, Y, Z define the coordinates for U, V, W and must be
monotonic and 3-D plaid (as if produced by meshgrid).
=
=
=
=
divergence(X,Y,Z,U,V,W)
divergence(U,V,W)
divergence(X,Y,U,V)
divergence(U,V)
div = divergence(U,V,W) assumes X, Y, and Z are determined by the
expression:
[X Y Z] = meshgrid(1:n,1:m,1:p)
where [m,n,p] = size(U).
div = divergence(X,Y,U,V) computes the divergence of a 2-D vector field U,
V. The arrays X, Y define the coordinates for U, V and must be monotonic and
2-D plaid (as if produced by meshgrid).
div = divergence(U,V) assumes X and Y are determined by the expression:
[X Y] = meshgrid(1:n,1:m)
where [m,n] = size(U).
Examples
This example displays the divergence of vector volume data as slice planes
using color to indicate divergence.
load wind
div = divergence(x,y,z,u,v,w);
slice(x,y,z,div,[90 134],[59],[0]);
shading interp
daspect([1 1 1])
camlight
2-531
divergence
See Also
streamtube, curl, isosurface
“Volume Visualization” for related functions
Displaying Divergence with Stream Tubes for another example
2-532
dlmread
Purpose
2dlmread
Graphical
Interface
As an alternative to dlmread, use the Import Wizard. To activate the Import
Wizard, select Import data from the File menu.
Syntax
M = dlmread(filename,delimiter)
M = dlmread(filename,delimiter,R,C)
M = dlmread(filename,delimiter,range)
Description
M = dlmread(filename,delimiter) reads numeric data from the ASCII
delimited file filename, using the specified delimiter. A comma (,) is the
default delimiter. Use '\t' to specify a tab delimiter.
Read an ASCII delimited file into a matrix
M = dlmread(filename,delimiter,R,C) reads numeric data from the ASCII
delimited file filename, using the specified delimiter. The values R and C
specify the row and column where the upper-left corner of the data lies in the
file. R and C are zero based so that R=0, C=0 specifies the first value in the file,
which is the upper left corner.
M = dlmread(filename,delimiter,range) reads the range specified by
range = [R1 C1 R2 C2] where (R1,C1) is the upper-left corner of the data to
be read and (R2,C2) is the lower-right corner. range can also be specified using
spreadsheet notation as in range = 'A1..B7'.
Remarks
dlmread fills empty delimited fields with zero. Data files having lines that end
with a non-space delimiter, such as a semi-colon, produce a result that has an
additional last column of zeros.
See Also
dlmwrite, textread, csvread, csvwrite, wk1read, wk1write
2-533
dlmwrite
Purpose
2dlmwrite
Write a matrix to an ASCII delimited file
Syntax
dlmwrite(filename,M,delimiter)
dlmwrite(filename,M,delimiter,R,C)
Description
dlmwrite(filename,M,delimiter) writes matrix M into an ASCII-format file,
using delimiter to separate matrix elements. The data is written to the upper
left-most cell of the spreadsheet filename. A comma (,) is the default delimiter.
Use '\t' to produce tab-delimited files.
dlmwrite(filename,M,delimiter,R,C) writes matrix A into an ASCII-format
file, using delimiter to separate matrix elements. The data is written to the
spreadsheet filename, starting at spreadsheet cell R and C, where R is the row
offset and C is the column offset. R and C are zero based so that R=0, C=0
specifies the first value in the file, which is the upper left corner.
Remarks
The resulting file is readable by spreadsheet programs.
See Also
dlmread, csvwrite, csvread, wk1write, wk1read
2-534
dmperm
Purpose
Syntax
Description
2dmperm
Dulmage-Mendelsohn decomposition
p = dmperm(A)
[p,q,r,s] = dmperm(A)
p = dmperm(A) if A is square and has full rank, returns a row permutation p so
that A(p,:) has nonzero diagonal elements. This permutation is also called a
perfect matching. If A is not square or not full rank, p is a vector that identifies
a matching of maximum size: for each column j of A, either p(j)=0 or
A(p(j),j) is nonzero.
[p,q,r,s] = dmperm(A), where A need not be square or full rank, finds
permutations p and q and index vectors r and s so that A(p,q) is block upper
triangular. The kth block has indices (r(k):r(k+1)-1, s(k):s(k+1)-1).
When A is square and has full rank, r = s.
If A is not square or not full rank, the first block may have more columns and
the last block may have more rows. All other blocks are square and irreducible.
dmperm permutes nonzeros to the diagonals of square blocks, but does not do
this for non-square blocks.
Remarks
If A is a reducible matrix, the linear system Ax = b can be solved by permuting
A to a block upper triangular form, with irreducible diagonal blocks, and then
performing block backsubstitution. Only the diagonal blocks of the permuted
matrix need to be factored, saving fill and arithmetic in the blocks above the
diagonal.
In graph theoretic terms, dmperm finds a maximum-size matching in the
bipartite graph of A, and the diagonal blocks of A(p,q) correspond to the strong
Hall components of that graph. The output of dmperm can also be used to find
the connected or strongly connected components of an undirected or directed
graph. For more information see Pothen and Fan [].
See Also
sprank
References
Pothen, Alex and Chin-Ju Fan, "Computing the Block Triangular Form of a
Sparse Matrix," ACM Transactions on Mathematical Software, Vol. 16, No. 4,
Dec. 1990, pp. 303-324.
2-535
doc
Purpose
2doc
Graphical
Interface
As an alternative to the doc function, use the Help browser Search tab. Set the
Search type to Function Name, type the function name, and click Go.
Syntax
doc
doc function
doc toolbox/
doc toolbox/function
Description
doc opens the Help browser, if it is not already running.
Display online documentation in MATLAB Help browser
doc function displays the reference page for the MATLAB function function
in the Help browser. If function is overloaded, doc displays the reference page
for the first function on the search path and lists the overloaded functions in
the MATLAB Command Window. If a reference page for the function does not
exist, doc displays M-file help in the Help browser.
doc toolbox/ displays the Roadmap page, a summary of the most pertinent
documentation for toolbox, in the Help browser.
doc toolbox/function displays the reference page for function that belongs
to the specified toolbox, in the Help browser.
See Also
2-536
help, helpbrowser, lookfor, type, web
docopt
Purpose
2docopt
Display location of help file directory for UNIX platforms
Syntax
docopt
[doccmd,options,docpath] = docopt
Description
docopt displays the location of the online help files directory (online
documentation location) for UNIX platforms if the web function is used with the
-browser option. It is also used for UNIX platforms that do not support Java
GUIs—see the “Release 13 Release Notes” for more information about these
platforms. You specify where the online help directory will be located when you
install MATLAB. It can be on a disk or CD-ROM drive in your local system. If
you relocate your online help file directory, edit the docopt.m file, changing the
location in it. (For Windows and the UNIX platforms that support Java GUIs,
select File -> Preferences -> Help to view or change the documentation
location.)
[doccmd,options,docpath] = docopt displays three strings: doccmd,
options, and docpath.
Remarks
doccmd
The function that doc uses to display MATLAB documentation.
The default is netscape.
options
Additional configuration options for use with doccmd.
docpath
The path to the MATLAB online help files. If docpath is empty,
the doc function assumes the help files are in the default
location.
To globally replace the online help file directory location, update
$matlabroot/toolbox/local/docopt.m.
To override the global setting, copy $matlabroot/toolbox/local/docopt.m to
$HOME/matlab/docopt.m and make changes there. For the changes to take
effect in the current MATLAB session, $HOME/matlab must be on your
MATLAB path.
See Also
doc, help, helpbrowser, helpdesk, lookfor, type
2-537
docroot
Purpose
2docroot
Graphical
Interface
As an alternative to the docroot function, select File -> Preferences -> Help
and set the Documentation location.
Syntax
docroot
docroot('newdocroot')
docroot(newdocroot, 'cdrom')
Description
docroot displays the current value for docroot, the root directory for MATLAB
Get or set root directory for MATLAB help files
help files. This is the directory where the MATLAB Help browser looks for the
online documentation to display.
docroot('newdocroot') sets the root directory for MATLAB help files to
newdocroot, where newdocroot is the full pathname to the help directory. For
example, type docroot('d:/matlabr13/help'). One useful application is
setting docroot in your startup.m file.
docroot('newdocroot', 'cdrom') sets the root directory for MATLAB help
files on the MATLAB documentation CD to newdocroot, where newdocroot is
the full pathname to the help directory on your MATLAB documentation CD.
For example, type docroot('z:/help', 'cdrom').
Examples
You can include a docroot statement in your startup.m file.
See Also
doc, helpbrowser
2-538
dos
Purpose
2dos
Execute a DOS command and return result
Syntax
dos command
status = dos('command')
[status,result] = dos('command')
[status,result] = dos('command','-echo')
Description
dos command calls upon the shell to execute the given command for Windows
systems.
status = dos('command') returns completion status to the status variable.
[status,result] = dos('command') in addition to completion status, returns
the result of the command to the result variable.
[status,result] = dos('command','-echo') forces the output to the
Command Window, even though it is also being assigned into a variable.
Both console (DOS) programs and Windows programs may be executed, but the
syntax causes different results based on the type of programs. Console
programs have stdout and their output is returned to the result variable. They
are always run in an iconified DOS or Command Prompt Window except as
noted below. Console programs never execute in the background. Also,
MATLAB will always wait for the stdout pipe to close before continuing
execution. Windows programs may be executed in the background as they have
no stdout.
The ampersand, &, character has special meaning. For console programs this
causes the console to open. Omitting this character will cause console programs
to run iconically. For Windows programs, appending this character will cause
the application to run in the background. MATLAB will continue processing.
Examples
The following example performs a directory listing, returning a zero (success)
in s and the string containing the listing in w.
[s, w] = dos('dir');
To open the DOS 5.0 editor in a DOS window
dos('edit &')
2-539
dos
To open the notepad editor and return control immediately to MATLAB
dos('notepad file.m &')
The next example returns a one in s and an error message in w because foo is
not a valid shell command.
[s, w] = dos('foo')
This example echoes the results of the dir command to the Command Window
as it executes as well as assigning the results to w.
[s, w] = dos('dir', '-echo');
See Also
2-540
! (exclamation point), perl, system, unix
dot
Purpose
2dot
Vector dot product
Syntax
C = dot(A,B)
C = dot(A,B,dim)
Description
C = dot(A,B) returns the scalar product of the vectors A and B. A and B must
be vectors of the same length. When A and B are both column vectors, dot(A,B)
is the same as A'*B.
For multidimensional arrays A and B, dot returns the scalar product along the
first non-singleton dimension of A and B. A and B must have the same size.
C = dot(A,B,dim) returns the scalar product of A and B in the dimension dim.
Examples
The dot product of two vectors is calculated as shown:
a = [1 2 3]; b = [4 5 6];
c = dot(a,b)
c =
32
See Also
cross
2-541
double
Purpose
2double
Convert to double-precision
Syntax
double(X)
Description
double(x) returns the double-precision value for X. If X is already a
double-precision array, double has no effect.
Remarks
2-542
double is called for the expressions in for, if, and while loops if the expression
isn't already double-precision. double should be overloaded for any object when
it makes sense to convert it to a double-precision value.
dragrect
Purpose
2dragrect
Drag rectangles with mouse
Syntax
[finalrect] = dragrect(initialrect)
[finalrect] = dragrect(initialrect,stepsize)
Description
[finalrect] = dragrect(initialrect) tracks one or more rectangles
anywhere on the screen. The n-by-4 matrix, initialrect, defines the
rectangles. Each row of initialrect must contain the initial rectangle
position as [left bottom width height] values. dragrect returns the final
position of the rectangles in finalrect.
[finalrect] = dragrect(initialrect,stepsize) moves the rectangles in
increments of stepsize. The lower-left corner of the first rectangle is
constrained to a grid of size equal to stepsize starting at the lower-left corner
of the figure, and all other rectangles maintain their original offset from the
first rectangle.
[finalrect] = dragrect(...) returns the final positions of the rectangles
when the mouse button is released. The default stepsize is 1.
Remarks
dragrect returns immediately if a mouse button is not currently pressed. Use
dragrect in a ButtonDownFcn, or from the command line in conjunction with
waitforbuttonpress to ensure that the mouse button is down when dragrect
is called. dragrect returns when you release the mouse button.
If the drag ends over a figure window, the positions of the rectangles are
returned in that figure's coordinate system. If the drag ends over a part of the
screen not contained within a figure window, the rectangles are returned in the
coordinate system of the figure over which the drag began
Example
Drag a rectangle that is 50 pixels wide and 100 pixels in height.
waitforbuttonpress
point1 = get(gcf,'CurrentPoint') % button down detected
rect = [point1(1,1) point1(1,2) 50 100]
[r2] = dragrect(rect)
See Also
rbbox, waitforbuttonpress
“Selecting Region of Interest” for related functions
2-543
drawnow
Purpose
2drawnow
Complete pending drawing events
Syntax
drawnow
Description
drawnow flushes the event queue and updates the figure window.
Remarks
Other events that cause MATLAB to flush the event queue and draw the figure
windows include:
• Returning to the MATLAB prompt
• A pause statement
• A waitforbuttonpress statement
• A waitfor statement
• A getframe statement
• A figure statement
Examples
Executing the statements,
x = -pi:pi/20:pi;
plot(x,cos(x))
drawnow
title('A Short Title')
grid on
as an M-file updates the current figure after executing the drawnow function
and after executing the final statement.
See Also
waitfor, pause, waitforbuttonpress
“Figure Windows” for related functions
2-544
dsearch
Purpose
2dsearch
Search for nearest point
Syntax
K = dsearch(x,y,TRI,xi,yi)
K = dsearch(x,y,TRI,xi,yi,S)
Description
K = dsearch(x,y,TRI,xi,yi) returns the index into x and y of the nearest
point to the point (xi,yi). dsearch requires a triangulation TRI of the points x,y
obtained using delaunay. If xi and yi are vectors, K is a vector of the same size.
K = dsearch(x,y,TRI,xi,yi,S) uses the sparse matrix S instead of
computing it each time:
S = sparse(TRI(:,[1 1 2 2 3 3]),TRI(:,[2 3 1 3 1 2]),1,nxy,nxy)
where nxy = prod(size(x)).
See Also
delaunay, tsearch, voronoi
2-545
dsearchn
Purpose
2dsearchn
n-D nearest point search
Syntax
k = dsearchn(X,T,XI)
k = dsearchn(X,T,XI,outval)
k = dsearchn(X,XI)
[k,d] = dsearchn(X,...)
Description
k = dsearchn(X,T,XI) returns the indices k of the closest points in X for each
point in XI. X is an m-by-n matrix representing m points in n-D space. XI is a
p-by-n matrix, representing p points in n-D space. T is a numt-by-n+1 matrix, a
tessellation of the data X generated by delaunayn. The output k is a column
vector of length p.
k = dsearchn(X,T,XI,outval) returns the indices k of the closest points in X
for each point in XI, unless a point is outside the convex hull. If XI(J,:) is
outside the convex hull, then K(J) is assigned outval, a scalar double. Inf is
often used for outval. If outval is [], then k is the same as in the case
k = dsearchn(X,T,XI).
k = dsearchn(X,XI) performs the search without using a tessellation. With
large X and small XI, this approach is faster and uses much less memory.
[k,d] = dsearchn(X,...) also returns the distances d to the closest points. d
is a column vector of length p.
See Also
2-546
tsearch, dsearch, tsearchn, griddatan, delaunayn
echo
Purpose
Syntax
Description
2echo
Echo M-files during execution
echo
echo
echo
echo
echo
echo
echo
echo
on
off
fcnname on
fcnname off
fcnname
on all
off all
The echo command controls the echoing of M-files during execution. Normally,
the commands in M-files do not display on the screen during execution.
Command echoing is useful for debugging or for demonstrations, allowing the
commands to be viewed as they execute.
The echo command behaves in a slightly different manner for script files and
function files. For script files, the use of echo is simple; echoing can be either
on or off, in which case any script used is affected.
echo on
Turns on the echoing of commands in all script files.
echo off
Turns off the echoing of commands in all script files.
echo
Toggles the echo state.
With function files, the use of echo is more complicated. If echo is enabled on a
function file, the file is interpreted, rather than compiled. Each input line is
then displayed as it is executed. Since this results in inefficient execution, use
echo only for debugging.
See Also
echo fcnname on
Turns on echoing of the named function file.
echo fcnname off
Turns off echoing of the named function file.
echo fcnname
Toggles the echo state of the named function file.
echo on all
Set echoing on for all function files.
echo off all
Set echoing off for all function files.
function
2-547
edit
Purpose
2edit
Graphical
Interface
As an alternative to the edit function, select New or Open from the File menu
in the MATLAB desktop or any desktop tool.
Syntax
edit
edit
edit
edit
edit
edit
edit
Description
Edit or create M-file
fun.m
file.ext
fun1 fun2 fun3 ...
class/fun
private/fun
class/private/fun
edit opens a new editor window.
edit fun.m opens the M-file fun.m in the default editor. Note that fun.m can
be a MATLAB partialpath or a complete path. If fun.m does not exist, a
prompt appears asking if you want to create a new file titled fun.m. After you
click Yes, the Editor/Debugger creates a blank file titled fun.m. If you do not
want the prompt to appear in this situation, select that check box in the
prompt. Then when you type edit fun.m, where fun.m did not previously exist,
a new file called fun.m is automatically opened in the Editor. To make the
prompt appear, specify it in preferences for “Prompt” on page 7-38.
edit file.ext opens the specified file.
edit fun1 fun2 fun3 ... opens fun1.m, fun2.m, fun3.m, and so on, in the
default editor.
edit class/fun, edit private/fun, or edit class/private/fun can be
used to edit a method, private function, or private method (for the class named
class).
Remarks
2-548
To specify the default editor for MATLAB, select Preferences from the File
menu. On the Editor/Debugger panel, select the MATLAB Editor/Debugger or
specify another.
edit
UNIX Users
If you run MATLAB with the -nodisplay startup option, or run without the
DISPLAY environment variable set, edit uses the External Editor command.
It does not use the MATLAB Editor/Debugger, but instead uses the default
editor defined for your system in $matlabroot/X11/app-defaults/Matlab.
You can specify the editor that the edit function uses or specify editor options
by adding the following line to your own .Xdefaults file, located in ~home
matlab*externalEditorCommand: $EDITOR -option $FILE
where
• $EDITOR is the name of your default editor, for example, emacs; leaving it as
$EDITOR means your default system editor will be used.
• -option is a valid option flag you can include for the specified editor.
• $FILE means the filename you type with the edit command will open in the
specified editor.
For example,
emacs $FILE
means that when you type edit foo, the file foo will open in the emacs editor.
After adding the line to your .Xdefaults file, you must run the following before
starting MATLAB:
xrdb -merge ~home/.Xdefaults
For the HP 700 platform, the default editor is instead defined in
$matlabroot/toolbox/matlab/general/edit.m. To change it, open the file
edit.m and edit the line
eval( ['!$EDITOR “' file '" &']);
See Also
open, type
2-549
eig
Purpose
2eig
Find eigenvalues and eigenvectors
Syntax
d = eig(A)
d = eig(A,B)
[V,D] = eig(A)
[V,D] = eig(A,'nobalance')
[V,D] = eig(A,B)
[V,D] = eig(A,B,flag)
Description
d = eig(A) returns a vector of the eigenvalues of matrix A.
d = eig(A,B) returns a vector containing the generalized eigenvalues, if A and
B are square matrices.
Note If S is sparse and symmetric, you can use d = eig(S) to returns the
eigenvalues of S. To request eigenvectors, and in all other cases, use eigs to
find the eigenvalues or eigenvectors of sparse matrices.
[V,D] = eig(A) produces matrices of eigenvalues (D) and eigenvectors (V) of
matrix A, so that A*V = V*D. Matrix D is the canonical form of A—a diagonal
matrix with A’s eigenvalues on the main diagonal. Matrix V is the modal
matrix—its columns are the eigenvectors of A.
If W is a matrix such that W'*A = D*W', the columns of W are the left eigenvectors
of A . Use [W,D] = eig(A.'); W = conj(W) to compute the left eigenvectors.
[V,D] = eig(A,'nobalance') finds eigenvalues and eigenvectors without a
preliminary balancing step. Ordinarily, balancing improves the conditioning of
the input matrix, enabling more accurate computation of the eigenvectors and
eigenvalues. However, if a matrix contains small elements that are really due
to roundoff error, balancing may scale them up to make them as significant as
the other elements of the original matrix, leading to incorrect eigenvectors. Use
the nobalance option in this event. See the balance function for more details.
[V,D] = eig(A,B) produces a diagonal matrix D of generalized eigenvalues
and a full matrix V whose columns are the corresponding eigenvectors so that
A*V = B*V*D.
2-550
eig
[V,D] = eig(A,B,flag) specifies the algorithm used to compute eigenvalues
and eigenvectors. flag can be:
'chol'
Computes the generalized eigenvalues of A and B using the
Cholesky factorization of B. This is the default for symmetric
(Hermitian) A and symmetric (Hermitian) positive definite B.
'qz'
Ignores the symmetry, if any, and uses the QZ algorithm as it
would for nonsymmetric (non-Hermitian) A and B.
Note For eig(A), the eigenvectors are scaled so that the norm of each is 1.0.
For eig(A,B), eig(A,'nobalance'), and eig(A,B,flag), the eigenvectors are
not normalized.
Remarks
The eigenvalue problem is to determine the nontrivial solutions of the equation
Ax = λx
where A is an n-by-n matrix, x is a length n column vector, and λ is a scalar.
The n values of λ that satisfy the equation are the eigenvalues, and the
corresponding values of x are the right eigenvectors. In MATLAB, the function
eig solves for the eigenvalues λ , and optionally the eigenvectors x .
The generalized eigenvalue problem is to determine the nontrivial solutions of
the equation
Ax = λBx
where both A and B are n-by-n matrices and λ is a scalar. The values of λ that
satisfy the equation are the generalized eigenvalues and the corresponding
values of x are the generalized right eigenvectors.
If B is nonsingular, the problem could be solved by reducing it to a standard
eigenvalue problem
B – 1 Ax = λx
Because B can be singular, an alternative algorithm, called the QZ method, is
necessary.
2-551
eig
When a matrix has no repeated eigenvalues, the eigenvectors are always
independent and the eigenvector matrix V diagonalizes the original matrix A if
applied as a similarity transformation. However, if a matrix has repeated
eigenvalues, it is not similar to a diagonal matrix unless it has a full
(independent) set of eigenvectors. If the eigenvectors are not independent then
the original matrix is said to be defective. Even if a matrix is defective, the
solution from eig satisfies A*X = X*D.
Examples
The matrix
B = [ 3
-2
-2
4
-eps/4 eps/2
-.5
-.5
-.9
1
-1
.1
2*eps
-eps
0
1
];
has elements on the order of roundoff error. It is an example for which the
nobalance option is necessary to compute the eigenvectors correctly. Try the
statements
[VB,DB] = eig(B)
B*VB - VB*DB
[VN,DN] = eig(B,'nobalance')
B*VN - VN*DN
Algorithm
MATLAB uses LAPACK routines to compute eigenvalues and eigenvectors:
Case
Routine
Real symmetric A
DSYEV
Real nonsymmetric A:
2-552
• With preliminary balance step
DGEEV (with SCLFAC = 2 instead
of 8 in DGEBAL)
• d = eig(A,'nobalance')
DGEHRD, DHSEQR
• [V,D] = eig(A,'nobalance')
DGEHRD, DORGHR, DHSEQR, DTREVC
Hermitian A
ZHEEV
eig
Case
Routine
Non-Hermitian A:
• With preliminary balance step
ZGEEV (with SCLFAC = 2 instead
of 8 in ZGEBAL)
• d = eig(A,'nobalance')
ZGEHRD, ZHSEQR
• [V,D] = eig(A,'nobalance')
ZGEHRD, ZUNGHR, ZHSEQR, ZTREVC
Real symmetric A,
symmetric positive definite B.
Special case:
eig(A,B,'qz') for real A, B
(same as real nonsymmetric A, real
general B)
DSYGV
Real nonsymmetric A, real general B
DGGEV
Complex Hermitian A,
Hermitian positive definite B.
Special case:
eig(A,B,'qz') for complex A or B
(same as complex non-Hermitian A,
complex B)
ZHEGV
Complex non-Hermitian A, complex B
ZGGEV
DGGEV
ZGGEV
See Also
balance, condeig, eigs, hess, qz, schur
References
[1] Anderson, E., Z. Bai, C. Bischof, S. Blackford, J. Demmel, J. Dongarra,
J. Du Croz, A. Greenbaum, S. Hammarling, A. McKenney, and D. Sorensen,
LAPACK User’s Guide
(http://www.netlib.org/lapack/lug/lapack_lug.html), Third Edition,
SIAM, Philadelphia, 1999.
2-553
eigs
Purpose
2eigs
Find a few eigenvalues and eigenvectors of a square large sparse matrix
Syntax
d = eigs(A)
d = eigs(A,B)
d = eigs(A,k)
d = eigs(A,B,k)
d = eigs(A,k,sigma)
d = eigs(A,B,k,sigma)
d = eigs(A,k,sigma,options)
d = eigs(A,B,k,sigma,options)
d = eigs(Afun,n)
d = eigs(Afun,n,B)
d = eigs(Afun,n,k)
d = eigs(Afun,n,B,k)
d = eigs(Afun,n,k,sigma)
d = eigs(Afun,n,B,k,sigma)
d = eigs(Afun,n,k,sigma,options)
d = eigs(Afun,n,B,k,sigma,options)
d = eigs(Afun,n,k,sigma,options,p1,p2...)
d = eigs(Afun,n,B,k,sigma,options,p1,p2...)
[V,D] = eigs(A,...)
[V,D] = eigs(Afun,n,...)
[V,D,flag] = eigs(A,...)
[V,D,flag] = eigs(Afun,n,...)
Description
d = eigs(A) returns a vector of A's six largest magnitude eigenvalues.
[V,D] = eigs(A) returns a diagonal matrix D of A's six largest magnitude
eigenvalues and a matrix V whose columns are the corresponding eigenvectors.
[V,D,flag] = eigs(A) also returns a convergence flag. If flag is 0 then all
the eigenvalues converged; otherwise not all converged.
eigs(A,B) solves the generalized eigenvalue problem A*V == B*V*D. B must
be symmetric (or Hermitian) positive definite and the same size as A.
eigs(A,[],...) indicates the standard eigenvalue problem A*V == V*D.
eigs(A,k) and eigs(A,B,k) return the k largest magnitude eigenvalues.
2-554
eigs
eigs(A,k,sigma) and eigs(A,B,k,sigma) return k eigenvalues based on
sigma, which can take any of the following values:
scalar
The eigenvalues closest to sigma. If A is a function, Afun
(real or complex, must return Y = (A-sigma*B)\x (i.e., Y = A\x when
including 0)
sigma = 0). Note, B need only be symmetric (Hermitian)
positive semi-definite.
'lm'
Largest magnitude (default).
'sm'
Smallest magnitude. Same as sigma = 0. If A is a function,
Afun must return Y = A\x. Note, B need only be symmetric
(Hermitian) positive semi-definite.
For real symmetric problems, the following are also options:
'la'
Largest algebraic ('lr' in MATLAB 5)
'sa'
Smallest algebraic ('sr' in MATLAB 5)
'be'
Both ends (one more from high end if k is odd)
For nonsymmetric and complex problems, the following are also options:
'lr'
Largest real part
'sr'
Smallest real part
'li'
Largest imaginary part
'si'
Smallest imaginary part
Note The MATLAB 5 value sigma = 'be' is obsolete for nonsymmetric and
complex problems.
2-555
eigs
eigs(A,K,sigma,opts) and eigs(A,B,k,sigma,opts) specify an options
structure. Default values are shown in brackets ({}).
Parameter
Description
Values
options.issym
1 if A or A-sigma*B represented
by Afun is symmetric, 0
[{0} | 1]
otherwise.
options.isreal
1 if A or A-sigma*B represented
by Afun is real, 0 otherwise.
[0 | {1}]
options.tol
Convergence: Ritz estimate
residual <= tol*norm(A).
[scalar | {eps}]
options.maxit
Maximum number of iterations.
[integer | {300}]
options.p
Number of basis vectors. p >= 2k
(p >= 2k+1 real nonsymmetric)
advised. Note: p must satisfy
k < p <= n for real symmetric,
k+1 < p <= n otherwise.
[integer | 2*k]
options.v0
Starting vector.
Randomly
generated by
ARPACK
options.disp
Diagnostic information display
level.
[0 | {1} | 2]
options.cholB
1 if B is really its Cholesky factor
chol(B), 0 otherwise.
[{0} | 1]
options.permB
Permutation vector permB if
sparse B is really
chol(B(permB,permB)).
[permB | {1:n}]
Note MATLAB 5 options stagtol and cheb are no longer allowed.
2-556
eigs
eigs(Afun,n,...) accepts the function Afun instead of the matrix A.
y = Afun(x) should return:
A*x
if sigma is not specified, or is a string other than 'sm'
A\x
if sigma is 0 or 'sm'
(A-sigma*I)\x
if sigma is a nonzero scalar (standard eigenvalue
problem). I is an identity matrix of the same size as A.
(A-sigma*B)\x
if sigma is a nonzero scalar (generalized eigenvalue
problem)
n is the size of A. The matrix A, A-sigma*I or A-sigma*B represented by Afun is
assumed to be real and nonsymmetric unless specified otherwise by
opts.isreal and opts.issym. In all the eigs syntaxes, eigs(A,...) can be
replaced by eigs(Afun,n,...).
eigs(Afun,n,k,sigma,opts,p1,p2,...) and
eigs(Afun,n,B,k,sigma,opts,p1,p2,...) provide for additional arguments
which are passed to Afun(x,p1,p2,...).
Remarks
d = eigs(A,k) is not a substitute for
d = eig(full(A))
d = sort(d)
d = d(end-k+1:end)
but is most appropriate for large sparse matrices. If the problem fits into
memory, it may be quicker to use eig(full(A)).
Algorithm
eigs provides the reverse communication required by the Fortran library
ARPACK, namely the routines DSAUPD, DSEUPD, DNAUPD, DNEUPD, ZNAUPD, and
ZNEUPD.
Examples
Example 1: This example shows the use of function handles.
A = delsq(numgrid('C',15));
d1 = eigs(A,5,'sm');
Equivalently, if dnRk is the following one-line function:
function y = dnRk(x,R,k)
2-557
eigs
y = (delsq(numgrid(R,k))) \ x;
then pass dnRk's additional arguments, 'C' and 15, to eigs.
n = size(A,1);
opts.issym = 1;
d2 = eigs(@dnRk,n,5,'sm',opts,'C',15);
Example 2: west0479 is a real 479-by-479 sparse matrix with both real and
pairs of complex conjugate eigenvalues. eig computes all 479 eigenvalues. eigs
easily picks out the largest magnitude eigenvalues.
This plot shows the 8 largest magnitude eigenvalues of west0479 as computed
by eig and eigs.
load west0479
d = eig(full(west0479))
dlm = eigs(west0479,8)
[dum,ind] = sort(abs(d));
plot(dlm,'k+')
hold on
plot(d(ind(end-7:end)),'ks')
hold off
legend('eigs(west0479,8)','eig(full(west0479))')
2-558
eigs
2000
eigs(west0479,8)
eig(full(west0479))
1500
1000
500
0
−500
−1000
−1500
−2000
−150
−100
−50
0
50
100
150
Example 3: A = delsq(numgrid('C',30)) is a symmetric positive definite
matrix of size 632 with eigenvalues reasonably well-distributed in the interval
(0 8), but with 18 eigenvalues repeated at 4. The eig function computes all 632
eigenvalues. It computes and plots the six largest and smallest magnitude
eigenvalues of A successfully with:
A = delsq(numgrid('C',30));
d = eig(full(A));
[dum,ind] = sort(abs(d));
dlm = eigs(A);
dsm = eigs(A,6,'sm');
subplot(2,1,1)
plot(dlm,'k+')
hold on
plot(d(ind(end:-1:end-5)),'ks')
hold off
legend('eigs(A)','eig(full(A))',3)
set(gca,'XLim',[0.5 6.5])
2-559
eigs
subplot(2,1,2)
plot(dsm,'k+')
hold on
plot(d(ind(1:6)),'ks')
hold off
legend('eigs(A,6,''sm'')','eig(full(A))',2)
set(gca,'XLim',[0.5 6.5])
8
7.95
7.9
7.85
eigs(A)
eig(full(A))
7.8
1
2
3
4
5
6
2
3
4
5
6
0.2
eigs(A,6,’SM’)
eig(full(A))
0.15
0.1
0.05
0
1
However, the repeated eigenvalue at 4 must be handled more carefully. The
call eigs(A,18,4.0) to compute 18 eigenvalues near 4.0 tries to find
eigenvalues of A - 4.0*I. This involves divisions of the form
1/(lambda - 4.0), where lambda is an estimate of an eigenvalue of A. As
lambda gets closer to 4.0, eigs fails. We must use sigma near but not equal to
4 to find those 18 eigenvalues.
sigma = 4 - 1e-6
[V,D] = eigs(A,18,sigma)
2-560
eigs
The plot shows the 20 eigenvalues closest to 4 that were computed by eig,
along with the 18 eigenvalues closest to 4 - 1e-6 that were computed by eigs.
18 repeated eigenvalues of delsq(numgrid(’C’,30)) at 4
4.03
eigs(A,18,sigma)
eig(A)
4.02
4.01
4
3.99
3.98
3.97
2
4
6
8
10
12
14
16
18
20
See Also
arpackc, eig, svds
References
[1] Lehoucq, R.B. and D.C. Sorensen, “Deflation Techniques for an Implicitly
Re-Started Arnoldi Iteration,” SIAM J. Matrix Analysis and Applications, Vol.
17, 1996, pp. 789-821.
[2] Lehoucq, R.B., D.C. Sorensen, and C. Yang, ARPACK Users' Guide:
Solution of Large-Scale Eigenvalue Problems with Implicitly Restarted Arnoldi
Methods, SIAM Publications, Philadelphia, 1998.
[3] Sorensen, D.C., “Implicit Application of Polynomial Filters in a k-Step
Arnoldi Method,” SIAM J. Matrix Analysis and Applications, Vol. 13, 1992,
pp. 357-385.
2-561
ellipj
Purpose
2ellipj
Jacobi elliptic functions
Syntax
[SN,CN,DN]
[SN,CN,DN]
Definition
The Jacobi elliptic functions are defined in terms of the integral:
u =
φ
=
=
ellipj(U,M)
ellipj(U,M,tol)
dθ
∫0 -----------------------------------2
1
---
( 1 – m sin θ ) 2
Then
1
---
sn ( u ) = sin φ, cn ( u ) = cos φ, dn ( u ) = ( 1 – m sin2 φ ) 2, am ( u ) = φ
Some definitions of the elliptic functions use the modulus k instead of the
parameter m . They are related by
k 2 = m = sin2 α
The Jacobi elliptic functions obey many mathematical identities; for a good
sample, see [1].
Description
[SN,CN,DN] = ellipj(U,M) returns the Jacobi elliptic functions SN, CN, and
DN, evaluated for corresponding elements of argument U and parameter M.
Inputs U and M must be the same size (or either can be scalar).
[SN,CN,DN] = ellipj(U,M,tol) computes the Jacobi elliptic functions to
accuracy tol. The default is eps; increase this for a less accurate but more
quickly computed answer.
Algorithm
ellipj computes the Jacobi elliptic functions using the method of the
arithmetic-geometric mean [1]. It starts with the triplet of numbers:
1
--2
a 0 = 1, b 0 = ( 1 – m ) , c 0 = ( m )
2-562
1
--2
ellipj
ellipj computes successive iterates with
1
a i = --- ( a i – 1 + b i – 1 )
2
1
--bi = ( ai – 1 bi – 1 ) 2
1
c i = --- ( a i – 1 – b i – 1 )
2
Next, it calculates the amplitudes in radians using:
cn
sin ( 2φ n – 1 – φ n ) = ------ sin ( φ n )
an
being careful to unwrap the phases correctly. The Jacobian elliptic functions
are then simply:
sn ( u ) = sin φ 0
cn ( u ) = cos φ 0
2
1
---
dn ( u ) = ( 1 – m ⋅ sn ( u ) ) 2
Limitations
The ellipj function is limited to the input domain 0 ≤ m ≤ 1 . Map other values
of M into this range using the transformations described in [1], equations 16.10
and 16.11. U is limited to real values.
See Also
ellipke
References
[1] Abramowitz, M. and I.A. Stegun, Handbook of Mathematical Functions,
Dover Publications, 1965, 17.6.
2-563
ellipke
Purpose
2ellipke
Syntax
K = ellipke(M)
[K,E] = ellipke(M)
[K,E] = ellipke(M,tol)
Definition
The complete elliptic integral of the first kind [1] is
Complete elliptic integrals of the first and second kind
K (m) = F(π ⁄ 2 m)
where F , the elliptic integral of the first kind, is
K (m) =
1
∫0
–1
------
[ ( 1 – t 2 ) ( 1 – mt 2 ) ] 2 dt =
π
--2
∫0
–1
------
( 1 – m sin2 θ ) 2 dθ
The complete elliptic integral of the second kind
E ( m ) = E ( K ( m ) ) = E 〈π ⁄ 2|m〉
is
E(m) =
1
∫0
–1
------
1
---
( 1 – t 2 ) 2 ( 1 – mt 2 ) 2 dt =
π
--2
1
--2
∫0 ( 1 – m sin2 θ ) dθ
Some definitions of K and E use the modulus k instead of the parameter m .
They are related by
k 2 = m = sin2 α
Description
K = ellipke(M) returns the complete elliptic integral of the first kind for the
elements of M.
[K,E] = ellipke(M) returns the complete elliptic integral of the first and
second kinds.
[K,E] = ellipke(M,tol) computes the Jacobian elliptic functions to accuracy
tol. The default is eps; increase this for a less accurate but more quickly
computed answer.
2-564
ellipke
Algorithm
ellipke computes the complete elliptic integral using the method of the
arithmetic-geometric mean described in [1], section 17.6. It starts with the
triplet of numbers
1
---
1
---
a 0 = 1, b 0 = ( 1 – m ) 2, c 0 = ( m ) 2
ellipke computes successive iterations of a i , b i , and c i with
1
a i = --- ( a i – 1 + b i – 1 )
2
1
--bi = ( ai – 1 bi – 1 ) 2
1
c i = --- ( a i – 1 – b i – 1 )
2
stopping at iteration n when cn ≈ 0 , within the tolerance specified by eps. The
complete elliptic integral of the first kind is then
π
K ( m ) = ---------2a n
Limitations
ellipke is limited to the input domain 0 ≤ m ≤ 1 .
See Also
ellipj
References
[1] Abramowitz, M. and I.A. Stegun, Handbook of Mathematical Functions,
Dover Publications, 1965, 17.6.
2-565
ellipsoid
Purpose
2ellipsoid
Generate ellipsoid
Syntax
[x,y,z] = ellipsoid(xc,yc,zc,xr,yr,zr,n)
[x,y,z] = ellipsoid(xc,yc,zc,xr,yr,zr)
ellipsoid(...)
Description
[x,y,z] = ellipsoid(xc,yc,zc,xr,yr,zr,n) generates three n+1-by-n+1
matrices so that surf(x,y,z) produces an ellipsoid with center (xc,yc,zc)
and radii (xr,yr,zr).
[x,y,z] = ellipsoid(xc,yc,zc,xr,yr,zr) uses n = 20.
ellipsoid(...) with no output arguments graphs the ellipsoid as a surface.
Algorithm
ellipsoid generates the data using the following equation:
2
2
2
( x – xc )
( y – yc )
( z – zc )
----------------------- + ----------------------- + ---------------------2
2
2
xr
yr
zr
See Also
cylinder, sphere, surf
“Polygons and Surfaces” for related functions
2-566
else
Purpose
2else
Conditionally execute statements
Syntax
if expression
statements1
else
statements2
end
Description
else is used to delineate an alternate block of statements. If expression
evaluates as false, MATLAB executes the one or more commands denoted
here as statements2.
A true expression has either a logical true or nonzero value. For nonscalar
expressions, (for example, “if (matrix A is less than matrix B)”), true means
that every element of the resulting matrix has a logical true or nonzero value.
Expressions usually involve relational operations such as (count < limit) or
isreal(A). Simple expressions can be combined by logical operators (&,|,~) into
compound expressions such as: (count < limit) & ((height - offset) >=
0).
See if for more information.
Examples
In this example, if both of the conditions are not satisfied, then the student fails
the course.
if ((attendance >= 0.90) & (grade_average >= 60))
pass = 1;
else
fail = 1;
end;
See Also
if, elseif, end, for, while, switch, break, return, relational_operators,
logical_operators
2-567
elseif
Purpose
2elseif
Conditionally execute statements
Syntax
if expression1
statements1
elseif expression2
statements2
end
Description
If expression1 evaluates as false and expression2 as true, MATLAB
executes the one or more commands denoted here as statements2.
A true expression has either a logical true or nonzero value. For nonscalar
expressions, (for example, is matrix A less then matrix B), true means that
every element of the resulting matrix has a logical true or nonzero value.
Expressions usually involve relational operations such as (count < limit) or
isreal(A). Simple expressions can be combined by logical operators (&,|,~) into
compound expressions such as: (count < limit) & ((height - offset) >=
0).
See if for more information.
Remarks
else if, with a space between the else and the if, differs from elseif, with
no space. The former introduces a new, nested if, which must have a matching
end. The latter is used in a linear sequence of conditional statements with only
one terminating end.
The two segments shown below produce identical results. Exactly one of the
four assignments to x is executed, depending upon the values of the three
logical expressions, A, B, and C.
if A
x = a
else
if B
x = b
else
if C
x = c
else
x = d
2-568
if A
x = a
elseif B
x = b
elseif C
x = c
else
x = d
end
elseif
end
end
end
Examples
Here is an example showing if, else, and elseif.
for m = 1:k
for n = 1:k
if m == n
a(m,n) = 2;
elseif abs(m-n) == 2
a(m,n) = 1;
else
a(m,n) = 0;
end
end
end
For k=5 you get the matrix
a =
2
0
1
0
0
See Also
0
2
0
1
0
1
0
2
0
1
0
1
0
2
0
0
0
1
0
2
if, else, end, for, while, switch, break, return, relational_operators,
logical_operators
2-569
end
Purpose
Syntax
2end
Terminate for, while, switch, try, and if statements or indicate last index
while expression% (or if, for, or try)
statements
end
B = A(index:end,index)
Description
end is used to terminate for, while, switch, try, and if statements. Without
an end statement, for, while, switch, try, and if wait for further input. Each
end is paired with the closest previous unpaired for, while, switch, try, or if
and serves to delimit its scope.
The end command also serves as the last index in an indexing expression. In
that context, end = (size(x,k)) when used as part of the kth index. Examples
of this use are X(3:end) and X(1,1:2:end-1). When using end to grow an
array, as in X(end+1)=5, make sure X exists first.
You can overload the end statement for a user object by defining an end method
for the object. The end method should have the calling sequence end(obj,k,n),
where obj is the user object, k is the index in the expression where the end
syntax is used, and n is the total number of indices in the expression. For
example, consider the expression
A(end-1,:)
MATLAB will call the end method defined for A using the syntax
end(A,1,2)
Examples
This example shows end used with the for and if statements.
for k = 1:n
if a(k) == 0
a(k) = a(k) + 2;
end
end
In this example, end is used in an indexing expression.
A = magic(5)
2-570
end
A =
17
23
4
10
11
24
5
6
12
18
1
7
13
19
25
8
14
20
21
2
15
16
22
3
9
B = A(end,2:end)
B =
18
See Also
25
2
9
break, for, if, return, switch, try, while
2-571
eomday
Purpose
2eomday
End of month
Syntax
E = eomday(Y,M)
Description
E = eomday(Y,M) returns the last day of the year and month given by
corresponding elements of arrays Y and M.
Examples
Because 1996 is a leap year, the statement eomday(1996,2) returns 29.
To show all the leap years in this century, try:
y = 1900:1999;
E = eomday(y,2∗ones(length(y),1)');
y(find(E==29))'
ans =
Columns 1 through 6
1904
1908
See Also
2-572
1912
1916
1920
1924
Columns 7 through 12
1928
1932
1936
1940
1944
1948
Columns 13 through 18
1952
1956
1960
1964
1968
1972
Columns 19 through 24
1976
1980
1984
1988
1992
1996
datenum, datevec, weekday
eps
Purpose
2eps
Floating-point relative accuracy
Syntax
eps
Description
eps returns the distance from 1.0 to the next largest floating-point number.
The value eps is a default tolerance for pinv and rank, as well as several other
MATLAB functions. eps = 2^(-52), which is roughly 2.22e-16.
See Also
realmax, realmin
2-573
erf, erfc, erfcx, erfinv, erfcinv
Purpose
2erf, erfc, erfcx, erfinv, erfcinv
Error functions
Syntax
Y
Y
Y
X
X
Definition
The error function erf(X) is twice the integral of the Gaussian distribution
with 0 mean and variance of 1 ⁄ 2 .
=
=
=
=
=
Error function
Complementary error function
Scaled complementary error function
Inverse error function
Inverse complementary error function
erf(X)
erfc(X)
erfcx(X)
erfinv(Y)
erfcinv(Y)
2
π
erf ( x ) = -------
x
∫0 e –t dt
2
The complementary error function erfc(X) is defined as
2
π
erfc ( x ) = -------
∞
∫x e –t dt
2
= 1 – erf ( x )
The scaled complementary error function erfcx(X) is defined as
erfcx ( x ) = e x erfc ( x )
2
1 1
For large X, erfcx(X) is approximately  -------  -- πx
Description
Y = erf(X) returns the value of the error function for each element of real
array X.
Y = erfc(X) computes the value of the complementary error function.
Y = erfcx(X) computes the value of the scaled complementary error function.
X = erfinv(Y) returns the value of the inverse error function for each element
of Y. Elements of Y must be in the interval [-1 1]. The function erfinv
satisfies y = erf( x) for – 1 ≤ y ≤ 1 and – ∞ ≤ x ≤ ∞ .
X = erfcinv(Y) returns the value of the inverse of the complementary error
function for each element of Y. Elements of Y must be in the interval [0 2].
The function erfcinv satisfies y = erfc( x) for 2 ≥ y ≥ 0 and – ∞ ≤ x ≤ ∞ .
2-574
erf, erfc, erfcx, erfinv, erfcinv
Remarks
The relationship between the complementary error function erfc and the
standard normal probability distribution returned by the Statistics Toolbox
function normcdf is
normcdf ( x ) = 0.5 * erfc ( – x ⁄
2)
The relationship between the inverse complementary error function erfcinv
and the inverse standard normal probability distribution returned by the
Statistics Toolbox function norminv is
norminv ( p ) = – 2 * erfcinv ( 2 p )
Examples
erfinv(1) is Inf
erfinv(-1) is -Inf.
For abs(Y) > 1, erfinv(Y) is NaN.
Algorithms
For the error functions, the MATLAB code is a translation of a Fortran
program by W. J. Cody, Argonne National Laboratory, NETLIB/SPECFUN,
March 19, 1990. The main computation evaluates near-minimax rational
approximations from [1].
For the inverse of the error function, rational approximations accurate to
approximately six significant digits are used to generate an initial
approximation, which is then improved to full accuracy by one step of Halley’s
method.
References
[1] Cody, W. J., “Rational Chebyshev Approximations for the Error Function,”
Math. Comp., pgs. 631-638, 1969
2-575
error
Purpose
2error
Display error messages
Syntax
error('message')
error('message',a1,a2, ...)
error('message_id','message')
error('message_id','message',a1,a2,...)
Description
error('message') displays an error message and returns control to the
keyboard. The error message contains the input string message.
The error command has no effect if message is a null string.
error('message',a1,a2,...) displays a message string that contains
formatting conversion characters, such as those used with the MATLAB
sprintf function. Each conversion character in message is converted to one of
the values a1, a2, ... in the argument list.
Note MATLAB converts special characters (like \n and %d) in the error
message string only when you specify more than one input argument with
error. See Example 3 below.
error('message_id','message') attaches a unique message identifier, or
message_id, to the error message. The identifier enables you to better identify
the source of an error. See “Message Identifiers” and “Using Message
Identifiers with lasterr” in the MATLAB documentation for more information
on the message_id argument and how to use it.
error('message_id','message',a1,a2, ...) includes formatting
conversion characters in message, and the character translations a1, a2, ...
Examples
Example 1
The error function provides an error return from M-files:
function foo(x,y)
if nargin ~= 2
error('Wrong number of input arguments')
end
2-576
error
The returned error message looks like this:
foo(pi)
??? Error using ==> foo
Wrong number of input arguments
Example 2
Specify a message identifier and error message string with error:
error('MyToolbox:angleTooLarge', ...
'The angle specified must be less than 90 degrees.');
In your error handling code, use lasterr to determine the message identifier
and error message string for the failing operation:
[errmsg, msgid] = lasterr
errmsg =
The angle specified must be less than 90 degrees.
msgid =
MyToolbox:angleTooLarge
Example 3
MATLAB converts special characters (like \n and %d) in the error message
string only when you specify more than one input argument with error. In the
single argument case shown below, \n is taken to mean backslash-n. It is not
converted to a newline character:
error('In this case, the newline \n is not converted.')
??? In this case, the newline \n is not converted.
But, when more than one argument is specified, MATLAB does convert special
characters. This holds true regardless of whether the additional argument
supplies conversion values or is a message identifier:
error('ErrorTests:convertTest', ...
'In this case, the newline \n is converted.')
??? In this case, the newline
is converted.
See Also
lasterr, lasterror, rethrow, errordlg, warning, lastwarn, warndlg, dbstop,
disp, sprintf
2-577
errorbar
Purpose
2errorbar
Plot error bars along a curve
Syntax
errorbar(Y,E)
errorbar(X,Y,E)
errorbar(X,Y,L,U)
errorbar(...,LineSpec)
h = errorbar(...)
Description
Error bars show the confidence level of data or the deviation along a curve.
errorbar(Y,E) plots Y and draws an error bar at each element of Y. The error
bar is a distance of E(i) above and below the curve so that each bar is
symmetric and 2*E(i) long.
errorbar(X,Y,E) plots X versus Y with symmetric error bars 2*E(i) long. X, Y,
E must be the same size. When they are vectors, each error bar is a distance of
E(i) above and below the point defined by (X(i),Y(i)). When they are
matrices, each error bar is a distance of E(i,j) above and below the point
defined by (X(i,j),Y(i,j)).
errorbar(X,Y,L,U) plots X versus Y with error bars L(i)+U(i) long specifying
the lower and upper error bars. X, Y, L, and U must be the same size. When they
are vectors, each error bar is a distance of L(i) below and U(i) above the point
defined by (X(i),Y(i)). When they are matrices, each error bar is a distance
of L(i,j) below and U(i,j) above the point defined by (X(i,j),Y(i,j)).
errorbar(...,LineSpec) draws the error bars using the line type, marker
symbol, and color specified by LineSpec.
h = errorbar(...) returns a vector of handles to line graphics objects.
Remarks
When the arguments are all matrices, errorbar draws one line per matrix
column. If X and Y are vectors, they specify one curve.
Examples
Draw symmetric error bars that are two standard deviation units in length.
X = 0:pi/10:pi;
Y = sin(X);
E = std(Y)*ones(size(X));
2-578
errorbar
errorbar(X,Y,E)
1.4
1.2
1
0.8
0.6
0.4
0.2
0
−0.2
−0.4
−0.5
See Also
0
0.5
1
1.5
2
2.5
3
3.5
LineSpec, plot, std
“Basic Plots and Graphs” for related functions
2-579
errordlg
Purpose
2errordlg
Create and display an error dialog box
Syntax
errordlg
errordlg('errorstring')
errordlg('errorstring','dlgname')
errordlg('errorstring','dlgname','on')
h = errordlg(...)
Description
errordlg creates an error dialog box, or if the named dialog exists, errordlg
pops the named dialog in front of other windows.
errordlg displays a dialog box named 'Error Dialog' that contains the string
'This is the default error string.'
errordlg('errorstring') displays a dialog box named 'Error Dialog' that
contains the string 'errorstring'.
errordlg('errorstring','dlgname') displays a dialog box named 'dlgname'
that contains the string 'errorstring'.
errordlg('errorstring','dlgname','on') specifies whether to replace an
existing dialog box having the same name. 'on' brings an existing error dialog
having the same name to the foreground. In this case, errordlg does not create
a new dialog.
h = errordlg(...) returns the handle of the dialog box.
Remarks
MATLAB sizes the dialog box to fit the string 'errorstring'. The error dialog
box has an OK pushbutton and remains on the screen until you press the OK
button or the Return key. After pressing the button, the error dialog box
disappears.
The appearance of the dialog box depends on the windowing system you use.
Examples
The function
errordlg('File not found','File Error');
2-580
errordlg
displays this dialog box:
See Also
dialog, helpdlg, msgbox, questdlg, warndlg
“Predefined Dialog Boxes” for related functions
2-581
etime
Purpose
2etime
Elapsed time
Syntax
e = etime(t2,t1)
Description
e = etime(t2,t1) returns the time in seconds between vectors t1 and t2. The
two vectors must be six elements long, in the format returned by clock:
T = [Year Month Day Hour Minute Second]
Examples
Calculate how long a 2048-point real FFT takes.
x = rand(2048,1);
t = clock; fft(x); etime(clock,t)
ans =
0.4167
Limitations
As currently implemented, the etime function fails across month and year
boundaries. Since etime is an M-file, you can modify the code to work across
these boundaries if needed.
See Also
clock, cputime, tic, toc
2-582
etree
Purpose
2etree
Elimination tree
Syntax
p = etree(A)
p = etree(A,'col')
p = etree(A,'sym')
[p,q] = etree(...)
Description
p = etree(A) returns an elimination tree for the square symmetric matrix
whose upper triangle is that of A. p(j) is the parent of column j in the tree, or
0 if j is a root.
p = etree(A,'col') returns the elimination tree of A'*A.
p = etree(A,'sym') is the same as p = etree(A).
[p,q] = etree(...) also returns a postorder permutation q of the tree.
See Also
treelayout, treeplot, etreeplot
2-583
etreeplot
Purpose
2etreeplot
Plot elimination tree
Syntax
etreeplot(A)
etreeplot(A,nodeSpec,edgeSpec)
Description
etreeplot(A) plots the elimination tree of A (or A+A', if non-symmetric).
etreeplot(A,nodeSpec,edgeSpec) allows optional parameters nodeSpec and
edgeSpec to set the node or edge color, marker, and linestyle. Use '' to omit
one or both.
See Also
2-584
etree, treeplot, treelayout
eval
Purpose
2eval
Execute a string containing a MATLAB expression
Syntax
eval(expression)
eval(expression,catch_expr)
[a1,a2,a3,...] = eval(function(b1,b2,b3,...))
Description
eval(expression) executes expression, a string containing any valid
MATLAB expression. You can construct expression by concatenating
substrings and variables inside square brackets:
expression = [string1,int2str(var),string2,...]
eval(expression,catch_expr) executes expression and, if an error is
detected, executes the catch_expr string. If expression produces an error, the
error string can be obtained with the lasterr function. This syntax is useful
when expression is a string that must be constructed from substrings. If this
is not the case, use the try...catch control flow statement in your code.
[a1,a2,a3,...] = eval(function(b1,b2,b3,...)) executes function with
arguments b1,b2,b3,..., and returns the results in the specified output
variables.
Remarks
Examples
Using the eval output argument list is recommended over including the output
arguments in the expression string. The first syntax below avoids strict
checking by the MATLAB parser and can produce untrapped errors and other
unexpected behavior.
eval('[a1,a2,a3,...] = function(var)')
% not recommended
[a1,a2,a3,...] = eval('function(var)')
% recommended syntax
This for loop generates a sequence of 12 matrices named M1 through M12:
for n = 1:12
magic_str = ['M',int2str(n),' = magic(n)'];
eval(magic_str)
end
2-585
eval
This example uses a function showdemo that runs a MATLAB demo selected by
the user. If an error is encountered, a message is displayed that names the
demo that failed.
function showdemo(demos)
errstring = 'Error running demo: ';
n = input('Select a demo number: ');
eval(demos(n,:),'[errstring demos(n,:)]')
% ----- end of file showdemo.m ----D = ['odedemo'; 'quademo'; 'fitdemo'];
showdemo(D)
Select a demo number: 2
ans =
Error running demo: quademo
The next example executes the size function on a 3-dimensional array,
returning the array dimensions in output variables d1, d2, and d3.
A = magic(4);
A(:,:,2) = A';
[d1,d2,d3] = eval('size(A)')
d1 =
4
d2 =
4
d3 =
2
See Also
2-586
assignin, catch, evalin, feval, lasterr, try
evalc
Purpose
2evalc
Evaluate MATLAB expression with capture
Syntax
T = evalc(S)
T = evalc(s1,s2)
[T,X,Y,Z,...] = evalc(S)
Description
T = evalc(S) is the same as eval(S) except that anything that would normally
be written to the command window is captured and returned in the character
array T (lines in T are separated by \n characters).
T = evalc(s1,s2) is the same as eval(s1,s2) except that any output is
captured into T.
[T,X,Y,Z,...] = evalc(S) is the same as [X,Y,Z,...] = eval(S) except
that any output is captured into T.
Remark
When you are using evalc, diary, more, and input are disabled.
See Also
diary, eval, evalin, input, more
2-587
evalin
Purpose
2evalin
Syntax
evalin(ws,expression)
[a1,a2,a3,...] = evalin(ws,expression)
evalin(ws,expression,catch_expr)
Description
evalin(ws,expression) executes expression, a string containing any valid
MATLAB expression, in the context of the workspace ws. ws can have a value
of 'base' or 'caller' to denote the MATLAB base workspace or the workspace
of the caller function. You can construct expression by concatenating
Execute a string containing a MATLAB expression in a workspace
substrings and variables inside square brackets:
expression = [string1,int2str(var),string2,...]
[a1,a2,a3,...] = evalin(ws,expression) executes expression and
returns the results in the specified output variables. Using the evalin output
argument list is recommended over including the output arguments in the
expression string:
evalin(ws,'[a1,a2,a3,...] = function(var)')
The above syntax avoids strict checking by the MATLAB parser and can
produce untrapped errors and other unexpected behavior.
evalin(ws,expression,catch_expr) executes expression and, if an error is
detected, executes the catch_expr string. If expression produces an error, the
error string can be obtained with the lasterr function. This syntax is useful
when expression is a string that must be constructed from substrings. If this
is not the case, use the try...catch control flow statement in your code.
Remarks
The MATLAB base workspace is the workspace that is seen from the MATLAB
command line (when not in the debugger). The caller workspace is the
workspace of the function that called the M-file. Note, the base and caller
workspaces are equivalent in the context of an M-file that is invoked from the
MATLAB command line.
Examples
This example extracts the value of the variable var in the MATLAB base
workspace and captures the value in the local variable v:
v = evalin('base','var');
2-588
evalin
Limitation
evalin cannot be used recursively to evaluate an expression. For example, a
sequence of the form evalin('caller','evalin(''caller'',''x'')')
doesn’t work.
See Also
assignin, catch, eval, feval, lasterr, try
2-589
eventlisteners (COM)
Purpose
2eventlisteners (COM)
Return a list of events attached to listeners
Syntax
eventlisteners(h)
Arguments
h
Handle for a MATLAB COM control object.
Description
eventlisteners lists any events, along with their callback or event handler
routines, that have been registered with control, h. The function returns a cell
array of strings, with each row containing the name of a registered event and
the handler routine for that event. If the control has no registered events, then
eventlisteners returns an empty cell array.
Events and their callback or event handler routines must be registered in order
for the control to respond to them. You can register events either when you
create the control, using actxcontrol, or at any time afterwards, using
registerevent.
Examples
Create an mwsamp control, registering only the Click event. eventlisteners
returns the name of the event and its event handler routine, myclick:
f = figure('pos', [100 200 200 200]);
h = actxcontrol('mwsamp.mwsampctrl.2', [0 0 200 200], f, ...
{'Click' 'myclick'});
eventlisteners(h)
ans =
'click'
'myclick'
Register two more events: DblClick and MouseDown. eventlisteners returns
the names of the three registered events along with their respective handler
routines:
registerevent(h, {'DblClick', 'my2click'; ...
'MouseDown' 'mymoused'});
eventlisteners(h)
ans =
'click'
'dblclick'
2-590
'myclick'
'my2click'
eventlisteners (COM)
'mousedown'
'mymoused'
Now unregister all events for the control, and eventlisteners returns an
empty cell array, indicating that no events have been registered for the control:
unregisterallevents(h)
eventlisteners(h)
ans =
{}
See Also
events, registerevent, unregisterevent, unregisterallevents, isevent
2-591
events (COM)
Purpose
2events (COM)
Return a list of events that the control can trigger
Syntax
events(h)
Arguments
h
Handle for a MATLAB COM control object.
Description
Returns a structure array containing all events, both registered and
unregistered, known to the control, and the function prototype used when
calling the event handler routine. For each array element, the structure field
is the event name and the contents of that field is the function prototype for
that event’s handler.
Note The send function is identical to events, but send will be made obsolete
in a future release.
Examples
Create an mwsamp control and list all events:
f = figure ('pos', [100 200 200 200]);
h = actxcontrol ('mwsamp.mwsampctrl.2', [0 0 200 200], f);
events(h)
Click = void Click()
DblClick = void DblClick()
MouseDown = void MouseDown(int16 Button, int16 Shift,
Variant x, Variant y)
Or assign the output to a variable and get one field of the returned structure:
ev = events(h);
ev.MouseDown
ans =
void MouseDown(int16 Button, int16 Shift, Variant x, Variant y)
See Also
2-592
isevent, eventlisteners, registerevent, unregisterevent,
unregisterallevents
events (COM)
In the following example, exist returns 8 on the Java class, Welcome, and
returns 2 on the Java class file, Welcome.class.
exist Welcome
ans =
8
exist javaclasses/Welcome.class
ans =
2
indicates there is a Java class Welcome and a Java class file Welcome.class.
The following example indicates that testresults is both a variable in the
workspace and a directory on the search path:
exist('testresults','var')
ans =
1
exist('testresults','dir')
ans =
7
See Also
dir, help, lookfor, partialpath, what, which, who
2-593
exist
Purpose
2exist
Graphical
Interface
As an alternative to the exist function, use the Workspace browser or the
Current Directory Browser.
Syntax
exist item
exist item kind
a = exist('item',...)
Description
exist item returns the status of the variable or file, item:
Check if a variable or file exists
0
If item does not exist.
1
If the variable item exists in the workspace.
2
If item is an M-file or a file of unknown type.
3
If item is a MEX-file on your MATLAB search path.
4
If item is an MDL-file on your MATLAB search path.
5
If item is a built-in MATLAB function.
6
If item is a P-file on your MATLAB search path.
7
If item is a directory.
8
If item is a Java class.
If item specifies a filename, that filename may include an extension to
preclude conflicting with other similar filenames. For example,
exist('file.ext').
MEX, MDL, and P-files must be on the MATLAB search path for exist to
return the values shown above. If item is found, but is not on the MATLAB
search path, exist('item') returns 2, because it considers item to be an
unknown file type.
Any other file type or directory specified by item is not required to be on the
MATLAB search path to be recognized by exist. If the file or directory is not
on the search path, then item must specify either a full pathname, a partial
pathname relative to MATLABPATH, or a partial pathname relative to your
current directory.
2-594
exist
If item is a Java class, then exist('item') returns an 8. However, if item is a
Java class file, then exist('item') returns a 2.
exist item kind returns the status of item for the specified kind. If item of
type kind does not exist, it returns 0. The kind argument may be one of the
following:
builtin
Checks only for built-in functions.
class
Checks only for Java classes.
dir
Checks only for directories.
file
Checks only for files or directories.
var
Checks only for variables.
a = exist('item',...) returns the status of the variable or file in variable a.
Remarks
To check for the existence of more than one variable, use the ismember
function. For example,
a = 5.83;
c = 'teststring';
ismember({'a','b','c'},who)
ans =
1
Examples
0
1
This example uses exist to check whether a MATLAB function is a built-in
function or a file:
type = exist('plot')
type =
5
This indicates that plot is a built-in function.
2-595
exit
Purpose
2exit
Graphical
Interface
As an alternative to the exit function, select Exit MATLAB from the File
menu or click the close box in the MATLAB desktop.
Syntax
exit
Description
exit ends the current MATLAB session. It is the same as quit. See quit for
termination options.
See Also
finish, quit
2-596
Terminate MATLAB (same as quit)
exp
Purpose
2exp
Exponential
Syntax
Y = exp(X)
Description
The exp function is an elementary function that operates element-wise on
arrays. Its domain includes complex numbers.
Y = exp(X) returns the exponential for each element of X. For complex
z = x + i* y , it returns the complex exponential e z = e x ( cos ( y ) + i sin ( y ) ) .
Remark
Use expm for matrix exponentials.
See Also
expm, log, log10, expint
2-597
expint
Purpose
2expint
Exponential integral
Syntax
Y = expint(X)
Definitions
The exponential integral computed by this function is defined as
E 1( x) =
∞
∫x
e –t
------- dt
t
Another common definition of the exponential integral function is the Cauchy
principal value integral
Ei ( x ) =
x
et
∫ ---- dt
–∞ t
which, for real positive x, is related to expint as
E 1 ( – x ) = – Ei ( x ) – iπ
Description
Y = expint(X) evaluates the exponential integral for each element of X.
References
[1] Abramowitz, M. and I. A. Stegun. Handbook of Mathematical Functions.
Chapter 5, New York: Dover Publications, 1965.
2-598
expm
Purpose
2expm
Matrix exponential
Syntax
Y = expm(X)
Description
Y = expm(X) raises the constant e to the matrix power X. The expm function
produces complex results if X has nonpositive eigenvalues.
Use exp for the element-by-element exponential.
Algorithm
expm is a built-in function that uses the Padé approximation with scaling and
squaring. You can see the coding of this algorithm in the expm1 demo.
Note The expm1, expm2, and expm3 demos illustrate the use of Padé
approximation, Taylor series approximation, and eigenvalues and
eigenvectors, respectively, to compute the matrix exponential.
References [1] and [2] describe and compare many algorithms for computing a
matrix exponential. The built-in method, expm, is essentially method 3 of [2].
Examples
This example computes and compares the matrix exponential of A and the
exponential of A.
A = [1
0
0
expm(A)
ans =
2.7183
0
0
exp(A)
ans =
2.7183
1.0000
1.0000
1
0
0
0
2
-1 ];
1.7183
1.0000
0
2.7183
1.0000
1.0000
1.0862
1.2642
0.3679
1.0000
7.3891
0.3679
2-599
expm
Notice that the diagonal elements of the two results are equal. This would be
true for any triangular matrix. But the off-diagonal elements, including those
below the diagonal, are different.
See Also
exp, funm, logm, sqrtm
References
[1] Golub, G. H. and C. F. Van Loan, Matrix Computation, p. 384, Johns
Hopkins University Press, 1983.
[2] Moler, C. B. and C. F. Van Loan, “Nineteen Dubious Ways to Compute the
Exponential of a Matrix,” SIAM Review 20, 1979, pp. 801-836.
2-600
eye
Purpose
2eye
Identity matrix
Syntax
Y
Y
Y
=
=
=
eye(n)
eye(m,n)
eye(size(A))
Description
Y
=
eye(n) returns the n-by-n identity matrix.
= eye(m,n) or eye([m n]) returns an m-by-n matrix with 1’s on the
diagonal and 0’s elsewhere.
Y
Y
=
eye(size(A)) returns an identity matrix the same size as A.
Limitations
The identity matrix is not defined for higher-dimensional arrays. The
assignment y = eye([2,3,4]) results in an error.
See Also
ones, rand, randn, zeros
2-601
ezcontour
Purpose
2ezcontour
Easy to use contour plotter
Syntax
ezcontour(f)
ezcontour(f,domain)
ezcontour(...,n)
Description
ezcontour(f) plots the contour lines of f(x,y), where f is a string that
represents a mathematical function of two variables, such as x and y.
The function f is plotted over the default domain: -2π < x < 2π, -2π < y < 2π.
MATLAB chooses the computational grid according to the amount of variation
that occurs; if the function f is not defined (singular) for points on the grid, then
these points are not plotted.
ezcontour(f,domain) plots f(x,y) over the specified domain. domain can be
either a 4-by-1 vector [xmin, xmax, ymin, ymax] or a 2-by-1 vector [min, max]
(where min < x < max, min < y < max).
If f is a function of the variables u and v (rather than x and y), then the domain
endpoints umin, umax, vmin, and vmax are sorted alphabetically. Thus,
ezcontour('u^2 - v^3',[0,1],[3,6]) plots the contour lines for u2 - v3 over
0 < u < 1, 3 < v < 6.
ezcontour(...,n) plots f over the default domain using an n-by-n grid. The
default value for n is 60.
ezcontour automatically adds a title and axis labels.
Remarks
Array multiplication, division, and exponentiation are always implied in the
expression you pass to ezcontour. For example, the MATLAB syntax for a
contour plot of the expression,
sqrt(x.^2 + y.^2)
is written as:
ezcontour('sqrt(x^2 + y^2)')
That is, x^2 is interpreted as x.^2 in the string you pass to ezcontour.
Examples
2-602
The following mathematical expression defines a function of two variables, x
and y.
ezcontour
1
x
2
2
2
2
– 10  --- – x 3 – y 5 e – x – y – --- e – ( x + 1 ) – y
5

3
ezcontour requires a string argument that expresses this function using
MATLAB syntax to represent exponents, natural logs, etc. This function is
represented by the string:
f ( x, y ) = 3 ( 1 – x ) 2 e – x
2
– ( y + 1 )2
f = ['3*(1−x)^2*exp(−(x^2)−(y+1)^2)',...
'− 10*(x/5 − x^3 − y^5)*exp(-x^2−y^2)',...
'- 1/3*exp(−(x+1)^2 − y^2)'];
For convenience, this string is written on three lines and concatenated into one
string using square brackets.
Pass the string variable f to ezcontour along with a domain ranging from −3
to 3 and specify a computational grid of 49-by-49:
ezcontour(f,[-3,3],49)
3 (1−x)2 exp(−(x2) − (y+1)2)− ~~~ x2−y2)− 1/3 exp(−(x+1)2 − y2)
3
2
y
1
0
−1
−2
−3
−3
−2
−1
0
x
1
2
3
In this particular case, the title is too long to fit at the top of the graph so
MATLAB abbreviates the string.
2-603
ezcontour
See Also
contour, ezcontourf, ezmesh, ezmeshc, ezplot, ezplot3, ezpolar, ezsurf,
ezsurfc
“Contour Plots” for related functions
2-604
ezcontourf
Purpose
2ezcontourf
Easy to use filled contour plotter
Syntax
ezcontourf(f)
ezcontourf(f,domain)
ezcontourf(...,n)
Description
ezcontourf(f) plots the contour lines of f(x,y), where f is a string that
represents a mathematical function of two variables, such as x and y.
The function f is plotted over the default domain: -2π < x < 2π, -2π < y < 2π.
MATLAB chooses the computational grid according to the amount of variation
that occurs; if the function f is not defined (singular) for points on the grid, then
these points are not plotted.
ezcontourf(f,domain) plots f(x,y) over the specified domain. domain can be
either a 4-by-1 vector [xmin, xmax, ymin, ymax] or a 2-by-1 vector [min, max]
(where, min < x < max, min < y < max).
If f is a function of the variables u and v (rather than x and y), then the domain
endpoints umin, umax, vmin, and vmax are sorted alphabetically. Thus,
ezcontourf('u^2 - v^3',[0,1],[3,6]) plots the contour lines for u2 - v3 over
0 < u < 1, 3 < v < 6.
ezcontourf(...,n) plots f over the default domain using an n-by-n grid. The
default value for n is 60.
ezcontourf automatically adds a title and axis labels.
Remarks
Array multiplication, division, and exponentiation are always implied in the
expression you pass to ezcontourf. For example, the MATLAB syntax for a
filled contour plot of the expression,
sqrt(x.^2 + y.^2);
is written as:
ezcontourf('sqrt(x^2 + y^2)')
That is, x^2 is interpreted as x.^2 in the string you pass to ezcontourf.
Examples
The following mathematical expression defines a function of two variables, x
and y.
2-605
ezcontourf
1
x
2
2
2
2
– 10  --- – x 3 – y 5 e – x – y – --- e – ( x + 1 ) – y
5

3
ezcontourf requires a string argument that expresses this function using
MATLAB syntax to represent exponents, natural logs, etc. This function is
represented by the string:
f ( x, y ) = 3 ( 1 – x ) 2 e – x
2
– ( y + 1 )2
f = ['3*(1−x)^2*exp(−(x^2)−(y+1)^2)',...
'− 10*(x/5 − x^3 − y^5)*exp(-x^2−y^2)',...
'- 1/3*exp(−(x+1)^2 − y^2)'];
For convenience, this string is written on three lines and concatenated into one
string using square brackets.
Pass the string variable f to ezcontourf along with a domain ranging from −3
to 3 and specify a grid of 49-by-49:
ezcontourf(f,[-3,3],49)
3 (1−x)2 exp(−(x2) − (y+1)2)− ~~~ x2−y2)− 1/3 exp(−(x+1)2 − y2)
3
2
y
1
0
−1
−2
−3
−3
−2
−1
0
x
1
2
3
In this particular case, the title is too long to fit at the top of the graph so
MATLAB abbreviates the string.
2-606
ezcontourf
See Also
contourf, ezcontour, ezmesh, ezmeshc, ezplot, ezplot3, ezpolar, ezsurf,
ezsurfc
“Contour Plots” for related functions
2-607
ezmesh
Purpose
2ezmesh
Easy to use 3-D mesh plotter
Syntax
ezmesh(f)
ezmesh(f,domain)
ezmesh(x,y,z)
ezmesh(x,y,z,[smin,smax,tmin,tmax]) or ezmesh(x,y,z,[min,max])
ezmesh(...,n)
ezmesh(...,'circ')
Description
ezmesh(f) creates a graph of f(x,y), where f is a string that represents a
mathematical function of two variables, such as x and y.
The function f is plotted over the default domain: -2π < x < 2π, -2π < y < 2π.
MATLAB chooses the computational grid according to the amount of variation
that occurs; if the function f is not defined (singular) for points on the grid, then
these points are not plotted.
ezmesh(f,domain) plots f over the specified domain. domain can be either a
4-by-1 vector [xmin, xmax, ymin, ymax] or a 2-by-1 vector [min, max] (where,
min < x < max, min < y < max).
If f is a function of the variables u and v (rather than x and y), then the domain
endpoints umin, umax, vmin, and vmax are sorted alphabetically. Thus,
ezmesh('u^2 - v^3',[0,1],[3,6]) plots u2 - v3 over 0 < u < 1, 3 < v < 6.
ezmesh(x,y,z) plots the parametric surface x = x(s,t), y = y(s,t), and z = z(s,t)
over the square: -2π < s < 2π, -2π < t < 2π.
ezmesh(x,y,z,[smin,smax,tmin,tmax]) or ezmesh(x,y,z,[min,max]) plots
the parametric surface using the specified domain.
ezmesh(...,n) plots f over the default domain using an n-by-n grid. The
default value for n is 60.
ezmesh(...,'circ') plots f over a disk centered on the domain.
Remarks
Array multiplication, division, and exponentiation are always implied in the
expression you pass to ezmesh. For example, the MATLAB syntax for a mesh
plot of the expression,
sqrt(x.^2 + y.^2);
2-608
ezmesh
is written as:
ezmesh('sqrt(x^2 + y^2)')
That is, x^2 is interpreted as x.^2 in the string you pass to ezmesh.
Examples
This example visualizes the function,
f ( x, y ) = xe
2
–x – y
2
with a mesh plot drawn on a 40-by-40 grid. The mesh lines are set to a uniform
blue color by setting the colormap to a single color:
ezmesh('x*exp(-x^2-y^2)',40)
colormap([0 0 1])
x exp(−x2 − y2)
0.5
0
−0.5
2
1
2
0
0
−1
y
See Also
−2
−2
x
ezmeshc, mesh
“Function Plots” for related functions
2-609
ezmeshc
Purpose
2ezmeshc
Easy to use combination mesh/contour plotter
Syntax
ezmeshc(f)
ezmeshc(f,domain)
ezmeshc(x,y,z)
ezmeshc(x,y,z,[smin,smax,tmin,tmax]) or ezmeshc(x,y,z,[min,max])
ezmeshc(...,n)
ezmeshc(...,'circ')
Description
ezmeshc(f) creates a graph of f(x,y), where f is a string that represents a
mathematical function of two variables, such as x and y.
The function f is plotted over the default domain: -2π < x < 2π, -2π < y < 2π.
MATLAB chooses the computational grid according to the amount of variation
that occurs; if the function f is not defined (singular) for points on the grid, then
these points are not plotted.
ezmeshc(f,domain) plots f over the specified domain. domain can be either a
4-by-1 vector [xmin, xmax, ymin, ymax] or a 2-by-1 vector [min, max] (where,
min < x < max, min < y < max).
If f is a function of the variables u and v (rather than x and y), then the domain
endpoints umin, umax, vmin, and vmax are sorted alphabetically. Thus,
ezmeshc('u^2 - v^3',[0,1],[3,6]) plots u2 - v3 over 0 < u < 1, 3 < v < 6.
ezmeshc(x,y,z) plots the parametric surface x = x(s,t), y = y(s,t), and z = z(s,t)
over the square: -2π < s < 2π, -2π < t < 2π.
ezmeshc(x,y,z,[smin,smax,tmin,tmax]) or ezmeshc(x,y,z,[min,max])
plots the parametric surface using the specified domain.
ezmeshc(...,n) plots f over the default domain using an n-by-n grid. The
default value for n is 60.
ezmeshc(...,'circ') plots f over a disk centered on the domain.
Remarks
Array multiplication, division, and exponentiation are always implied in the
expression you pass to ezmeshc. For example, the MATLAB syntax for a
mesh/contour plot of the expression,
sqrt(x.^2 + y.^2);
2-610
ezmeshc
is written as:
ezmeshc('sqrt(x^2 + y^2)')
That is, x^2 is interpreted as x.^2 in the string you pass to ezmeshc.
Examples
Create a mesh/contour graph of the expression,
y
f ( x, y ) = ---------------------------2
2
1+x + y
over the domain -5 < x < 5, -2*pi < y < 2*pi:
ezmeshc('y/(1 + x^2 + y^2)',[−5,5,−2*pi,2*pi])
Use the mouse to rotate the axes to better observe the contour lines (this
picture uses a view of azimuth = -65.5 and elevation = 26).
y/(1 + x2 + y2)
0.5
0
5
−0.5
0
5
0
−5
y
See Also
−5
x
ezmesh, ezsurfc, meshc
“Function Plots” for related functions
2-611
ezplot
Purpose
2ezplot
Easy to use function plotter
Syntax
ezplot(f)
ezplot(f,[min,max])
ezplot(f,[xmin,xmax,ymin,ymax])
ezplot(x,y)
ezplot(x,y,[tmin,tmax])
ezplot(...,figure)
Description
ezplot(f) plots the expression f = f(x) over the default domain: -2π < x < 2π.
ezplot(f,[min,max]) plots f = f(x) over the domain: min < x < max.
For implicitly defined functions, f = f(x,y):
ezplot(f) plots f(x,y) = 0 over the default domain -2π < x < 2π, -2π < y < 2π.
ezplot(f,[xmin,xmax,ymin,ymax]) plots f(x,y) = 0 over xmin < x < xmax and
ymin < y < ymax.
ezplot(f,[min,max])plots f(x,y) = 0 over min < x < max and min < y < max.
If f is a function of the variables u and v (rather than x and y), then the domain
endpoints umin, umax, vmin, and vmax are sorted alphabetically. Thus,
ezplot('u^2 - v^2 - 1',[-3,2,-2,3]) plots u2 - v2 - 1 = 0 over -3 < u < 2, -2
< v < 3.
ezplot(x,y) plots the parametrically defined planar curve x = x(t) and y = y(t)
over the default domain 0 < t < 2π.
ezplot(x,y,[tmin,tmax]) plots x = x(t) and y = y(t) over tmin < t < tmax.
ezplot(...,figure) plots the given function over the specified domain in the
figure window identified by the handle figure.
Remarks
Array multiplication, division, and exponentiation are always implied in the
expression you pass to ezplot. For example, the MATLAB syntax for a plot of
the expression,
x.^2 - y.^2
which represents an implicitly defined function, is written as:
ezplot('x^2 - y^2')
2-612
ezplot
That is, x^2 is interpreted as x.^2 in the string you pass to ezplot.
Examples
This example plots the implicitly defined function,
x2 - y4 = 0
over the domain [-2π, 2π]:
ezplot('x^2-y^4')
x2−y4 = 0
6
4
y
2
0
−2
−4
−6
−6
See Also
−4
−2
0
x
2
4
6
ezplot3, ezpolar, plot
“Function Plots” for related functions
2-613
ezplot3
Purpose
2ezplot3
Easy to use 3-D parametric curve plotter
Syntax
ezplot3(x,y,z)
ezplot3(x,y,z,[tmin,tmax])
ezplot3(...,'animate')
Description
ezplot3(x,y,z) plots the spatial curve x = x(t), y = y(t), and z = z(t) over the
default domain 0 < t < 2π.
ezplot3(x,y,z,[tmin,tmax]) plots the curve x = x(t), y = y(t), and z = z(t) over
the domain tmin < t < tmax.
ezplot3(...,'animate') produces an animated trace of the spatial curve.
Remarks
Array multiplication, division, and exponentiation are always implied in the
expression you pass to ezplot3. For example, the MATLAB syntax for a plot of
the expression,
x = s./2, y = 2.*s, z = s.^2;
which represents a parametric function, is written as:
ezplot3('s/2','2*s','s^2')
That is, s/2 is interpreted as s./2 in the string you pass to ezplot3.
Examples
This example plots the parametric curve,
x = sin t ,
y = cos t ,
z=t
over the domain [0,6π]:
ezplot3('sin(t)','cos(t)','t',[0,6*pi])
2-614
ezplot3
x = sin(t), y = cos(t), z = t
20
z
15
10
5
0
1
1
0.5
0.5
0
0
−0.5
y
See Also
−0.5
−1
−1
x
ezplot, ezpolar, plot3
“Function Plots” for related functions
2-615
ezpolar
Purpose
2ezpolar
Easy to use polar coordinate plotter
Syntax
ezpolar(f)
ezpolar(f,[a,b])
Description
ezpolar(f) plots the polar curve rho = f(theta) over the default domain 0 <
theta < 2π.
ezpolar(f,[a,b]) plots f for a < theta < b.
Examples
This example creates a polar plot of the function,
1 + cos(t)
over the domain [0, 2π]:
ezpolar('1+cos(t)')
90
2
120
60
1.5
150
30
1
0.5
180
0
330
210
240
300
270
r = 1+cos(t)
See Also
2-616
ezplot, ezplot3, plot, plot3, polar
ezpolar
“Function Plots” for related functions
2-617
ezsurf
Purpose
2ezsurf
Easy to use 3-D colored surface plotter
Syntax
ezsurf(f)
ezsurf(f,domain)
ezsurf(x,y,z)
ezsurf(x,y,z,[smin,smax,tmin,tmax]) or ezsurf(x,y,z,[min,max])
ezsurf(...,n)
ezsurf(...,'circ')
Description
ezsurf(f) creates a graph of f(x,y), where f is a string that represents a
mathematical function of two variables, such as x and y.
The function f is plotted over the default domain: -2π < x < 2π, -2π < y < 2π.
MATLAB chooses the computational grid according to the amount of variation
that occurs; if the function f is not defined (singular) for points on the grid, then
these points are not plotted.
ezsurf(f,domain) plots f over the specified domain. domain can be either a
4-by-1 vector [xmin, xmax, ymin, ymax] or a 2-by-1 vector [min, max] (where,
min < x < max, min < y < max).
If f is a function of the variables u and v (rather than x and y), then the domain
endpoints umin, umax, vmin, and vmax are sorted alphabetically. Thus,
ezsurf('u^2 - v^3',[0,1],[3,6]) plots u2 - v3 over 0 < u < 1, 3 < v < 6.
ezsurf(x,y,z) plots the parametric surface x = x(s,t), y = y(s,t), and z = z(s,t)
over the square: -2π < s < 2π, -2π < t < 2π.
ezsurf(x,y,z,[smin,smax,tmin,tmax]) or ezsurf(x,y,z,[min,max]) plots
the parametric surface using the specified domain.
ezsurf(...,n) plots f over the default domain using an n-by-n grid. The
default value for n is 60.
ezsurf(...,'circ') plots f over a disk centered on the domain.
Remarks
Array multiplication, division, and exponentiation are always implied in the
expression you pass to ezsurf. For example, the MATLAB syntax for a surface
plot of the expression,
sqrt(x.^2 + y.^2);
2-618
ezsurf
is written as:
ezsurf('sqrt(x^2 + y^2)')
That is, x^2 is interpreted as x.^2 in the string you pass to ezsurf.
Examples
ezsurf does not graph points where the mathematical function is not defined
(these data points are set to NaNs, which MATLAB does not plot). This example
illustrates this filtering of singularities/discontinuous points by graphing the
function,
f ( x, y) = real ( atan ( x + iy ) )
over the default domain -2π < x < 2π, -2π < y < 2π:
ezsurf('real(atan(x+i*y))')
real(atan(x+i y))
2
1
0
−1
−2
5
5
0
y
0
−5
−5
x
Using surf to plot the same data produces a graph without filtering of
discontinuities (as well as requiring more steps):
[x,y] = meshgrid(linspace(-2*pi,2*pi,60));
z = real(atan(x+i.*y));
2-619
ezsurf
surf(x,y,z)
2
1
0
−1
−2
10
5
10
5
0
0
−5
−5
−10
−10
Note also that ezsurf creates graphs that have axis labels, a title, and extend
to the axis limits.
See Also
ezmesh, ezsurfc, surf
“Function Plots” for related functions
2-620
ezsurfc
Purpose
2ezsurfc
Easy to use combination surface/contour plotter
Syntax
ezsurfc(f)
ezsurfc(f,domain)
ezsurfc(x,y,z)
ezsurfc(x,y,z,[smin,smax,tmin,tmax]) or ezsurfc(x,y,z,[min,max])
ezsurfc(...,n)
ezsurfc(...,'circ')
Description
ezsurfc(f) creates a graph of f(x,y), where f is a string that represents a
mathematical function of two variables, such as x and y.
The function f is plotted over the default domain: -2π < x < 2π, -2π < y < 2π.
MATLAB chooses the computational grid according to the amount of variation
that occurs; if the function f is not defined (singular) for points on the grid, then
these points are not plotted.
ezsurfc(f,domain) plots f over the specified domain. domain can be either a
4-by-1 vector [xmin, xmax, ymin, ymax] or a 2-by-1 vector [min, max] (where,
min < x < max, min < y < max).
If f is a function of the variables u and v (rather than x and y), then the domain
endpoints umin, umax, vmin, and vmax are sorted alphabetically. Thus,
ezsurfc('u^2 - v^3',[0,1],[3,6]) plots u2 - v3 over 0 < u < 1, 3 < v < 6.
ezsurfc(x,y,z) plots the parametric surface x = x(s,t), y = y(s,t), and z = z(s,t)
over the square: -2π < s < 2π, -2π < t < 2π.
ezsurfc(x,y,z,[smin,smax,tmin,tmax]) or ezsurfc(x,y,z,[min,max])
plots the parametric surface using the specified domain.
ezsurfc(...,n) plots f over the default domain using an n-by-n grid. The
default value for n is 60.
ezsurfc(...,'circ') plots f over a disk centered on the domain.
Remarks
Array multiplication, division, and exponentiation are always implied in the
expression you pass to ezsurfc. For example, the MATLAB syntax for a
surface/contour plot of the experssion,
sqrt(x.^2 + y.^2);
2-621
ezsurfc
is written as:
ezsurfc('sqrt(x^2 + y^2)')
That is, x^2 is interpreted as x.^2 in the string you pass to ezsurfc.
Examples
Create a surface/contour plot of the expression,
y
f ( x, y ) = ---------------------------2
2
1+x + y
over the domain -5 < x < 5, -2*pi < y < 2*pi, with a computational grid of size
35-by-35:
ezsurfc('y/(1 + x^2 + y^2)',[−5,5,−2*pi,2*pi],35)
Use the mouse to rotate the axes to better observe the contour lines (this
picture uses a view of azimuth = -65.5 and elevation = 26)
y/(1 + x2 + y2)
0.5
0
5
−0.5
0
5
0
−5
y
See Also
2-622
ezmesh, ezmeshc, ezsurf, surfc
−5
x
ezsurfc
“Function Plots” for related functions
2-623
ezsurfc
2-624
Index
Symbols
! 2-24
- 2-11
% 2-24
& 2-20, 2-22
&& 2-22
' 2-11, 2-24
( ) 2-24
* 2-11
+ 2-11
, 2-24
. 2-24
... 2-24
/ 2-11
: 2-27
< 2-19
= 2-24
== 2-19
> 2-19
\ 2-11
^ 2-11
{} 2-24
| 2-20, 2-22
|| 2-22
~ 2-20, 2-22
~= 2-19
A
abs 2-29
absolute value 2-29
accuracy
of linear equation solution 2-357
of matrix inversion 2-357
relative floating-point 2-573
acos 2-30
acosh 2-32
acot 2-34
acoth 2-36
acsc 2-38
acsch 2-40
actxcontrol 2-42
actxserver 2-46
addframe
AVI files 2-48
addition (arithmetic operator) 2-11
addpath 2-50
addproperty 2-52
addressing selected array elements 2-27
adjacency graph 2-535
airy 2-53
Airy functions
relationship to modified Bessel functions 2-53
ALim, Axes property 2-117
all 2-56
AmbientLightColor, Axes property 2-117
and (M-file function equivalent for &) 2-21
AND, logical
bit-wise 2-190
angle 2-64
ans 2-65
any 2-66
arccosecant 2-38
arccosine 2-30
arccotangent 2-34
arcsecant 2-70
arcsine 2-74
arctangent 2-80
four-quadrant 2-82
area 2-68
arithmetic operations, matrix and array
distinguished 2-11
arithmetic operators
I-1
Index
reference 2-11
array
addressing selected elements of 2-27
displaying 2-525
left division (arithmetic operator) 2-12
multiplication (arithmetic operator) 2-11
power (arithmetic operator) 2-12
right division (arithmetic operator) 2-12
shift circularly 2-297
transpose (arithmetic operator) 2-12
arrays
maximum size of 2-356
arrowhead matrix 2-348
ASCII
delimited files
writing 2-534
ASCII data
printable characters (list of) 2-278
reading 2-533
auwrite 2-98
asec 2-70
bar3 2-151
asech 2-72
bar3h 2-151
asin 2-74
barh 2-147
asinh 2-76
assignin 2-78
base to decimal conversion 2-155
base two operations
conversion from decimal to binary 2-481
atan 2-80
base2dec 2-155
atan2 2-82
beep 2-156
Bessel functions
first kind 2-167
modified, first kind 2-161
modified, second kind 2-164
second kind 2-170
Bessel functions, modified
relationship to Airy functions 2-53
Bessel’s equation
(defined) 2-167
modified (defined) 2-161
aspect ratio of axes 2-428
atanh 2-84
.au files
reading 2-97
writing 2-98
audio
saving in AVI format 2-99
audio devices 2-86
audiodevinfo 2-86
audioplayer 2-88
audiorecorder 2-92
I-2
avi 2-99
avifile 2-99
aviinfo 2-102
aviread 2-104
Axes
creating 2-105
defining default properties 2-109
fixed-width font 2-126
property descriptions 2-117
axes
setting and querying data aspect ratio 2-428
axes 2-105
axis 2-138
B
balance 2-144
bar 2-147
Index
besseli 2-161
Box, Axes property 2-118
besselj 2-167
besselk 2-164
braces, curly (special characters) 2-24
brackets (special characters) 2-24
bessely 2-170
break 2-201
beta 2-173
betainc 2-175
breakpoints
listing 2-451
removing 2-442
resuming execution from 2-444
setting in M-files 2-453
brighten 2-202
betaln 2-176
builtin 2-204
bicg 2-177
BusyAction
beta function
(defined) 2-173
incomplete (defined) 2-175
natural logarithm 2-176
Axes property 2-118
bicgstab 2-184
BiConjugate Gradients method 2-177
BiConjugate Gradients Stabilized method 2-184
ButtonDownFcn
bin2dec 2-189
Axes property 2-118
bvp4c 2-205
binary to decimal conversion 2-189
bvpget 2-212
bitand 2-190
bvpinit 2-213
bitcmp 2-191
bvpset 2-215
bitget 2-192
bvpval 2-218
bitmax 2-193
bitor 2-194
bitset 2-195
C
bitshift 2-196
calendar 2-219
bit-wise operations
AND 2-190
get 2-192
OR 2-194
set bit 2-195
shift 2-196
XOR 2-197
camdolly 2-220
camera
dollying position 2-220
moving camera and target postions 2-220
placing a light at 2-222
positioning to view objects 2-224
rotating around camera target 2-226, 2-228
rotating around viewing axis 2-232
setting and querying position 2-229
setting and querying projection type 2-231
setting and querying target 2-233
setting and querying up vector 2-235
setting and querying view angle 2-237
bitxor 2-197
blanks
removing trailing 2-479
blanks 2-198
blkdiag 2-199
box 2-200
I-3
Index
CameraPosition, Axes property 2-119
cell2mat 2-266
CameraTarget, Axes property 2-119
cell2struct 2-268
CameraTargetMode, Axes property 2-119
celldisp 2-269
CameraUpVector, Axes property 2-119
cellfun 2-270
CameraUpVectorMode, Axes property 2-119
cellplot 2-272
CameraViewAngle, Axes property 2-120
cgs 2-274
CameraViewAngleMode, Axes property 2-120
char 2-278
camlight 2-222
checkin 2-280
camlookat 2-224
camproj 2-231
examples 2-281
options 2-280
checkout 2-282
examples 2-283
options 2-282
camroll 2-232
Children
camorbit 2-226
campan 2-228
campos 2-229
camtarget 2-233
Axes property 2-121
camup 2-235
chol 2-285
camva 2-237
capture 2-240
Cholesky factorization 2-285
(as algorithm for solving linear equations) 2-15
preordering for 2-348
cart2pol 2-241
cholinc 2-287
cart2sph 2-242
cholupdate 2-294
Cartesian coordinates 2-241, 2-242
circshift 2-297
case 2-243
cla 2-298
cat 2-244
clabel 2-299
catch 2-245
class 2-301
caxis 2-246
clc 2-303, 2-309
cd 2-250
clear 2-304
cdf2rdf 2-251
clear
cdfepoch 2-253
serial port I/O 2-308
clearing
Command Window 2-303
items from workspace 2-304
Java import list 2-305
clf 2-309
CLim, Axes property 2-121
CLimMode, Axes property 2-121
camzoom 2-239
cdfinfo 2-254
cdfread 2-258
cdfwrite 2-260
ceil 2-263
cell 2-264
cell array
creating 2-264
I-4
structure of, displaying 2-272
CameraPositionMode, Axes property 2-119
Index
AVI files 2-314
closest point search 2-546
cmapeditor 2-330
cmopts 2-316
complementary error function
(defined) 2-574
scaled (defined) 2-574
complete elliptic integral
(defined) 2-564
modulus of 2-562, 2-564
complex
exponential (defined) 2-597
phase angle 2-64
colamd 2-317
complex 2-354
colmmd 2-319
complex conjugate 2-365
sorting pairs of 2-407
complex data
creating 2-354
complex numbers, magnitude 2-29
computer 2-356
computer MATLAB is running on 2-356
concatenating arrays 2-244
clipboard 2-310
Clipping
Axes property 2-121
clock 2-311
close 2-312
Color
Axes property 2-122
colorbar 2-322
colormap
editor 2-330
colormap 2-326
ColorOrder, Axes property 2-122
ColorSpec 2-346
cond 2-357
colperm 2-348
condeig 2-358
COM
object methods
condest 2-359
actxserver 2-46
condition number of matrix 2-357
improving 2-144
coneplot 2-360
addproperty 2-52
conj 2-365
delete 2-499
conjugate, complex 2-365
sorting pairs of 2-407
continuation (..., special characters) 2-25
continue 2-366
contour
and mesh plot 2-610
filled plot 2-605
functions 2-602
of mathematical expression 2-602
with surface plot 2-621
contour 2-367
contour3 2-371
actxcontrol 2-42
deleteproperty 2-503
eventlisteners 2-590
events 2-592
comet 2-349
comet3 2-350
comma (special characters) 2-26
Command Window
clearing 2-303
compan 2-351
companion matrix 2-351
compass 2-352
I-5
Index
contourc 2-373
contourf 2-375
contours
in slice planes 2-377
contourslice 2-377
contrast 2-380
conv 2-381
conv2 2-382
conversion
base to decimal 2-155
binary to decimal 2-189
Cartesian to cylindrical 2-241
Cartesian to polar 2-241
complex diagonal to real block diagonal 2-251
decimal number to base 2-477, 2-480
decimal to binary 2-481
decimal to hexadecimal 2-482
string matrix to cell array 2-273
vector to character string 2-278
convex hulls
multidimensional vizualization 2-388
two-dimensional vizualization 2-386
cosh 2-400
cosine 2-398
hyperbolic 2-400
inverse 2-30
inverse hyperbolic 2-32
cot 2-402
cotangent 2-402
hyperbolic 2-404
inverse 2-34
inverse hyperbolic 2-36
coth 2-404
cov 2-406
cplxpair 2-407
cputime 2-408
CreateFcn
Axes property 2-122
cross 2-409
cross product 2-409
convhull 2-386
csc 2-410
convhulln 2-388
csch 2-412
convn 2-390
csvread 2-414
convolution 2-381
inverse See deconvolution
two-dimensional 2-382
coordinates
Cartesian 2-241, 2-242
cylindrical 2-241, 2-242
polar 2-241, 2-242
coordinates.See also conversion
copyfile 2-391
copyobj 2-393
csvwrite 2-416
corrcoef 2-395
cos 2-398
I-6
cosecant
hyperbolic 2-412
inverse 2-38
inverse hyperbolic 2-40
ctranspose (M-file function equivalent for ') 2-13
cumprod 2-417
cumsum 2-418
cumtrapz 2-419
cumulative
product 2-417
sum 2-418
curl 2-421
curly braces (special characters) 2-24
current directory
changing 2-250
Index
CurrentPoint
ddeget 2-466
Axes property 2-123
customverctrl 2-424
cylinder 2-425
cylindrical coordinates 2-241, 2-242
ddeinit 2-467
ddepoke 2-468
ddereq 2-470
ddeset 2-472
ddeterm 2-475
ddeunadv 2-476
D
deal 2-477
daspect 2-428
deblank 2-479
data aspect ratio of axes 2-428
data types
complex 2-354
DataAspectRatio, Axes property 2-123
DataAspectRatioMode, Axes property 2-125
datenum 2-432
debugging
changing workspace context 2-445
changing workspace to calling M-file 2-458
displaying function call stack 2-450
MEX-files on UNIX 2-448
quitting debug mode 2-449
removing breakpoints 2-442
resuming execution from breakpoint 2-452
setting breakpoints in 2-453
stepping through lines 2-452
dec2base 2-477, 2-480
datestr 2-434
dec2bin 2-481
datevec 2-440
dec2hex 2-482
dbclear 2-442
dbstack 2-450
decimal number to base conversion 2-477, 2-480
decimal point (.)
(special characters) 2-25
to distinguish matrix and array operations
2-11
decomposition
Dulmage-Mendelsohn 2-535
dbstatus 2-451
deconv 2-483
dbstep 2-452
dbtype 2-457
deconvolution 2-483
default tolerance 2-573
del operator 2-484
dbup 2-458
del2 2-484
dde23 2-459
delaunay 2-487
ddeadv 2-463
Delaunay tessellation
3-dimensional vizualization 2-492
date 2-431
date and time functions 2-572
date string
format of 2-434
date vector 2-440
dbcont 2-444
dbdown 2-445
dblquad 2-446
dbmex 2-448
dbquit 2-449
dbstop 2-453
ddeexec 2-465
I-7
Index
multidimensional vizualization 2-495
Delaunay triangulation
vizualization 2-487
delaunay3 2-492
delaunayn 2-495
delete 2-498, 2-499
delete
serial port I/O 2-501
timer object 2-502
DeleteFcn
Axes property 2-125
deleteproperty 2-503
deleting
files 2-498
items from workspace 2-304
delimiters in ASCII files 2-533, 2-534
demo 2-504
depdir 2-507
depfun 2-508
derivative
approximate 2-521
det 2-512
determinant of a matrix 2-512
detrend 2-513
deval 2-515
diag 2-517
diagonal 2-517
main 2-517
dialog 2-519
dialog box
error 2-580
diary 2-520
diff 2-521
differences
between adjacent array elements 2-521
differential equation solvers
ODE boundary value problems 2-205
I-8
adjusting parameters 2-215
extracting properties 2-212
extracting properties of 2-583, 2-584
forming initial guess 2-213
dir 2-523
directories
adding to search path 2-50
checking existence of 2-594
copying 2-391
listing contents of 2-523
See also directory, search path
directory
See also directories
directory, changing 2-250
discontinuities, plotting functions with 2-619
disp 2-525
disp
serial port I/O 2-526
timer object 2-527
display 2-529
distribution
Gaussian 2-574
division
array, left (arithmetic operator) 2-12
array, right (arithmetic operator) 2-12
matrix, left (arithmetic operator) 2-12
matrix, right (arithmetic operator) 2-11
of polynomials 2-483
dlmread 2-533
dlmwrite 2-534
dmperm 2-535
docroot 2-538
documentation
location of files for UNIX 2-537
documentation location 2-538
dolly camera 2-220
dos 2-539
Index
dot 2-541
dot product 2-409, 2-541
double 2-542
double integral
numerical evaluation 2-446
dragrect 2-543
DrawMode, Axes property 2-125
drawnow 2-544
elliptic functions, Jacobian
(defined) 2-562
elliptic integral
complete (defined) 2-564
modulus of 2-562, 2-564
else 2-567
elseif 2-568
end 2-570
dsearch 2-545
end of line, indicating 2-26
dsearchn 2-546
eomday 2-572
Dulmage-Mendelsohn decomposition 2-535
eps 2-573
E
equal sign (special characters) 2-25
equations, linear
accuracy of solution 2-357
echo 2-547
erf 2-574
edge finding, Sobel technique 2-383
editing
M-files 2-548
erfc 2-574
eig 2-550
erfinv 2-574
eigensystem
transforming 2-251
eigenvalue
accuracy of 2-550
complex 2-251
of companion matrix 2-351
problem 2-551
problem, generalized 2-551
repeated 2-552
eigenvalues
effect of roundoff error 2-144
improving accuracy 2-144
eigenvector
left 2-551
right 2-551
error 2-576
eigs 2-554
eventlisteners 2-590
ellipj 2-562
events 2-592
ellipke 2-564
examples
erfcinv 2-574
erfcx 2-574
error function
(defined) 2-574
complementary 2-574
scaled complementary 2-574
error message
displaying 2-576
errorbar 2-578
errordlg 2-580
etime 2-582
etree 2-583
etreeplot 2-584
eval 2-585
evalc 2-587
evalin 2-588
I-9
Index
contouring mathematical expressions 2-602
mesh plot of mathematical function 2-609
mesh/contour plot 2-611
plotting filled contours 2-605
plotting function of two variables 2-613
plotting parametric curves 2-614
polar plot of function 2-616
surface plot of mathematical function 2-619
surface/contour plot 2-622
exclamation point (special characters) 2-26
execution
resuming from breakpoint 2-444
exist 2-594
exit 2-596
exp 2-597
expint 2-598
expm 2-599
exponential 2-597
complex (defined) 2-597
integral 2-598
matrix 2-599
exponentiation
array (arithmetic operator) 2-12
matrix (arithmetic operator) 2-12
eye 2-601
ezcontour 2-602
ezcontourf 2-605
ezmesh 2-608
ezmeshc 2-610
ezplot 2-612
ezplot3 2-614
ezpolar 2-616
ezsurf 2-618
ezsurfc 2-621
F
factorization, Cholesky 2-285
(as algorithm for solving linear equations) 2-15
preordering for 2-348
Figures
updating from M-file 2-544
files
ASCII delimited
reading 2-533
writing 2-534
checking existence of 2-594
copying 2-391
deleting 2-498
listing
names in a directory 2-523
sound
reading 2-97
writing 2-98, 2-99
filter
two-dimensional 2-382
fixed-width font
axes 2-126
flint See floating-point, integer
floating-point
integer 2-191, 2-195
integer, maximum 2-193
numbers, interval between 2-573
flow control
break 2-201
case 2-243
end 2-570
error 2-576
font
fixed-width, axes 2-126
FontAngle
Axes property 2-125
FontName
I-10
Index
Axes property 2-126
FontSize
Axes property 2-126
FontUnits
Help browser
accessing from doc 2-536
help files 2-538
HitTest
Axes property 2-126
Axes property 2-128
FontWeight
horzcat (M-file function equivalent for [,]) 2-26
Axes property 2-127
Fourier transform
convolution theorem and 2-381
functions
call stack for 2-450
checking existence of 2-594
clearing from workspace 2-304
Householder reflections (as algorithm for solving
linear equations) 2-16
hyperbolic
cosecant 2-412
cosecant, inverse 2-40
cosine 2-400
cosine, inverse 2-32
cotangent 2-404
cotangent, inverse 2-36
secant, inverse 2-72
sine, inverse 2-76
tangent, inverse 2-84
G
Gaussian distribution function 2-574
Gaussian elimination
(as algorithm for solving linear equations)
2-16
generalized eigenvalue problem 2-551
generating a sequence of matrix names (M1
through M12) 2-585
global variables, clearing from workspace 2-304
graph
adjacency 2-535
graphics objects
Axes 2-105
graphics objects, deleting 2-498
GridLineStyle, Axes property 2-127
H
HandleVisibility
Axes property 2-127
help
files, location for UNIX 2-537
I
identity matrix 2-601
incomplete beta function
(defined) 2-175
inheritance, of objects 2-302
integer
floating-point 2-191, 2-195
floating-point, maximum 2-193
Interruptible
Axes property 2-128
inverse
cosecant 2-38
cosine 2-30
cotangent 2-34
hyperbolic cosecant 2-40
hyperbolic cosine 2-32
hyperbolic cotangent 2-36
I-11
Index
hyperbolic secant 2-72
hyperbolic sine 2-76
hyperbolic tangent 2-84
secant 2-70
sine 2-74
tangent 2-80
tangent, four-quadrant 2-82
inversion, matrix
accuracy of 2-357
J
Jacobian elliptic functions
(defined) 2-562
Java
class names 2-305
Java import list
clearing 2-305
joining arrays See concatenating arrays
L
labeling
matrix columns 2-525
Laplacian 2-484
Layer, Axes property 2-128
ldivide (M-file function equivalent for .\) 2-13
Light
positioning in camera coordinates 2-222
line numbers in M-files 2-457
linear equation systems
accuracy of solution 2-357
linear equation systems, methods for solving
Cholesky factorization 2-15
Gaussian elimination 2-16
Householder reflections 2-16
LineStyleOrder
I-12
Axes property 2-129
LineWidth
Axes property 2-129
Lobatto IIIa ODE solver 2-211
log
saving session to file 2-520
logarithm
of beta function (natural) 2-176
logical operations
AND, bit-wise 2-190
OR, bit-wise 2-194
XOR, bit-wise 2-197
logical operators 2-20, 2-22
logical tests
all 2-56
any 2-66
M
matrix
addressing selected rows and columns of 2-27
arrowhead 2-348
companion 2-351
condition number of 2-357
condition number, improving 2-144
converting to vector 2-27
defective (defined) 2-552
determinant of 2-512
diagonal of 2-517
Dulmage-Mendelsohn decomposition 2-535
exponential 2-599
identity 2-601
inversion, accuracy of 2-357
left division (arithmetic operator) 2-12
maximum size of 2-356
modal 2-550
multiplication (defined) 2-11
Index
power (arithmetic operator) 2-12
reading files into 2-533
right division (arithmetic operator) 2-11
singularity, test for 2-512
trace of 2-517
transpose (arithmetic operator) 2-12
transposing 2-25
writing to ASCII delimited file 2-534
See also array
matrix names, (M1 through M12) generating a
sequence of 2-585
matrix power See matrix, exponential
maximum matching 2-535
MDL-files
checking existence of 2-594
memory
clearing 2-304
methods
inheritance of 2-302
MEX-files
clearing from workspace 2-304
debugging on UNIX 2-448
M-file
displaying during execution 2-547
function file, echoing 2-547
script file, echoing 2-547
M-files
checking existence of 2-594
clearing from workspace 2-304
deleting 2-498
editing 2-548
line numbers, listing 2-457
setting breakpoints 2-453
MinorGridLineStyle, Axes property 2-129
minus (M-file function equivalent for -) 2-13
mldivide (M-file function equivalent for \) 2-13
modal matrix 2-550
modified Bessel functions
relationship to Airy functions 2-53
modifying for PVCS 2-316
movies
exporting in AVI format 2-99
mpower (M-file function equivalent for ^) 2-13
mrdivide (M-file function equivalent for /) 2-13
mtimes (M-file function equivalent for *) 2-13
multidimensional arrays
concatenating 2-244
multiplication
array (arithmetic operator) 2-11
matrix (defined) 2-11
of polynomials 2-381
N
NextPlot
Axes property 2-130
not (M-file function equivalent for ~) 2-21
numerical evaluation
double integral 2-446
O
object
inheritance 2-302
object classes, list of predefined 2-301
online help
location of files for UNIX 2-537
operating system command, issuing 2-26
operators
arithmetic 2-11
logical 2-20, 2-22
relational 2-19
special characters 2-24
logical OR
I-13
Index
bit-wise 2-194
or (M-file function equivalent for |) 2-21
orthographic projection, setting and querying
2-231
P
parametric curve, plotting 2-614
Parent
Axes property 2-130
parentheses (special characters) 2-25
path
adding directories to 2-50
pauses, removing 2-442
percent sign (special characters) 2-26
perfect matching 2-535
period (.), to distinguish matrix and array
operations 2-11
period (special characters) 2-25
perspective projection, setting and querying
2-231
P-files
checking existence of 2-594
phase angle, complex 2-64
platform MATLAB is running on 2-356
PlotBoxAspectRatio, Axes property 2-130
PlotBoxAspectRatioMode, Axes property 2-130
plotting
contours (a 2-602
contours (ez function) 2-602
errorbars 2-578
ez-function mesh plot 2-608
filled contours 2-605
functions with discontinuities 2-619
in polar coordinates 2-616
mathematical function 2-612
mesh contour plot 2-610
I-14
parametric curve 2-614
surfaces 2-618
velocity vectors 2-360
plus (M-file function equivalent for +) 2-13
polar coordinates
computing the angle 2-64
converting from Cartesian 2-241
plotting in 2-616
polynomial
division 2-483
multiplication 2-381
poorly conditioned eigenvalues 2-144
Position
Axes property 2-131
position of camera
dollying 2-220
position of camera, setting and querying 2-229
power
matrix See matrix exponential
power (M-file function equivalent for .^) 2-13
printing, suppressing 2-26
product
cumulative 2-417
of vectors (cross) 2-409
scalar (dot) 2-409
projection type, setting and querying 2-231
ProjectionType, Axes property 2-131
R
rdivide (M-file function equivalent for ./) 2-13
rearranging arrays
converting to vector 2-27
rearranging matrices
converting to vector 2-27
transposing 2-25
reference page
Index
accessing from doc 2-536
regularly spaced vectors, creating 2-27
relational operators 2-19
relative accuracy
floating-point 2-573
rolling camera 2-232
rotating camera 2-226
rotating camera target 2-228
round
towards infinity 2-263
roundoff error
convolution theorem and 2-381
effect on eigenvalues 2-144
S
saving
session to a file 2-520
scalar product (of vectors) 2-409
scaled complementary error function (defined)
2-574
search path
adding directories to 2-50
secant
inverse 2-70
inverse hyperbolic 2-72
Selected
Axes property 2-131
SelectionHighlight
Axes property 2-132
semicolon (special characters) 2-26
sequence of matrix names (M1 through M12)
generating 2-585
session
saving 2-520
shifting array
circular 2-297
sine
inverse 2-74
inverse hyperbolic 2-76
single quote (special characters) 2-25
slice planes, contouring 2-377
sorting
complex conjugate pairs 2-407
sound
files
reading 2-97
writing 2-98
source control systems
checking in files 2-280
checking out files 2-282
viewing current system 2-316
sparse matrix
minimum degree ordering of 2-319
permuting columns of 2-348
spreadsheets
reading into a matrix 2-533
writing matrices into 2-534
stack, displaying 2-450
str2cell 2-273
stretch-to-fill 2-106
string
converting from vector to 2-278
string matrix to cell array conversion 2-273
subsref (M-file function equivalent for
A(i,j,k...)) 2-26
subtraction (arithmetic operator) 2-11
sum
cumulative 2-418
Surface
and contour plotter 2-621
plotting mathematical functions 2-618
I-15
Index
T
uminus (M-file function equivalent for unary –)
2-13
Tag
Axes property 2-132
tangent
four-quadrant, inverse 2-82
inverse 2-80
inverse hyperbolic 2-84
target, of camera 2-233
test, logical See logical tests and detecting
TickDir, Axes property 2-132
TickDirMode, Axes property 2-132
TickLength, Axes property 2-132
time
CPU 2-408
required to execute commands 2-582
time and date functions 2-572
times (M-file function equivalent for .*) 2-13
Title, Axes property 2-133
tolerance, default 2-573
trace of a matrix 2-517
trailing blanks
removing 2-479
transformation
See also conversion
transpose
array (arithmetic operator) 2-12
matrix (arithmetic operator) 2-12
transpose (M-file function equivalent for .')
2-13
truth tables (for logical operations) 2-20
Type
Axes property 2-133
Units
Axes property 2-133
up vector, of camera 2-235
updating figure during M-file execution 2-544
uplus (M-file function equivalent for unary +) 2-13
UserData
Axes property 2-134
V
variables
checking existence of 2-594
clearing from workspace 2-304
vector
dot product 2-541
product (cross) 2-409
vector field, plotting 2-360
vectorizing ODE function (BVP) 2-216
vectors, creating
regularly spaced 2-27
velocity vectors, plotting 2-360
vertcat (M-file function equivalent for [;]) 2-26
video
saving in AVI format 2-99
view 2-224
view angle, of camera 2-237
View, Axes property (obsolete) 2-134
viewing
a group of object 2-224
a specific object in a scene 2-224
Visible
U
UIContextMenu
Axes property 2-133
I-16
Axes property 2-134
visualizing
cell array structure 2-272
volumes
Index
contouring slice planes 2-377
YScale, Axes property 2-136
YTick, Axes property 2-136
YTickLabel, Axes property 2-136
W
YTickLabelMode, Axes property 2-137
workspace
changing context while debugging 2-445,
2-458
clearing items from 2-304
YTickMode, Axes property 2-137
Z
ZColor, Axes property 2-134
ZDir, Axes property 2-134
X
ZGrid, Axes property 2-135
XAxisLocation, Axes property 2-134
ZLim, Axes property 2-135
XColor, Axes property 2-134
ZLimMode, Axes property 2-136
XDir, Axes property 2-134
ZMinorGrid, Axes property 2-136
XGrid, Axes property 2-135
ZScale, Axes property 2-136
XLabel, Axes property 2-135
ZTick, Axes property 2-136
XLim, Axes property 2-135
ZTickLabel, Axes property 2-136
XLimMode, Axes property 2-136
ZTickLabelMode, Axes property 2-137
XMinorGrid, Axes property 2-136
ZTickMode, Axes property 2-137
logical XOR
bit-wise 2-197
XScale, Axes property 2-136
XTick, Axes property 2-136
XTickLabel, Axes property 2-136
XTickLabelMode, Axes property 2-137
XTickMode, Axes property 2-137
Y
YAxisLocation, Axes property 2-134
YColor, Axes property 2-134
YDir, Axes property 2-134
YGrid, Axes property 2-135
YLabel, Axes property 2-135
YLim, Axes property 2-135
YLimMode, Axes property 2-136
YMinorGrid, Axes property 2-136
I-17

* Your assessment is very important for improving the work of artificial intelligence, which forms the content of this project