7

Functions
7 Functions

abs
Symbolic absolute value (complex modulus or magnitude)

Syntax
abs(z)

Description
abs(z) returns the absolute value (or complex modulus) of z. Because symbolic variables are
assumed to be complex by default, abs returns the complex modulus (magnitude) by default. If z is
an array, abs acts element-wise on each element of z.

Examples

Compute Absolute Values of Symbolic Numbers

[abs(sym(1/2)), abs(sym(0)), abs(sym(pi) - 4)]

ans =
[ 1/2, 0, 4 - pi]

Compute Absolute Value of Complex Numbers

Compute abs(x)^2 and simplify the result. Because symbolic variables are assumed to be complex
by default, the result does not simplify to x^2.

syms x
simplify(abs(x)^2)

ans =
abs(x)^2

Assume x is real, and repeat the calculation. Now, the result is simplified to x^2.

assume(x,'real')
simplify(abs(x)^2)

ans =
x^2

Remove assumptions on x for further calculations. For details, see “Use Assumptions on Symbolic
Variables” on page 1-41.

assume(x,'clear')

7-2
 abs

Absolute Values of Elements of Array

Compute the absolute values of each element of matrix A.

A = sym([1/2+i -25;
i pi/2]);
abs(A)

ans =
[ 5^(1/2)/2, 25]
[ 1, pi/2]

Effect of Assumptions on Absolute Value

Compute the absolute value of this expression assuming that the value of x is negative.

syms x
assume(x < 0)
abs(5*x^3)

ans =
-5*x^3

For further computations, clear the assumption on x by recreating it using syms:

syms x

Input Arguments
z — Input
number | vector | matrix | multidimensional array | symbolic number | symbolic array | symbolic
function | symbolic expression

Input, specified as a number, vector, matrix, or array, or a symbolic number, vector, matrix, or array,
variable, function, or expression.

More About
Complex Modulus

The absolute value of a complex number z = x + y*i is the value z = x2 + y2. Here, x and y are real
numbers. The absolute value of a complex number is also called a complex modulus.

Tips
• Calling abs for a number that is not a symbolic object invokes the MATLAB abs function.

Version History
Introduced before R2006a

7-3
7 Functions

See Also
angle | imag | real | sign | signIm

7-4
 acos

acos
Symbolic inverse cosine function

Syntax
acos(X)

Description
acos(X) returns the inverse cosine function (arccosine function) of X. All angles are in radians.

• For real values of X in the interval [-1,1], acos(x) returns the values in the interval [0,pi].
• For real values of X outside the interval [-1,1] and for complex values of X, acos(X) returns
complex values with the real parts in the interval [0,pi].

Examples
Inverse Cosine Function for Numeric and Symbolic Arguments

Depending on its arguments, acos returns floating-point or exact symbolic results.

Compute the inverse cosine function for these numbers. Because these numbers are not symbolic
objects, acos returns floating-point results.

A = acos([-1, -1/3, -1/2, 1/4, 1/2, sqrt(3)/2, 1])

A =
3.1416 1.9106 2.0944 1.3181 1.0472 0.5236 0

Compute the inverse cosine function for the numbers converted to symbolic objects. For many
symbolic (exact) numbers, acos returns unresolved symbolic calls.

symA = acos(sym([-1, -1/3, -1/2, 1/4, 1/2, sqrt(3)/2, 1]))

symA =
[ pi, pi - acos(1/3), (2*pi)/3, acos(1/4), pi/3, pi/6, 0]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =
[ 3.1415926535897932384626433832795,...
1.9106332362490185563277142050315,...
2.0943951023931954923084289221863,...
1.318116071652817965745664254646,...
1.0471975511965977461542144610932,...
0.52359877559829887307710723054658,...
0]

Plot Inverse Cosine Function

7-5
7 Functions

Plot the inverse cosine function on the interval from -1 to 1.

syms x
fplot(acos(x),[-1 1])
grid on

Handle Expressions Containing Inverse Cosine Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing acos.

Find the first and second derivatives of the inverse cosine function:
syms x
diff(acos(x), x)
diff(acos(x), x, x)

ans =
-1/(1 - x^2)^(1/2)

ans =
-x/(1 - x^2)^(3/2)

Find the indefinite integral of the inverse cosine function:

int(acos(x), x)

ans =
x*acos(x) - (1 - x^2)^(1/2)

7-6
 acos

Find the Taylor series expansion of acos(x):

taylor(acos(x), x)

ans =
- (3*x^5)/40 - x^3/6 - x + pi/2

Rewrite the inverse cosine function in terms of the natural logarithm:

rewrite(acos(x), 'log')

ans =
-log(x + (1 - x^2)^(1/2)*1i)*1i

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
asin | atan | acsc | asec | acot | sin | cos | tan | csc | sec | cot

7-7
7 Functions

acosh
Symbolic inverse hyperbolic cosine function

Syntax
acosh(X)

Description
acosh(X) returns the inverse hyperbolic cosine function of X.

Examples
Inverse Hyperbolic Cosine Function for Numeric and Symbolic Arguments

Depending on its arguments, acosh returns floating-point or exact symbolic results.

Compute the inverse hyperbolic cosine function for these numbers. Because these numbers are not
symbolic objects, acosh returns floating-point results.

A = acosh([-1, 0, 1/6, 1/2, 1, 2])

A =
0.0000 + 3.1416i 0.0000 + 1.5708i 0.0000 + 1.4033i...
0.0000 + 1.0472i 0.0000 + 0.0000i 1.3170 + 0.0000i

Compute the inverse hyperbolic cosine function for the numbers converted to symbolic objects. For
many symbolic (exact) numbers, acosh returns unresolved symbolic calls.

symA = acosh(sym([-1, 0, 1/6, 1/2, 1, 2]))

symA =
[ pi*1i, (pi*1i)/2, acosh(1/6), (pi*1i)/3, 0, acosh(2)]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =

[ 3.1415926535897932384626433832795i,...
1.5707963267948966192313216916398i,...
1.4033482475752072886780470855961i,...
1.0471975511965977461542144610932i,...
0,...
1.316957896924816708625046347308]

Plot Inverse Hyperbolic Cosine Function

Plot the inverse hyperbolic cosine function on the interval from 1 to 10.

7-8
 acosh

syms x
fplot(acosh(x),[1 10])
grid on

Handle Expressions Containing Inverse Hyperbolic Cosine Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing
acosh.

Find the first and second derivatives of the inverse hyperbolic cosine function. Simplify the second
derivative by using simplify.

syms x
diff(acosh(x), x)
simplify(diff(acosh(x), x, x))

ans =
1/((x - 1)^(1/2)*(x + 1)^(1/2))

ans =
-x/((x - 1)^(3/2)*(x + 1)^(3/2))

Find the indefinite integral of the inverse hyperbolic cosine function. Simplify the result by using
simplify.

int(acosh(x), x)

7-9
7 Functions

ans =
x*acosh(x) - (x - 1)^(1/2)*(x + 1)^(1/2)

Find the Taylor series expansion of acosh(x) for x > 1:

assume(x > 1)
taylor(acosh(x), x)

ans =
(x^5*3i)/40 + (x^3*1i)/6 + x*1i - (pi*1i)/2

For further computations, clear the assumption on x by recreating it using syms:

syms x

Rewrite the inverse hyperbolic cosine function in terms of the natural logarithm:

rewrite(acosh(x), 'log')

ans =
log(x + (x - 1)^(1/2)*(x + 1)^(1/2))

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
asinh | atanh | acsch | asech | acoth | sinh | cosh | tanh | csch | sech | coth

7-10
 acot

acot
Symbolic inverse cotangent function

Syntax
acot(X)

Description
acot(X) returns the inverse cotangent function (arccotangent function) of X. All angles are in
radians.

• For real values of X, acot(X) returns values in the interval [-pi/2,pi/2].

• For complex values of X, acot(X) returns complex values with the real parts in the interval [-
pi/2,pi/2].

Examples
Inverse Cotangent Function for Numeric and Symbolic Arguments

Depending on its arguments, acot returns floating-point or exact symbolic results.

Compute the inverse cotangent function for these numbers. Because these numbers are not symbolic
objects, acot returns floating-point results.

A = acot([-1, -1/3, -1/sqrt(3), 1/2, 1, sqrt(3)])

A =
-0.7854 -1.2490 -1.0472 1.1071 0.7854 0.5236

Compute the inverse cotangent function for the numbers converted to symbolic objects. For many
symbolic (exact) numbers, acot returns unresolved symbolic calls.

symA = acot(sym([-1, -1/3, -1/sqrt(3), 1/2, 1, sqrt(3)]))

symA =
[ -pi/4, -acot(1/3), -pi/3, acot(1/2), pi/4, pi/6]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =
[ -0.78539816339744830961566084581988,...
-1.2490457723982544258299170772811,...
-1.0471975511965977461542144610932,...
1.1071487177940905030170654601785,...
0.78539816339744830961566084581988,...
0.52359877559829887307710723054658]

Plot Inverse Cotangent Function

7-11
7 Functions

Plot the inverse cotangent function on the interval from -10 to 10.
syms x
fplot(acot(x),[-10 10])
grid on

Handle Expressions Containing Inverse Cotangent Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing acot.

Find the first and second derivatives of the inverse cotangent function:
syms x
diff(acot(x), x)
diff(acot(x), x, x)

ans =
-1/(x^2 + 1)

ans =
(2*x)/(x^2 + 1)^2

Find the indefinite integral of the inverse cotangent function:

int(acot(x), x)

ans =
log(x^2 + 1)/2 + x*acot(x)

7-12
 acot

Find the Taylor series expansion of acot(x) for x > 0:

assume(x > 0)
taylor(acot(x), x)

ans =
- x^5/5 + x^3/3 - x + pi/2

For further computations, clear the assumption on x by recreating it using syms:

syms x

Rewrite the inverse cotangent function in terms of the natural logarithm:

rewrite(acot(x), 'log')

ans =
(log(1 - 1i/x)*1i)/2 - (log(1i/x + 1)*1i)/2

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
acos | asin | atan | acsc | asec | sin | cos | tan | csc | sec | cot

7-13
7 Functions

acoth
Symbolic inverse hyperbolic cotangent function

Syntax
acoth(X)

Description
acoth(X) returns the inverse hyperbolic cotangent function of X.

Examples
Inverse Hyperbolic Cotangent Function for Numeric and Symbolic Arguments

Depending on its arguments, acoth returns floating-point or exact symbolic results.

Compute the inverse hyperbolic cotangent function for these numbers. Because these numbers are
not symbolic objects, acoth returns floating-point results.

A = acoth([-pi/2, -1, 0, 1/2, 1, pi/2])

A =
-0.7525 + 0.0000i -Inf + 0.0000i 0.0000 + 1.5708i...
0.5493 + 1.5708i Inf + 0.0000i 0.7525 + 0.0000i

Compute the inverse hyperbolic cotangent function for the numbers converted to symbolic objects.
For many symbolic (exact) numbers, acoth returns unresolved symbolic calls.

symA = acoth(sym([-pi/2, -1, 0, 1/2, 1, pi/2]))

symA =
[ -acoth(pi/2), Inf, -(pi*1i)/2, acoth(1/2), Inf, acoth(pi/2)]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =
[ -0.75246926714192715916204347800251,...
Inf,...
-1.5707963267948966192313216916398i,...
0.54930614433405484569762261846126...
- 1.5707963267948966192313216916398i,...
Inf,...
0.75246926714192715916204347800251]

Plot Inverse Hyperbolic Cotangent Function

Plot the inverse hyperbolic cotangent function on the interval from -10 to 10.

7-14
 acoth

syms x
fplot(acoth(x),[-10 10])
grid on

Handle Expressions Containing Inverse Hyperbolic Cotangent Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing
acoth.

Find the first and second derivatives of the inverse hyperbolic cotangent function:

syms x
diff(acoth(x), x)
diff(acoth(x), x, x)

ans =
-1/(x^2 - 1)

ans =
(2*x)/(x^2 - 1)^2

Find the indefinite integral of the inverse hyperbolic cotangent function:

int(acoth(x), x)

ans =
log(x^2 - 1)/2 + x*acoth(x)

7-15
7 Functions

Find the Taylor series expansion of acoth(x) for x > 0:

assume(x > 0)
taylor(acoth(x), x)

ans =
x^5/5 + x^3/3 + x - (pi*1i)/2

For further computations, clear the assumption on x by recreating it using syms:

syms x

Rewrite the inverse hyperbolic cotangent function in terms of the natural logarithm:

rewrite(acoth(x), 'log')

ans =
log(1/x + 1)/2 - log(1 - 1/x)/2

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
asinh | acosh | atanh | acsch | asech | sinh | cosh | tanh | csch | sech | coth

7-16
 acsc

acsc
Symbolic inverse cosecant function

Syntax
acsc(X)

Description
acsc(X) returns the inverse cosecant function (arccosecant function) of X. All angles are in radians.

• For real values of X in intervals [-Inf,-1] and [1,Inf], acsc returns real values in the interval
[-pi/2,pi/2].
• For real values of X in the interval [-1,1] and for complex values of X, acsc returns complex
values with the real parts in the interval [-pi/2,pi/2].

Examples
Inverse Cosecant Function for Numeric and Symbolic Arguments

Depending on its arguments, acsc returns floating-point or exact symbolic results.

Compute the inverse cosecant function for these numbers. Because these numbers are not symbolic
objects, acsc returns floating-point results.

A = acsc([-2, 0, 2/sqrt(3), 1/2, 1, 5])

A =
-0.5236 + 0.0000i 1.5708 - Infi 1.0472 + 0.0000i 1.5708...
- 1.3170i 1.5708 + 0.0000i 0.2014 + 0.0000i

Compute the inverse cosecant function for the numbers converted to symbolic objects. For many
symbolic (exact) numbers, acsc returns unresolved symbolic calls.

symA = acsc(sym([-2, 0, 2/sqrt(3), 1/2, 1, 5]))

symA =
[ -pi/6, Inf, pi/3, asin(2), pi/2, asin(1/5)]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =
[ -0.52359877559829887307710723054658,...
Inf,...
1.0471975511965977461542144610932,...
1.5707963267948966192313216916398...
- 1.3169578969248165734029498707969i,...
1.5707963267948966192313216916398,...
0.20135792079033079660099758712022]

7-17
7 Functions

Plot Inverse Cosecant Function

Plot the inverse cosecant function on the interval from -10 to 10.

syms x
fplot(acsc(x),[-10 10])
grid on

Handle Expressions Containing Inverse Cosecant Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing acsc.

Find the first and second derivatives of the inverse cosecant function:

syms x
diff(acsc(x), x)
diff(acsc(x), x, x)

ans =
-1/(x^2*(1 - 1/x^2)^(1/2))

ans =
2/(x^3*(1 - 1/x^2)^(1/2)) + 1/(x^5*(1 - 1/x^2)^(3/2))

Find the indefinite integral of the inverse cosecant function:

7-18
 acsc

int(acsc(x), x)

ans =
x*asin(1/x) + log(x + (x^2 - 1)^(1/2))*sign(x)

Find the Taylor series expansion of acsc(x) around x = Inf:

taylor(acsc(x), x, Inf)

ans =
1/x + 1/(6*x^3) + 3/(40*x^5)

Rewrite the inverse cosecant function in terms of the natural logarithm:

rewrite(acsc(x), 'log')

ans =
-log(1i/x + (1 - 1/x^2)^(1/2))*1i

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
acos | asin | atan | asec | acot | sin | cos | tan | csc | sec | cot

7-19
7 Functions

acsch
Symbolic inverse hyperbolic cosecant function

Syntax
acsch(X)

Description
acsch(X) returns the inverse hyperbolic cosecant function of X.

Examples
Inverse Hyperbolic Cosecant Function for Numeric and Symbolic Arguments

Depending on its arguments, acsch returns floating-point or exact symbolic results.

Compute the inverse hyperbolic cosecant function for these numbers. Because these numbers are not
symbolic objects, acsch returns floating-point results.

A = acsch([-2*i, 0, 2*i/sqrt(3), 1/2, i, 3])

A =
0.0000 + 0.5236i Inf + 0.0000i 0.0000 - 1.0472i...
1.4436 + 0.0000i 0.0000 - 1.5708i 0.3275 + 0.0000i

Compute the inverse hyperbolic cosecant function for the numbers converted to symbolic objects. For
many symbolic (exact) numbers, acsch returns unresolved symbolic calls.

symA = acsch(sym([-2*i, 0, 2*i/sqrt(3), 1/2, i, 3]))

symA =
[ (pi*1i)/6, Inf, -(pi*1i)/3, asinh(2), -(pi*1i)/2, asinh(1/3)]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =
[ 0.52359877559829887307710723054658i,...
Inf,...
-1.0471975511965977461542144610932i,...
1.4436354751788103424932767402731,...
-1.5707963267948966192313216916398i,...
0.32745015023725844332253525998826]

Plot Inverse Hyperbolic Cosecant Function

Plot the inverse hyperbolic cosecant function on the interval from -10 to 10.

7-20
 acsch

syms x
fplot(acsch(x),[-10 10])
grid on

Handle Expressions Containing Inverse Hyperbolic Cosecant Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing
acsch.

Find the first and second derivatives of the inverse hyperbolic cosecant function:

syms x
diff(acsch(x), x)
diff(acsch(x), x, x)

ans =
-1/(x^2*(1/x^2 + 1)^(1/2))

ans =
2/(x^3*(1/x^2 + 1)^(1/2)) - 1/(x^5*(1/x^2 + 1)^(3/2))

Find the indefinite integral of the inverse hyperbolic cosecant function:

int(acsch(x), x)

ans =
x*asinh(1/x) + asinh(x)*sign(x)

7-21
7 Functions

Find the Taylor series expansion of acsch(x) around x = Inf:

taylor(acsch(x), x, Inf)

ans =
1/x - 1/(6*x^3) + 3/(40*x^5)

Rewrite the inverse hyperbolic cosecant function in terms of the natural logarithm:

rewrite(acsch(x), 'log')

ans =
log((1/x^2 + 1)^(1/2) + 1/x)

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
asinh | acosh | atanh | asech | acoth | sinh | cosh | tanh | csch | sech | coth

7-22
 adjoint

adjoint
Classical adjoint (adjugate) of square matrix

Syntax
X = adjoint(A)

Description
X = adjoint(A) returns the “Classical Adjoint (Adjugate) Matrix” on page 7-24 X of A, such that
A*X = det(A)*eye(n) = X*A, where n is the number of rows in A.

Examples

Classical Adjoint (Adjugate) of Matrix

Find the classical adjoint of a numeric matrix.

A = magic(3);
X = adjoint(A)

X =
-53.0000 52.0000 -23.0000
22.0000 -8.0000 -38.0000
7.0000 -68.0000 37.0000

Find the classical adjoint of a symbolic matrix.

syms x y z
A = sym([x y z; 2 1 0; 1 0 2]);
X = adjoint(A)

X =
[ 2, -2*y, -z]
[ -4, 2*x - z, 2*z]
[ -1, y, x - 2*y]

Verify that det(A)*eye(3) = X*A by using isAlways.

cond = det(A)*eye(3) == X*A;

isAlways(cond)

ans =
3×3 logical array
1 1 1
1 1 1
1 1 1

7-23
7 Functions

Compute Inverse Using Classical Adjoint and Determinant

Compute the inverse of this matrix by computing its classical adjoint and determinant.
syms a b c d
A = [a b; c d];
invA = adjoint(A)/det(A)

invA =
[ d/(a*d - b*c), -b/(a*d - b*c)]
[ -c/(a*d - b*c), a/(a*d - b*c)]

Verify that invA is the inverse of A.

isAlways(invA == inv(A))

ans =
2×2 logical array
1 1
1 1

Input Arguments
A — Square matrix
matrix of symbolic scalar variables | symbolic matrix variable | symbolic function | symbolic matrix
function | symbolic expression

Square matrix, specified as a matrix of symbolic scalar variables, symbolic matrix variable, symbolic
function, symbolic matrix function, or symbolic expression.

More About
Classical Adjoint (Adjugate) Matrix

The classical adjoint, or adjugate, of a square matrix A is the square matrix X, such that the (i,j)-th
entry of X is the (j,i)-th cofactor of A.

The (j,i)-th cofactor of A is defined as follows.

i+ j
a ji′ = −1 det Ai j

Aij is the submatrix of A obtained from A by removing the i-th row and j-th column.

The classical adjoint matrix should not be confused with the adjoint matrix. The adjoint is the
conjugate transpose of a matrix while the classical adjoint is another name for the adjugate matrix or
cofactor transpose of a matrix.

Version History
Introduced in R2013a

Compute classical adjoint of symbolic matrix functions

The adjoint function accepts an input argument of type symfunmatrix.

7-24
 adjoint

Compute classical adjoint of symbolic matrix variables

The adjoint function accepts an input argument of type symmatrix.

See Also
ctranspose | det | inv | rank

7-25
7 Functions

airy
Airy function

Syntax
airy(x)
airy(0,x)
airy(1,x)
airy(2,x)
airy(3,x)

airy(n,x)

airy( ___ ,1)

Description
airy(x) returns the Airy function on page 7-31 of the first kind, Ai(x), for each element of x.

airy(0,x) is the same as airy(x).

airy(1,x) returns the derivative of Ai(x).

airy(2,x) returns the Airy function on page 7-31 of the second kind, Bi(x).

airy(3,x) returns the derivative of Bi(x).

airy(n,x) uses the values in vector n to return the corresponding Airy functions of elements of
vector x. Both n and x must have the same size.

airy( ___ ,1) returns the “Scaled Airy Functions” on page 7-31 following the syntax for the
MATLAB airy function.

Examples
Find the Airy Function of the First Kind

Find the Airy function of the first kind, Ai(x), for numeric or symbolic inputs using airy. Approximate
exact symbolic outputs using vpa.

Find the Airy function of the first kind, Ai(x), at 1.5. Because the input is double and not symbolic,
you get a double result.

airy(1.5)

ans =
0.0717

Find the Airy function of the values of vector v symbolically, by converting v to symbolic form using
sym. Because the input is symbolic, airy returns exact symbolic results. The exact symbolic results
for most symbolic inputs are unresolved function calls.

7-26
 airy

v = sym([-1 0 25.1 1+1i]);

vAiry = airy(v)

vAiry =
[ airy(0, -1), 3^(1/3)/(3*gamma(2/3)), airy(0, 251/10), airy(0, 1 + 1i)]

Numerically approximate the exact symbolic result using vpa.

vpa(vAiry)

ans =
[ 0.53556088329235211879951656563887, 0.35502805388781723926006318600418,...
4.9152763177499054787371976959487e-38,...
0.060458308371838149196532978116646 - 0.15188956587718140235494791259223i]

Find the Airy function, Ai(x), of the symbolic input x^2. For symbolic expressions, airy returns an
unresolved call.

syms x
airy(x^2)

ans =
airy(0, x^2)

Find the Airy Function of the Second Kind

Find the Airy function of the second kind, Bi(x), of the symbolic input [-3 4 1+1i x^2] by
specifying the first argument as 2. Because the input is symbolic, airy returns exact symbolic
results. The exact symbolic results for most symbolic inputs are unresolved function calls.

v = sym([-3 4 1+1i x^2]);

vAiry = airy(2, v)

vAiry =
[ airy(2, -3), airy(2, 4), airy(2, 1 + 1i), airy(2, x^2)]

Use the syntax airy(2,x) like airy(x), as described in the example “Find the Airy Function of the
First Kind” on page 7-26.

Plot Airy Functions

Plot the Airy Functions, Ai(x) and Bi(x), over the interval [-10 2] using fplot.

syms x
fplot(airy(x), [-10 2])
hold on
fplot(airy(2,x), [-10 2])
legend('Ai(x)','Bi(x)','Location','Best')
title('Airy functions Ai(x) and Bi(x)')
grid on

7-27
7 Functions

Plot the absolute value of Ai(z) over the complex plane.

syms y
z = x + 1i*y;
figure(2)
fsurf(abs(airy(z)))
title('|Ai(z)|')
a = gca;
a.ZLim = [0 10];
caxis([0 10])

7-28
 airy

Find Derivatives of Airy Functions

Find the derivative of the Airy function of the first kind, Ai′(x), at 0 by specifying the first argument of
airy as 1. Then, numerically approximate the derivative using vpa.

dAi = airy(1, sym(0))

dAi_vpa = vpa(dAi)

dAi =
-(3^(1/6)*gamma(2/3))/(2*pi)
dAi_vpa =
-0.2588194037928067984051835601892

Find the derivative of the Airy function of the second kind, Bi′(x), at x by specifying the first argument
as 3. Then, find the derivative at x = 5 by substituting for x using subs and calling vpa.

syms x
dBi = airy(3, x)
dBi_vpa = vpa(subs(dBi, x, 5))

dBi =
airy(3, x)
dBi_vpa =
1435.8190802179825186717212380046

7-29
7 Functions

Solve Airy Differential Equation for Airy Functions

Show that the Airy functions Ai(x) and Bi(x) are the solutions of the differential equation

∂2 y
− xy = 0.
∂x2

syms y(x)
dsolve(diff(y, 2) - x*y == 0)

ans =
C1*airy(0, x) + C2*airy(2, x)

Differentiate Airy Functions

Differentiate expressions containing airy.

syms x y
diff(airy(x^2))
diff(diff(airy(3, x^2 + x*y -y^2), x), y)

ans =
2*x*airy(1, x^2)

ans =
airy(2, x^2 + x*y - y^2)*(x^2 + x*y - y^2) +...
airy(2, x^2 + x*y - y^2)*(x - 2*y)*(2*x + y) +...
airy(3, x^2 + x*y - y^2)*(x - 2*y)*(2*x + y)*(x^2 + x*y - y^2)

Expand Airy Function using Taylor Series

Find the Taylor series expansion of the Airy functions, Ai(x) and Bi(x), using taylor.

aiTaylor = taylor(airy(x))
biTaylor = taylor(airy(2, x))

aiTaylor =
- (3^(1/6)*gamma(2/3)*x^4)/(24*pi) + (3^(1/3)*x^3)/(18*gamma(2/3))...
- (3^(1/6)*gamma(2/3)*x)/(2*pi) + 3^(1/3)/(3*gamma(2/3))
biTaylor =
(3^(2/3)*gamma(2/3)*x^4)/(24*pi) + (3^(5/6)*x^3)/(18*gamma(2/3))...
+ (3^(2/3)*gamma(2/3)*x)/(2*pi) + 3^(5/6)/(3*gamma(2/3))

Fourier Transform of Airy Function

Find the Fourier transform of the Airy function Ai(x) using fourier.

syms x
aiFourier = fourier(airy(x))

aiFourier =
exp((w^3*1i)/3)

Numeric Roots of Airy Function

Find a root of the Airy function Ai(x) numerically using vpasolve.

7-30
 airy

syms x
vpasolve(airy(x) == 0, x)

ans =
-226.99630507523600716771890962744

Find a root in the interval [-5 -3].

vpasolve(airy(x) == 0, x, [-5 -3])

ans =
-4.0879494441309706166369887014574

Input Arguments
x — Input
number | vector | matrix | multidimensional array | symbolic number | symbolic variable | symbolic
vector | symbolic matrix | symbolic multidimensional array | symbolic function | symbolic expression

Input, specified as a number, vector, matrix, or multidimensional array, or a symbolic number,

variable, vector, matrix, multidimensional array, function, or expression.

n — Type of Airy function

0 (default) | number | vector | matrix | multidimensional array | symbolic number | symbolic variable |
symbolic vector | symbolic matrix | symbolic multidimensional array

Type of Airy function, specified as a number, vector, matrix, or multidimensional array, or a symbolic
number, variable, vector, matrix, or multidimensional array. The values of the input must be 0, 1, 2, or
3, which specify the Airy function as follows.

n Returns
0 (default) Airy function, Ai(x), which is the same as airy(x).
1 Derivative of Airy function, Ai’(x).
2 Airy function of the second kind, Bi(x).
3 Derivative of Airy function of the second kind, Bi’(x).

More About
Airy Functions

The Airy functions Ai(x) and Bi(x) are the two linearly independent solutions of the differential
equation

∂2 y
− xy = 0.
∂x2

Ai(x) is called the Airy function of the first kind. Bi(x) is called the Airy function of the second kind.

Scaled Airy Functions

The Airy function of the first kind, Ai(x), is scaled as

2 3/2
e x Ai x .
3

7-31
7 Functions

The derivative, Ai’(x), is scaled by the same factor.

The Airy function of the second kind, Bi(x), is scaled as

2
e− Re x 3/2 Bi x .
3

The derivative, Bi’(x), is scaled by the same factor.

Tips
• When you call airy for inputs that are not symbolic objects, you call the MATLAB airy function.
• When you call airy(n, x), at least one argument must be a scalar or both arguments must be
vectors or matrices of the same size. If one argument is a scalar and the other is a vector or
matrix, airy(n,x) expands the scalar into a vector or matrix of the same size as the other
argument with all elements equal to the scalar.
• airy returns special exact values at 0.

Version History
Introduced in R2012a

See Also
besseli | besselj | besselk | bessely

7-32
 all

all
Test whether all equations and inequalities represented as elements of symbolic array are valid

Syntax
all(A)
all(A,dim)

Description
all(A) tests whether all elements of A return logical 1 (true). If A is a matrix, all tests all elements
of each column. If A is a multidimensional array, all tests all elements along one dimension.

all(A,dim) tests along the dimension of A specified by dim.

Examples
Test All Elements of Symbolic Vector

Create vector V that contains the symbolic equation and inequalities as its elements:
syms x
V = [x ~= x + 1, abs(x) >= 0, x == x];

Use all to test whether all of them are valid for all values of x:
all(V)

ans =
logical
1

Test All Elements of Symbolic Matrix

Create this matrix of symbolic equations and inequalities:

syms x
M = [x == x, x == abs(x); abs(x) >= 0, x ~= 2*x]

M =
[ x == x, x == abs(x)]
[ 0 <= abs(x), x ~= 2*x]

Use all to test equations and inequalities of this matrix. By default, all tests whether all elements
of each column are valid for all possible values of variables. If all equations and inequalities in the
column are valid (return logical 1), then all returns logical 1 for that column. Otherwise, it returns
logical 0 for the column. Thus, it returns 1 for the first column and 0 for the second column:
all(M)

ans =
1×2 logical array
1 0

7-33
7 Functions

Specify Dimension to Test Along

Create this matrix of symbolic equations and inequalities:

syms x
M = [x == x, x == abs(x); abs(x) >= 0, x ~= 2*x]

M =
[ x == x, x == abs(x)]
[ 0 <= abs(x), x ~= 2*x]

For matrices and multidimensional arrays, all can test all elements along the specified dimension. To
specify the dimension, use the second argument of all. For example, to test all elements of each
column of a matrix, use the value 1 as the second argument:

all(M, 1)

ans =
1×2 logical array
1 0

To test all elements of each row, use the value 2 as the second argument:

all(M, 2)

ans =
2×1 logical array
0
1

Test Arrays with Numeric Values

Test whether all elements of this vector return logical 1s. Note that all also converts all numeric
values outside equations and inequalities to logical 1s and 0s. The numeric value 0 becomes logical 0:

syms x
all([0, x == x])

ans =
logical
0

All nonzero numeric values, including negative and complex values, become logical 1s:

all([1, 2, -3, 4 + i, x == x])

ans =
logical
1

Input Arguments
A — Input
symbolic array

Input, specified as a symbolic array. For example, it can be an array of symbolic equations,
inequalities, or logical expressions with symbolic subexpressions.

7-34
 all

dim — Dimension
first non-singleton dimension (default) | integer

Dimension, specified as an integer. For example, if A is a matrix, any(A,1) tests elements of each
column and returns a row vector of logical 1s and 0s. any(A,2) tests elements of each row and
returns a column vector of logical 1s and 0s.

Tips
• If A is an empty symbolic array, all(A) returns logical 1.
• If some elements of A are just numeric values (not equations or inequalities), all converts these
values as follows. All numeric values except 0 become logical 1. The value 0 becomes logical 0.
• If A is a vector and all its elements return logical 1, all(A) returns logical 1. If one or more
elements are zero, all(A) returns logical 0.
• If A is a multidimensional array, all(A) treats the values along the first dimension that is not
equal to 1 (nonsingleton dimension) as vectors, returning logical 1 or 0 for each vector.

Version History
Introduced in R2012a

See Also
and | any | isAlways | not | or | xor

7-35
7 Functions

and
Logical AND for symbolic expressions

Syntax
A & B
and(A,B)

Description
A & B represents the logical AND. A & B is true only when both A and B are true.

and(A,B) is equivalent to A & B.

Examples

Construct and Set Assumptions Using AND

Combine symbolic inequalities into one condition by using &.

syms x y
cond = x>=0 & y>=0;

Set the assumptions represented by the condition using assume.

assume(cond)

Verify that the assumptions are set.

assumptions

ans =
[ 0 <= x, 0 <= y]

Evaluate Inequalities or Conditions

Define a range for a variable by combining two inequalities into a logical condition using &.

syms x
range = 0 < x & x < 1;

Return the condition at 1/2 and 10 by substituting for x using subs. The subs function does not
evaluate the conditions automatically.

x1 = subs(range,x,1/2)
x2 = subs(range,x,10)

x1 =
0 < 1/2 & 1/2 < 1

7-36
 and

x2 =
0 < 10 & 10 < 1

Evaluate the inequalities to logical 1 or 0 by using isAlways.

isAlways(x1)
isAlways(x2)

ans =
logical
1
ans =
logical
0

Input Arguments
A, B — Operands
symbolic equations | symbolic inequalities | symbolic expressions | symbolic arrays

Operands, specified as symbolic equations, inequalities, expressions, or arrays. Inputs A and B must
either be the same size or have sizes that are compatible (for example, A is an M-by-N matrix and B is
a scalar or 1-by-N row vector). For more information, see “Compatible Array Sizes for Basic
Operations”.

Tips
• If you call simplify for a logical expression containing symbolic subexpressions, you can get the
symbolic constants symtrue and symfalse. These two constants are not the same as logical 1
(true) and logical 0 (false). To convert symbolic symtrue and symfalse to logical values, use
logical.

Version History
Introduced in R2012a

Implicit expansion change affects arguments for operators

Behavior changed in R2016b

Starting in R2016b with the addition of implicit expansion, some combinations of arguments for basic
operations that previously returned errors now produce results. For example, you previously could
not add a row and a column vector, but those operands are now valid for addition. In other words, an
expression like [1 2] + [1; 2] previously returned a size mismatch error, but now it executes.

If your code uses element-wise operators and relies on the errors that MATLAB previously returned
for mismatched sizes, particularly within a try/catch block, then your code might no longer catch
those errors.

For more information on the required input sizes for basic array operations, see “Compatible Array
Sizes for Basic Operations”.

7-37
7 Functions

See Also
all | any | isAlways | not | or | piecewise | xor

7-38
 angle

angle
Symbolic polar angle

Syntax
angle(Z)

Description
angle(Z) computes the polar angle of the complex value Z.

Examples
Compute Polar Angle of Numeric Inputs

Compute the polar angles of these complex numbers. Because these numbers are not symbolic
objects, you get floating-point results.

[angle(1 + i), angle(4 + pi*i), angle(Inf + Inf*i)]

ans =
0.7854 0.6658 0.7854

Compute Polar Angle of Symbolic Inputs

Compute the polar angles of these complex numbers which are converted to symbolic objects:

[angle(sym(1) + i), angle(sym(4) + sym(pi)*i), angle(Inf + sym(Inf)*i)]

ans =
[ pi/4, atan(pi/4), pi/4]

Compute Polar Angle of Symbolic Expressions

Compute the limits of these symbolic expressions:

syms x
limit(angle(x + x^2*i/(1 + x)), x, -Inf)
limit(angle(x + x^2*i/(1 + x)), x, Inf)

ans =
-(3*pi)/4

ans =
pi/4

Compute Polar Angle of Array

Compute the polar angles of the elements of matrix Z:

Z = sym([sqrt(3) + 3*i, 3 + sqrt(3)*i; 1 + i, i]);

angle(Z)

7-39
7 Functions

ans =
[ pi/3, pi/6]
[ pi/4, pi/2]

Input Arguments
Z — Input
number | vector | matrix | array | symbolic number | symbolic array | symbolic function | symbolic
expression

Input, specified as a number, vector, matrix, array, or a symbolic number, variable, expression,
function.

Tips
• Calling angle for numbers (or vectors or matrices of numbers) that are not symbolic objects
invokes the MATLAB angle function.
• If Z = 0, then angle(Z) returns 0.

Alternatives
For real X and Y such that Z = X + Y*i, the call angle(Z) is equivalent to atan2(Y,X).

Version History
Introduced in R2013a

See Also
atan2 | conj | imag | real | sign | signIm

7-40
 animationToFrame

animationToFrame
Return structure of frames from animation objects

Syntax
frames = animationToFrame
frames = animationToFrame(fig)
frames = animationToFrame( ___ ,Name,Value)

Description
frames = animationToFrame returns a structure array of frames from animation objects. The
animation objects must be created using the fanimator function.

frames = animationToFrame(fig) returns a structure array of frames from animation objects in

the figure fig.

frames = animationToFrame( ___ ,Name,Value) uses the specified Name,Value pair

arguments. Use this option with any of the input argument combinations in the previous syntaxes.

Examples

Return Animation Frames

Create an animation of a moving circle, and return specific frames of the animation.

First, create two symbolic variables, t and x. The variable t defines the time parameter of the
animation. Use t to set the center of the circle at (t,1) and x to parameterize the perimeter of the
circle within the range [-pi pi]. Create the circle animation object using fanimator. Set the x-
axis and y-axis to be equal length.

syms t x
fanimator(@fplot,cos(x)+t,sin(x)+1,[-pi pi])
axis equal

By default, fanimator generates an animation object with 10 frames per unit time within the range
of t from 0 to 10. The default animation object contains a total of 101 frames. Use the command
playAnimation to play the animation.

Next, return a structure array of frames from the animation object by using animationToFrame.

frames = animationToFrame

7-41
7 Functions

frames=1×101 struct array with fields:

cdata
colormap

The structure frames contains two fields. The cdata field stores the image data as an array of
uint8 values.

Reconstruct the animation frames by using the imshow function. For example, display the 50th frame
and the last frame of the animation.

imshow(frames(50).cdata)

7-42
 animationToFrame

imshow(frames(101).cdata)

7-43
7 Functions

Return Animation Frames in Reverse Order

Create a moving circle animation object and a timer animation object. Return the generated
animation frames in reverse order.

First, create two symbolic variables, t and x. The variable t defines the time parameter of the
animation. Create a figure window for the animation.

syms t x
fig1 = figure;

Create a circle animation object using fanimator. Use t to set the center of the circle at (t,1) and
x to parameterize the perimeter of the circle within the range [-pi pi]. Set the x-axis and y-axis to
be equal length.

fanimator(@fplot,cos(x)+t,sin(x)+1,[-pi pi])
axis equal

Next, use the text function to add a piece of text to count the elapsed time. Use num2str to convert
the time parameter to a string.

7-44
 animationToFrame

hold on
fanimator(@(t) text(8,3,"Timer: "+num2str(t,2)))
hold off

By default, fanimator creates stop-motion frames with 10 frames per unit time within the range of t
from 0 to 10. The default animation object contains a total of 101 frames. Use the command
playAnimation to play the animation.

Next, return a structure array of frames from the animation in figure fig by using
animationToFrame. Return the animation frames in reverse order by setting the 'Backwards'
option to true. Set the frame rate per unit time to 2 to return a total of 21 frames.

frames = animationToFrame(fig1,'Backwards',true,'FrameRate',2)

frames=1×21 struct array with fields:

cdata
colormap

The structure frames contains two fields. The cdata field stores the image data as an array of
uint8 values.

Reconstruct the animation frames by using the imshow function. For example, display the first frame
and the 11th frame of the animation in a new figure window.

fig2 = figure;
imshow(frames(1).cdata)

7-45
7 Functions

imshow(frames(11).cdata)

7-46
 animationToFrame

Input Arguments
fig — Target figure
Figure object

Target figure, specified as a Figure object. For more information about Figure objects, see figure.

Name-Value Pair Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the

argument name and Value is the corresponding value. Name-value arguments must appear after
other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.
Example: 'Backwards',true,'AnimationRange',[-2 5]

AnimationRange — Range of animation time parameter

[0 10] (default) | two-element row vector

Range of the animation time parameter, specified as a two-element row vector. The two elements
must be real values that are increasing.

7-47
7 Functions

Example: [-2 4.5]

FrameRate — Frame rate

10 (default) | positive value

Frame rate, specified as a positive value. The frame rate defines the number of frames per unit time
when you returning animation frames as a structure array.
Example: 20

Backwards — Backward option

logical 0 (false) (default) | logical value

Backward option, specified as a logical value (boolean). If you specify true, then the function returns
the animation frames backwards or in reverse order.
Example: true

Output Arguments
frames — Animation frames
structure array

Animation frames, returned as a structure array with two fields:

• cdata — The image data stored as an array of uint8 values. The size of the image data array
depends on your screen resolution.
• colormap — The colormap. On true color systems, this field is empty.

The animationToFrame function returns a structure of animation frames in the same format as the
output returned by the getframe function.

Version History
Introduced in R2019a

See Also
playAnimation | fanimator | writeAnimation | rewindAnimation | getframe

7-48
 Animator Properties

Animator Properties
Animator appearance and behavior

Note UIContextMenu property is not recommended. Use ContextMenu instead. For more
information, see “Compatibility Considerations”.

Description
Animator properties control the appearance and behavior of an Animator object. By changing
property values, you can modify certain aspects of the Animator object. You can use dot notation to
refer to a particular object and property:

fp = fanimator(@(x) plot(x,sin(x),'bo'))
ls = fp.Visible
fp.Visible = 'off'

Properties
Frames

AnimationRange — Range of animation time parameter

[0 10] (default) | two-element row vector

This property is read-only.

Range of the animation time parameter, specified as a two-element row vector. The two elements
must be real values that are increasing.

FrameRate — Frame rate

10 (default) | positive value

This property is read-only.

Frame rate, specified as a positive value. The frame rate defines the number of frames per unit time
interval of an animation object.

Interactivity

Visible — State of visibility

'on' (default) | on/off logical value

State of visibility, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A value
of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value of this
property as a logical value. The value is stored as an on/off logical value of type
matlab.lang.OnOffSwitchState.

• 'on' — Display the object.

• 'off' — Hide the object without deleting it. You still can access the properties of an invisible
object.

7-49
7 Functions

ContextMenu — Context menu

empty GraphicsPlaceholder array (default) | ContextMenu object

Context menu, specified as a ContextMenu object. Use this property to display a context menu when
you right-click the object. Create the context menu using the uicontextmenu function.

Callbacks

ButtonDownFcn — Mouse-click callback

'' (default) | function handle | cell array | character vector

Mouse-click callback, specified as one of these values:

• Function handle.
• Cell array containing a function handle and additional arguments.
• Character vector that is a valid MATLAB command or function, which is evaluated in the base
workspace (not recommended).

Use this property to execute code when you click the object. If you specify this property using a
function handle, then MATLAB passes two arguments to the callback function when executing the
callback:

• Clicked object — Access properties of the clicked object from within the callback function.
• Event data — Empty argument. Replace it with the tilde character (~) in the function definition to
indicate that this argument is not used.

For more information on how to use function handles to define callback functions, see “Create
Callbacks for Graphics Objects”.

CreateFcn — Creation function

'' (default) | function handle | cell array | character vector

Object creation function, specified as one of these values:

• Function handle.
• Cell array in which the first element is a function handle. Subsequent elements in the cell array
are the arguments to pass to the callback function.
• Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates
this expression in the base workspace.

For more information about specifying a callback as a function handle, cell array, or character vector,
see “Create Callbacks for Graphics Objects”.

This property specifies a callback function to execute when MATLAB creates the object. MATLAB
initializes all property values before executing the CreateFcn callback. If you do not specify the
CreateFcn property, then MATLAB executes a default creation function.

Setting the CreateFcn property on an existing component has no effect.

If you specify this property as a function handle or cell array, you can access the object that is being
created using the first argument of the callback function. Otherwise, use the gcbo function to access
the object.

7-50
 Animator Properties

DeleteFcn — Deletion function

'' (default) | function handle | cell array | character vector

Object deletion function, specified as one of these values:

• Function handle.
• Cell array in which the first element is a function handle. Subsequent elements in the cell array
are the arguments to pass to the callback function.
• Character vector containing a valid MATLAB expression (not recommended). MATLAB evaluates
this expression in the base workspace.

For more information about specifying a callback as a function handle, cell array, or character vector,
see “Create Callbacks for Graphics Objects”.

This property specifies a callback function to execute when MATLAB deletes the object. MATLAB
executes the DeleteFcn callback before destroying the properties of the object. If you do not specify
the DeleteFcn property, then MATLAB executes a default deletion function.

If you specify this property as a function handle or cell array, you can access the object that is being
deleted using the first argument of the callback function. Otherwise, use the gcbo function to access
the object.

Callback Execution Control

Interruptible — Callback interruption

'on' (default) | on/off logical value

Callback interruption, specified as 'on' or 'off', or as numeric or logical 1 (true) or 0 (false). A

value of 'on' is equivalent to true, and 'off' is equivalent to false. Thus, you can use the value
of this property as a logical value. The value is stored as an on/off logical value of type
matlab.lang.OnOffSwitchState.

This property determines if a running callback can be interrupted. There are two callback states to
consider:

• The running callback is the currently executing callback.

• The interrupting callback is a callback that tries to interrupt the running callback.

MATLAB determines callback interruption behavior whenever it executes a command that processes
the callback queue. These commands include drawnow, figure, uifigure, getframe, waitfor,
and pause.

If the running callback does not contain one of these commands, then no interruption occurs.
MATLAB first finishes executing the running callback, and later executes the interrupting callback.

If the running callback does contain one of these commands, then the Interruptible property of
the object that owns the running callback determines if the interruption occurs:

• If the value of Interruptible is 'off', then no interruption occurs. Instead, the BusyAction
property of the object that owns the interrupting callback determines if the interrupting callback
is discarded or added to the callback queue.
• If the value of Interruptible is 'on', then the interruption occurs. The next time MATLAB
processes the callback queue, it stops the execution of the running callback and executes the

7-51
7 Functions

interrupting callback. After the interrupting callback completes, MATLAB then resumes executing
the running callback.

Note Callback interruption and execution behave differently in these situations:

• If the interrupting callback is a DeleteFcn, CloseRequestFcn, or SizeChangedFcn callback,

then the interruption occurs regardless of the Interruptible property value.
• If the running callback is currently executing the waitfor function, then the interruption occurs
regardless of the Interruptible property value.
• If the interrupting callback is owned by a Timer object, then the callback executes according to
schedule regardless of the Interruptible property value.

Note When an interruption occurs, MATLAB does not save the state of properties or the display. For
example, the object returned by the gca or gcf command might change when another callback
executes.

BusyAction — Callback queuing

'queue' (default) | 'cancel'

Callback queuing, specified as 'queue' or 'cancel'. The BusyAction property determines how
MATLAB handles the execution of interrupting callbacks. There are two callback states to consider:

• The running callback is the currently executing callback.

• The interrupting callback is a callback that tries to interrupt the running callback.

The BusyAction property determines callback queuing behavior only when both of these conditions
are met:

• The running callback contains a command that processes the callback queue, such as drawnow,
figure, uifigure, getframe, waitfor, or pause.
• The value of the Interruptible property of the object that owns the running callback is 'off'.

Under these conditions, the BusyAction property of the object that owns the interrupting callback
determines how MATLAB handles the interrupting callback. These are possible values of the
BusyAction property:

• 'queue' — Puts the interrupting callback in a queue to be processed after the running callback
finishes execution.
• 'cancel' — Does not execute the interrupting callback.

BeingDeleted — Deletion status

on/off logical value

This property is read-only.

Deletion status, returned as an on/off logical value of type matlab.lang.OnOffSwitchState.

MATLAB sets the BeingDeleted property to 'on' when the DeleteFcn callback begins execution.
The BeingDeleted property remains set to 'on' until the component object no longer exists.

7-52
 Animator Properties

Check the value of the BeingDeleted property to verify that the object is not about to be deleted
before querying or modifying it.

Parent/Child

Parent — Parent
Axes object

Parent, specified as an Axes object.

Children — Children
graphics object

Children, returned as a graphics object. Use this property to view the property values of the graphics
object.

You cannot add or remove children using the Children property. You can only set Children to a
permutation of itself.

HandleVisibility — Visibility of object handle

'on' (default) | 'off' | 'callback'

Visibility of the object handle in the Children property of the parent, specified as one of these
values:

• 'on' — Object handle is always visible.

• 'off' — Object handle is invisible at all times. This option is useful for preventing unintended
changes to the UI by another function. Set the HandleVisibility to 'off' to temporarily hide
the handle during the execution of that function.
• 'callback' — Object handle is visible from within callbacks or functions invoked by callbacks,
but not from within functions invoked from the command line. This option blocks access to the
object at the command line, but permits callback functions to access it.

If the object is not listed in the Children property of the parent, then functions that obtain object
handles by searching the object hierarchy or querying handle properties cannot return it. Examples
of such functions include the get, findobj, gca, gcf, gco, newplot, cla, clf, and close
functions.

Hidden object handles are still valid. Set the root ShowHiddenHandles property to 'on' to list all
object handles regardless of their HandleVisibility property setting.

Identifier

Type — Type of graphics object

'animator'

This property is read-only.

Type of graphics object, returned as 'animator'. Use this property to find all objects of a given type
within a plotting hierarchy. For example, you can use the findobj function to find graphics objects of
type 'animator'.

Tag — Object identifier

'' (default) | character vector | string scalar

7-53
7 Functions

Object identifier, specified as a character vector or string scalar. You can specify a unique Tag value
to serve as an identifier for an object. When you need access to the object elsewhere in your code,
you can use the findobj function to search for the object based on the Tag value.

UserData — User data

[] (default) | array

User data, specified as any MATLAB array. For example, you can specify a scalar, vector, matrix, cell
array, character array, table, or structure. Use this property to store arbitrary data on an object.

If you are working in App Designer, create public or private properties in the app to share data
instead of using the UserData property. For more information, see “Share Data Within App Designer
Apps”.

Version History
Introduced in R2019a

UIContextMenu property is not recommended

Not recommended starting in R2020a

Starting in R2020a, using the UIContextMenu property to assign a context menu to a graphics
object or UI component is not recommended. Use the ContextMenu property instead. The property
values are the same.

There are no plans to remove support for the UIContextMenu property at this time. However, the
UIContextMenu property no longer appears in the list returned by calling the get function on a
graphics object or UI component.

See Also

7-54
 any

any
Test whether at least one of equations and inequalities represented as elements of symbolic array is
valid

Syntax
any(A)
any(A,dim)

Description
any(A) tests whether at least one element of A returns logical 1 (true). If A is a matrix, any tests
elements of each column. If A is a multidimensional array, any tests elements along one dimension.

any(A,dim) tests along the dimension of A specified by dim.

Examples
Test Vector of Symbolic Conditions

Create vector V that contains the symbolic equation and inequalities as its elements:

syms x real
V = [x ~= x + 1, abs(x) >= 0, x == x];

Use any to test whether at least one of them is valid for all values of x:

any(V)

ans =
logical
1

Test Matrix of Symbolic Conditions

Create this matrix of symbolic equations and inequalities:

syms x real
M = [x == 2*x, x == abs(x); abs(x) >= 0, x == 2*x]

M =
[ x == 2*x, x == abs(x)]
[ 0 <= abs(x), x == 2*x]

Use any to test equations and inequalities of this matrix. By default, any tests whether any element
of each column is valid for all possible values of variables. If at least one equation or inequality in the
column is valid (returns logical 1), then any returns logical 1 for that column. Otherwise, it returns
logical 0 for the column. Thus, it returns 1 for the first column and 0 for the second column:

any(M)

7-55
7 Functions

ans =
1×2 logical array
1 0

Specify Dimension to Test Along

Create this matrix of symbolic equations and inequalities:

syms x real
M = [x == 2*x, x == abs(x); abs(x) >= 0, x == 2*x]

M =
[ x == 2*x, x == abs(x)]
[ 0 <= abs(x), x == 2*x]

For matrices and multidimensional arrays, any can test elements along the specified dimension. To
specify the dimension, use the second argument of any. For example, to test elements of each column
of a matrix, use the value 1 as the second argument:

any(M, 1)

ans =
1×2 logical array
1 0

To test elements of each row, use the value 2 as the second argument:

any(M, 2)

ans =
2×1 logical array
0
1

Test Arrays with Numeric Values

Test whether any element of this vector returns logical 1. Note that any also converts all numeric
values outside equations and inequalities to logical 1s and 0s. The numeric value 0 becomes logical 0:

syms x
any([0, x == x + 1])

ans =
logical
0

All nonzero numeric values, including negative and complex values, become logical 1s:

any([-4 + i, x == x + 1])

ans =
logical
1

Input Arguments
A — Input
symbolic array

7-56
 any

Input, specified as a symbolic array. For example, it can be an array of symbolic equations,
inequalities, or logical expressions with symbolic subexpressions.

dim — Dimension
first non-singleton dimension (default) | integer

Dimension, specified as an integer. For example, if A is a matrix, any(A,1) tests elements of each
column and returns a row vector of logical 1s and 0s. any(A,2) tests elements of each row and
returns a column vector of logical 1s and 0s.

Tips
• If A is an empty symbolic array, any(A) returns logical 0.
• If some elements of A are just numeric values (not equations or inequalities), any converts these
values as follows. All nonzero numeric values become logical 1. The value 0 becomes logical 0.
• If A is a vector and any of its elements returns logical 1, any(A) returns logical 1. If all elements
are zero, any(A) returns logical 0.
• If A is a multidimensional array, any(A) treats the values along the first dimension that is not
equal to 1 (non-singleton dimension) as vectors, returning logical 1 or 0 for each vector.

Version History
Introduced in R2012a

See Also
all | and | isAlways | not | or | xor

7-57
7 Functions

argnames
Input variables of symbolic function or matrix function

Syntax
args = argnames(f)

Description
args = argnames(f) returns the input variables of the symbolic function or matrix function f.

Examples

Find Input Variables of Symbolic Function

Create a symbolic function.

syms f(x,y)
f(x,y) = x + y;

Find the input variables of f by using argnames.

args = argnames(f)

args = x y

Create another symbolic function.

syms f(a,b,x,y)
f(x,b,y,a) = a*x + b*y;

Find the input variables of f. When returning variables, argnames uses the same order as you used
when you defined the function.

args = argnames(f)

args = x b y a

Find Input Variables of Symbolic Matrix Function

Create a symbolic matrix function.

syms A B 2 matrix
syms f(A,B) 2 matrix keepargs
f(A,B) = A*B - 3*A + 2*eye(2);

Find the input variables of f by using argnames. The result is a cell array containing symbolic matrix
variables.

7-58
 argnames

args = argnames(f)

args=1×2 cell array

{2x2 symmatrix} {2x2 symmatrix}

Access the contents of the cell array by indexing into it.

arg1 = args{1}

arg1 = A

arg2 = args{2}

arg2 = B

Input Arguments
f — Input function
symbolic function | symbolic matrix function

Input function, specified as a symbolic function or symbolic matrix function.

Data Types: symfun | symfunmatrix

Output Arguments
args — Input variables of symbolic function or matrix function
symbolic variable | vector of symbolic variables | cell array of symbolic matrix variables

Input variables of a symbolic function or matrix function.

• If f is a symbolic function of type symfun, then args is returned as a symbolic variable or a

vector of symbolic variables of type sym.
• If f is a symbolic matrix function of type symfunmatrix, then args is returned as a cell array of
symbolic matrix variables of type symmatrix.

Data Types: sym | cell

Version History
Introduced in R2012a

Find input variables of symbolic matrix functions

The argnames function accepts an input argument of type symfunmatrix. For an example, see
“Find Input Variables of Symbolic Matrix Function” on page 7-58.

See Also
formula | syms | symvar | symfun | symfunmatrix

7-59
7 Functions

asec
Symbolic inverse secant function

Syntax
asec(X)

Description
asec(X) returns the inverse secant function (arcsecant function) of X. All angles are in radians.

• For real elements of X in the interval [-Inf,-1] and [1,Inf], asec returns values in the
interval [0,pi].
• For real values of X in the interval [-1,1] and for complex values of X, asec returns complex
values with the real parts in the interval [0,pi].

Examples
Inverse Secant Function for Numeric and Symbolic Arguments

Depending on its arguments, asec returns floating-point or exact symbolic results.

Compute the inverse secant function for these numbers. Because these numbers are not symbolic
objects, asec returns floating-point results.
A = asec([-2, 0, 2/sqrt(3), 1/2, 1, 5])

A =
2.0944 + 0.0000i 0.0000 + Infi 0.5236 + 0.0000i...
0.0000 + 1.3170i 0.0000 + 0.0000i 1.3694 + 0.0000i

Compute the inverse secant function for the numbers converted to symbolic objects. For many
symbolic (exact) numbers, asec returns unresolved symbolic calls.
symA = asec(sym([-2, 0, 2/sqrt(3), 1/2, 1, 5]))

symA =
[ (2*pi)/3, Inf, pi/6, acos(2), 0, acos(1/5)]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =
[ 2.0943951023931954923084289221863,...
Inf,...
0.52359877559829887307710723054658,...
1.3169578969248165734029498707969i,...
0,...
1.3694384060045659001758622252964]

Plot Inverse Secant Function

7-60
 asec

Plot the inverse secant function on the interval from -10 to 10.
syms x
fplot(asec(x),[-10 10])
grid on

Handle Expressions Containing Inverse Secant Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing asec.

Find the first and second derivatives of the inverse secant function:
syms x
diff(asec(x), x)
diff(asec(x), x, x)

ans =
1/(x^2*(1 - 1/x^2)^(1/2))

ans =
- 2/(x^3*(1 - 1/x^2)^(1/2)) - 1/(x^5*(1 - 1/x^2)^(3/2))

Find the indefinite integral of the inverse secant function:

int(asec(x), x)

ans =
x*acos(1/x) - log(x + (x^2 - 1)^(1/2))*sign(x)

7-61
7 Functions

Find the Taylor series expansion of asec(x) around x = Inf:

taylor(asec(x), x, Inf)

ans =
pi/2 - 1/x - 1/(6*x^3) - 3/(40*x^5)

Rewrite the inverse secant function in terms of the natural logarithm:

rewrite(asec(x), 'log')

ans =
-log(1/x + (1 - 1/x^2)^(1/2)*1i)*1i

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
acos | asin | atan | acsc | acot | sin | cos | tan | csc | sec | cot

7-62
 asech

asech
Symbolic inverse hyperbolic secant function

Syntax
asech(X)

Description
asech(X) returns the inverse hyperbolic secant function of X.

Examples
Inverse Hyperbolic Secant Function for Numeric and Symbolic Arguments

Depending on its arguments, asech returns floating-point or exact symbolic results.

Compute the inverse hyperbolic secant function for these numbers. Because these numbers are not
symbolic objects, asech returns floating-point results.

A = asech([-2, 0, 2/sqrt(3), 1/2, 1, 3])

A =
0.0000 + 2.0944i Inf + 0.0000i 0.0000 + 0.5236i...
1.3170 + 0.0000i 0.0000 + 0.0000i 0.0000 + 1.2310i

Compute the inverse hyperbolic secant function for the numbers converted to symbolic objects. For
many symbolic (exact) numbers, asech returns unresolved symbolic calls.

symA = asech(sym([-2, 0, 2/sqrt(3), 1/2, 1, 3]))

symA =
[ (pi*2i)/3, Inf, (pi*1i)/6, acosh(2), 0, acosh(1/3)]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =
[ 2.0943951023931954923084289221863i,...
Inf,...
0.52359877559829887307710723054658i,...
1.316957896924816708625046347308,...
0,...
1.230959417340774682134929178248i]

Plot Inverse Hyperbolic Secant Function

Plot the inverse hyperbolic secant function on the interval from 0 to 1.

7-63
7 Functions

syms x
fplot(asech(x),[0 1])
grid on

Handle Expressions Containing Inverse Hyperbolic Secant Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing
asech.

Find the first and second derivatives of the inverse hyperbolic secant function. Simplify the second
derivative by using simplify.
syms x
diff(asech(x), x)
simplify(diff(asech(x), x, x))

ans =
-1/(x^2*(1/x - 1)^(1/2)*(1/x + 1)^(1/2))

ans =
-(2*x^2 - 1)/(x^5*(1/x - 1)^(3/2)*(1/x + 1)^(3/2))

Find the indefinite integral of the inverse hyperbolic secant function:

int(asech(x), x)

ans =
atan(1/((1/x - 1)^(1/2)*(1/x + 1)^(1/2))) + x*acosh(1/x)

7-64
 asech

Find the Taylor series expansion of asech(x) around x = Inf:

taylor(asech(x), x, Inf)

ans =
(pi*1i)/2 - 1i/x - 1i/(6*x^3) - 3i/(40*x^5)

Rewrite the inverse hyperbolic secant function in terms of the natural logarithm:

rewrite(asech(x), 'log')

ans =
log((1/x - 1)^(1/2)*(1/x + 1)^(1/2) + 1/x)

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
asinh | acosh | atanh | acsch | acoth | sinh | cosh | tanh | csch | sech | coth

7-65
7 Functions

asin
Symbolic inverse sine function

Syntax
asin(X)

Description
asin(X) returns the inverse sine function (arcsine function) of X. All angles are in radians.

• For real values of X in the interval [-1,1], asin(X) returns the values in the interval [-pi/
2,pi/2].
• For real values of X outside the interval [-1,1] and for complex values of X, asin(X) returns
complex values with the real parts in the interval [-pi/2,pi/2].

Examples
Inverse Sine Function for Numeric and Symbolic Arguments

Depending on its arguments, asin returns floating-point or exact symbolic results.

Compute the inverse sine function for these numbers. Because these numbers are not symbolic
objects, asin returns floating-point results.
A = asin([-1, -1/3, -1/2, 1/4, 1/2, sqrt(3)/2, 1])

A =
-1.5708 -0.3398 -0.5236 0.2527 0.5236 1.0472 1.5708

Compute the inverse sine function for the numbers converted to symbolic objects. For many symbolic
(exact) numbers, asin returns unresolved symbolic calls.
symA = asin(sym([-1, -1/3, -1/2, 1/4, 1/2, sqrt(3)/2, 1]))

symA =
[ -pi/2, -asin(1/3), -pi/6, asin(1/4), pi/6, pi/3, pi/2]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =
[ -1.5707963267948966192313216916398,...
-0.33983690945412193709639251339176,...
-0.52359877559829887307710723054658,...
0.25268025514207865348565743699371,...
0.52359877559829887307710723054658,...
1.0471975511965977461542144610932,...
1.5707963267948966192313216916398]

Plot Inverse Sine Function

7-66
 asin

Plot the inverse sine function on the interval from -1 to 1.

syms x
fplot(asin(x),[-1 1])
grid on

Handle Expressions Containing Inverse Sine Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing asin.

Find the first and second derivatives of the inverse sine function:
syms x
diff(asin(x), x)
diff(asin(x), x, x)

ans =
1/(1 - x^2)^(1/2)

ans =
x/(1 - x^2)^(3/2)

Find the indefinite integral of the inverse sine function:

int(asin(x), x)

ans =
x*asin(x) + (1 - x^2)^(1/2)

7-67
7 Functions

Find the Taylor series expansion of asin(x):

taylor(asin(x), x)

ans =
(3*x^5)/40 + x^3/6 + x

Rewrite the inverse sine function in terms of the natural logarithm:

rewrite(asin(x), 'log')

ans =
-log((1 - x^2)^(1/2) + x*1i)*1i

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
acos | atan | acsc | asec | acot | sin | cos | tan | csc | sec | cot

7-68
 asinh

asinh
Symbolic inverse hyperbolic sine function

Syntax
asinh(X)

Description
asinh(X) returns the inverse hyperbolic sine function of X.

Examples
Inverse Hyperbolic Sine Function for Numeric and Symbolic Arguments

Depending on its arguments, asinh returns floating-point or exact symbolic results.

Compute the inverse hyperbolic sine function for these numbers. Because these numbers are not
symbolic objects, asinh returns floating-point results.

A = asinh([-i, 0, 1/6, i/2, i, 2])

A =
0.0000 - 1.5708i 0.0000 + 0.0000i 0.1659 + 0.0000i...
0.0000 + 0.5236i 0.0000 + 1.5708i 1.4436 + 0.0000i

Compute the inverse hyperbolic sine function for the numbers converted to symbolic objects. For
many symbolic (exact) numbers, asinh returns unresolved symbolic calls.

symA = asinh(sym([-i, 0, 1/6, i/2, i, 2]))

symA =
[ -(pi*1i)/2, 0, asinh(1/6), (pi*1i)/6, (pi*1i)/2, asinh(2)]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =
[ -1.5707963267948966192313216916398i,...
0,...
0.16590455026930117643502171631553,...
0.52359877559829887307710723054658i,...
1.5707963267948966192313216916398i,...
1.4436354751788103012444253181457]

Plot Inverse Hyperbolic Sine Function

Plot the inverse hyperbolic sine function on the interval from -10 to 10.

7-69
7 Functions

syms x
fplot(asinh(x),[-10 10])
grid on

Handle Expressions Containing Inverse Hyperbolic Sine Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing
asinh.

Find the first and second derivatives of the inverse hyperbolic sine function:

syms x
diff(asinh(x), x)
diff(asinh(x), x, x)

ans =
1/(x^2 + 1)^(1/2)

ans =
-x/(x^2 + 1)^(3/2)

Find the indefinite integral of the inverse hyperbolic sine function:

int(asinh(x), x)

ans =
x*asinh(x) - (x^2 + 1)^(1/2)

7-70
 asinh

Find the Taylor series expansion of asinh(x):

taylor(asinh(x), x)

ans =
(3*x^5)/40 - x^3/6 + x

Rewrite the inverse hyperbolic sine function in terms of the natural logarithm:

rewrite(asinh(x), 'log')

ans =
log(x + (x^2 + 1)^(1/2))

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
acosh | atanh | acsch | asech | acoth | sinh | cosh | tanh | csch | sech | coth

7-71
7 Functions

assume
Set assumption on symbolic object

Syntax
assume(condition)
assume(expr,set)
assume(expr,'clear')

Description
assume(condition) states that condition is valid. assume is not additive. Instead, it
automatically deletes all previous assumptions on the variables in condition.

assume(expr,set) states that expr belongs to set. assume deletes previous assumptions on
variables in expr.

assume(expr,'clear') clears all assumptions on all variables in expr.

Examples
Common Assumptions

Set an assumption using the associated syntax.

Assume ‘x’ is Syntax

real assume(x,'real')
rational assume(x,'rational')
positive assume(x,'positive')
positive integer assume(x,{'positive','integer'})
less than -1 or greater than 1 assume(x<-1 | x>1)
an integer from 2 through 10 assume(in(x,'integer') & x>2 & x<10)
not an integer assume(~in(z,'integer'))
not equal to 0 assume(x ~= 0)
even assume(x/2,'integer')
odd assume((x-1)/2,'integer')
from 0 through 2π assume(x>0 & x<2*pi)
a multiple of π assume(x/pi,'integer')

Assume Variable Is Even or Odd

Assume x is even by assuming that x/2 is an integer. Assume x is odd by assuming that (x-1)/2 is
an integer.

Assume x is even.

7-72
 assume

syms x
assume(x/2,'integer')

Find all even numbers between 0 and 10 using solve.

solve(x>0,x<10,x)

ans =
2
4
6
8

Assume x is odd. assume is not additive, but instead automatically deletes the previous assumption
in(x/2, 'integer').

assume((x-1)/2,'integer')
solve(x>0,x<10,x)

ans =
1
3
5
7
9

Clear the assumptions on x for further computations.

assume(x,'clear')

Multiple Assumptions

Successive assume commands do not set multiple assumptions. Instead, each assume command
deletes previous assumptions and sets new assumptions. Set multiple assumptions by using
assumeAlso or the & operator.

Assume x > 5 and then x < 10 by using assume. Use assumptions to check that only the second
assumption exists because assume deleted the first assumption when setting the second.

syms x
assume(x > 5)
assume(x < 10)
assumptions

ans =
x < 10

Assume the first assumption in addition to the second by using assumeAlso. Check that both
assumptions exist.

assumeAlso(x > 5)
assumptions

ans =
[ 5 < x, x < 10]

Clear the assumptions on x.

assume(x,'clear')

7-73
7 Functions

Assume both conditions using the & operator. Check that both assumptions exist.
assume(x>5 & x<10)
assumptions

ans =
[ 5 < x, x < 10]

Clear the assumptions on x for future calculations.

assume(x,'clear')

Assumptions on Integrand

Compute an indefinite integral with and without the assumption on the symbolic parameter a.

Use assume to set an assumption that a does not equal -1.

syms x a
assume(a ~= -1)

Compute this integral.

int(x^a,x)

ans =
x^(a + 1)/(a + 1)

Now, clear the assumption and compute the same integral. Without assumptions, int returns this
piecewise result.
assume(a,'clear')
int(x^a, x)

ans =
piecewise(a == -1, log(x), a ~= -1, x^(a + 1)/(a + 1))

Assumptions on Parameters and Variables of Equation

Use assumptions to restrict the returned solutions of an equation to a particular interval.

Solve this equation.

syms x
eqn = x^5 - (565*x^4)/6 - (1159*x^3)/2 - (2311*x^2)/6 + (365*x)/2 + 250/3;
solve(eqn, x)

ans =
-5
-1
-1/3
1/2
100

Use assume to restrict the solutions to the interval –1 <= x <= 1.

assume(-1 <= x <= 1)
solve(eqn, x)

ans =
-1

7-74
 assume

-1/3
1/2

Set several assumptions simultaneously by using the logical operators and, or, xor, not, or their
shortcuts. For example, all negative solutions less than -1 and all positive solutions greater than 1.
assume(x < -1 | x > 1)
solve(eqn, x)

ans =
-5
100

For further computations, clear the assumptions.

assume(x,'clear')

Use Assumptions for Simplification

Setting appropriate assumptions can result in simpler expressions.

Try to simplify the expression sin(2*pi*n) using simplify. The simplify function cannot
simplify the input and returns the input as it is.
syms n
simplify(sin(2*n*pi))

ans =
sin(2*pi*n)

Assume n is an integer. simplify now simplifies the expression.

assume(n,'integer')
simplify(sin(2*n*pi))

ans =
0

For further computations, clear the assumption.

assume(n,'clear')

Assumptions on Expressions

Set assumption on the symbolic expression.

You can set assumptions not only on variables, but also on expressions. For example, compute this
integral.
syms x
f = 1/abs(x^2 - 1);
int(f,x)

ans =
-atanh(x)/sign(x^2 - 1)

Set the assumption x2 – 1 > 0 to produce a simpler result.

assume(x^2 - 1 > 0)
int(f,x)

7-75
7 Functions

ans =
-atanh(x)

For further computations, clear the assumption.

assume(x,'clear')

Assumptions to Prove Relations

Prove relations that hold under certain conditions by first assuming the conditions and then using
isAlways.

Prove that sin(pi*x) is never equal to 0 when x is not an integer. The isAlways function returns
logical 1 (true), which means the condition holds for all values of x under the set assumptions.

syms x
assume(~in(x,'integer'))
isAlways(sin(pi*x) ~= 0)

ans =
logical
1

Assumptions on Matrix Elements

Set assumptions on all elements of a matrix using sym.

Create the 2-by-2 symbolic matrix A with auto-generated elements. Specify the set as rational.

A = sym('A',[2 2],'rational')

A =
[ A1_1, A1_2]
[ A2_1, A2_2]

Return the assumptions on the elements of A using assumptions.

assumptions(A)

ans =
[ in(A1_1, 'rational'), in(A1_2, 'rational'),...
in(A2_1, 'rational'), in(A2_2, 'rational')]

You can also use assume to set assumptions on all elements of a matrix. Now, assume all elements of
A have positive rational values. Set the assumptions as a cell of character vectors
{'positive','rational'}.

assume(A,{'positive','rational'})

Return the assumptions on the elements of A using assumptions.

assumptions(A)

ans =
[ 0 < A1_1, 0 < A1_2, 0 < A2_1, 0 < A2_2,...
in(A1_1, 'rational'), in(A1_2, 'rational'),...
in(A2_1, 'rational'), in(A2_2, 'rational')]

For further computations, clear the assumptions.

7-76
 assume

assume(A,'clear')

Input Arguments
condition — Assumption statement
symbolic expression | symbolic equation | symbolic relation | vector or matrix of symbolic expressions,
equations, or relations

Assumption statement, specified as a symbolic expression, equation, relation, or vector or matrix of

symbolic expressions, equations, or relations. You also can combine several assumptions by using the
logical operators and, or, xor, not, or their shortcuts.

expr — Expression to set assumption on

symbolic variable | symbolic expression | vector or matrix of symbolic variables or expressions

Expression to set assumption on, specified as a symbolic variable, expression, vector, or matrix. If
expr is a vector or matrix, then assume(expr,set) sets an assumption that each element of expr
belongs to set.

set — Set of assumptions

character vector | string array | cell array

Set of assumptions, specified as a character vector, string array, or cell array. The available
assumptions are 'integer', 'rational', 'real', or 'positive'.

You can combine multiple assumptions by specifying a string array or cell array of character vectors.
For example, assume a positive rational value by specifying set as ["positive" "rational"] or
{'positive','rational'}.

Tips
• assume removes any assumptions previously set on the symbolic variables. To retain previous
assumptions while adding an assumption, use assumeAlso.
• When you delete a symbolic variable from the MATLAB workspace using clear, all assumptions
that you set on that variable remain in the symbolic engine. If you later declare a new symbolic
variable with the same name, it inherits these assumptions.
• To clear all assumptions set on a symbolic variable var, use this command.
assume(var,'clear')
• To delete all objects in the MATLAB workspace and close the Symbolic Math Toolbox engine
associated with the MATLAB workspace clearing all assumptions, use this command:
clear all
• MATLAB projects complex numbers in inequalities to the real axis. If condition is an inequality,
then both sides of the inequality must represent real values. Inequalities with complex numbers
are invalid because the field of complex numbers is not an ordered field. (It is impossible to tell
whether 5 + i is greater or less than 2 + 3*i.) For example, x > i becomes x > 0, and x <=
3 + 2*i becomes x <= 3.
• The toolbox does not support assumptions on symbolic functions. Make assumptions on symbolic
variables and expressions instead.
• When you create a new symbolic variable using sym and syms, you also can set an assumption
that the variable is real, positive, integer, or rational.

7-77
7 Functions

a = sym('a','real');
b = sym('b','rational');
c = sym('c','positive');
d = sym('d','positive');
e = sym('e',{'positive','integer'});

or more efficiently

syms a real
syms b rational
syms c d positive
syms e positive integer

Version History
Introduced in R2012a

See Also
and | assumeAlso | assumptions | isAlways | in | not | or | piecewise | sym | syms

Topics
“Set Assumptions” on page 1-41
“Check Existing Assumptions” on page 1-42
“Delete Symbolic Objects and Their Assumptions” on page 1-42
“Default Assumption” on page 1-41

7-78
 assumeAlso

assumeAlso
Add assumption on symbolic object

Syntax
assumeAlso(condition)
assumeAlso(expr,set)

Description
assumeAlso(condition) states that condition is valid for all symbolic variables in condition.
It retains all assumptions previously set on these symbolic variables.

assumeAlso(expr,set) states that expr belongs to set, in addition to all previously made
assumptions.

Examples
Assumptions Specified as Relations

Set assumptions using assume. Then add more assumptions using assumeAlso.

Solve this equation assuming that both x and y are nonnegative.

syms x y
assume(x >= 0 & y >= 0)
s = solve(x^2 + y^2 == 1, y)

Warning: Solutions are valid under the following

conditions: x <= 1;
x == 1.
To include parameters and conditions in the
solution, specify the 'ReturnConditions' value as
'true'.
> In solve>warnIfParams (line 482)
In solve (line 357)
s =
(1 - x)^(1/2)*(x + 1)^(1/2)
-(1 - x)^(1/2)*(x + 1)^(1/2)

The solver warns that both solutions hold only under certain conditions.

Add the assumption that x < 1. To add a new assumption without removing the previous one, use
assumeAlso.
assumeAlso(x < 1)

Solve the same equation under the expanded set of assumptions.

s = solve(x^2 + y^2 == 1, y)

s =
(1 - x)^(1/2)*(x + 1)^(1/2)

7-79
7 Functions

For further computations, clear the assumptions.

assume([x y],'clear')

Assumptions Specified as Sets

Set assumptions using syms. Then add more assumptions using assumeAlso.

When declaring the symbolic variable n, set an assumption that n is positive.

syms n positive

Using assumeAlso, add more assumptions on the same variable n. For example, assume also that n
is an integer.

assumeAlso(n,'integer')

Return all assumptions affecting variable n using assumptions. In this case, n is a positive integer.

assumptions(n)

ans =
[ 0 < n, in(n, 'integer')]

For further computations, clear the assumptions.

assume(n,'clear')

Assumptions on Matrix Elements

Use the assumption on a matrix as a shortcut for setting the same assumption on each matrix
element.

Create the 3-by-3 symbolic matrix A with auto-generated elements. To assume every element of A is
rational, specify set as 'rational'.

A = sym('A',[3 3],'rational')

A =
[ A1_1, A1_2, A1_3]
[ A2_1, A2_2, A2_3]
[ A3_1, A3_2, A3_3]

Now, add the assumption that each element of A is greater than 1.

assumeAlso(A > 1)

Return assumptions affecting elements of A using assumptions:

assumptions(A)

ans =
[ 1 < A1_1, 1 < A1_2, 1 < A1_3, 1 < A2_1, 1 < A2_2, 1 < A2_3,...
1 < A3_1, 1 < A3_2, 1 < A3_3,...
in(A1_1, 'rational'), in(A1_2, 'rational'), in(A1_3, 'rational'),...
in(A2_1, 'rational'), in(A2_2, 'rational'), in(A2_3, 'rational'),...
in(A3_1, 'rational'), in(A3_2, 'rational'), in(A3_3, 'rational')]

For further computations, clear the assumptions.

7-80
 assumeAlso

assume(A,'clear')

Contradicting Assumptions

When you add assumptions, ensure that the new assumptions do not contradict the previous
assumptions. Contradicting assumptions can lead to inconsistent and unpredictable results. In some
cases, assumeAlso detects conflicting assumptions and issues an error.

Try to set contradicting assumptions. assumeAlso returns an error.

syms y
assume(y,'real')
assumeAlso(y == i)

Error using mupadengine/feval (line 172)

Inconsistent assumptions.
Error in sym/assumeAlso (line 627)
feval(symengine, 'assumeAlso', cond);

assumeAlso does not guarantee to detect contradicting assumptions. For example, assume that y is
nonzero, and both y and y*i are real values.
syms y
assume(y ~= 0)
assumeAlso(y,'real')
assumeAlso(y*i,'real')

Return all assumptions affecting variable y using assumptions:

assumptions(y)

ans =
[ in(y, 'real'), in(y*1i, 'real'), y ~= 0]

For further computations, clear the assumptions.

assume(y,'clear')

Input Arguments
condition — Assumption statement
symbolic expression | symbolic equation | relation | vector or matrix of symbolic expressions,
equations, or relations

Assumption statement, specified as a symbolic expression, equation, relation, or vector or matrix of

symbolic expressions, equations, or relations. You also can combine several assumptions by using the
logical operators and, or, xor, not, or their shortcuts.

expr — Expression to set assumption on

symbolic variable | symbolic expression | vector or matrix of symbolic variables or expressions

Expression to set assumption on, specified as a symbolic variable, expression, or a vector or matrix of
symbolic variables or expressions. If expr is a vector or matrix, then assumeAlso(expr,set) sets
an assumption that each element of expr belongs to set.

set — Set of assumptions

character vector | string array | cell array

7-81
7 Functions

Set of assumptions, specified as a character vector, string array, or cell array. The available
assumptions are 'integer', 'rational', 'real', or 'positive'.

You can combine multiple assumptions by specifying a string array or cell array of character vectors.
For example, assume a positive rational value by specifying set as ["positive" "rational"] or
{'positive','rational'}.

Tips
• assumeAlso keeps all assumptions previously set on the symbolic variables. To replace previous
assumptions with the new one, use assume.
• When adding assumptions, always check that a new assumption does not contradict the existing
assumptions. To see existing assumptions, use assumptions. Symbolic Math Toolbox does not
guarantee to detect conflicting assumptions. Conflicting assumptions can lead to unpredictable
and inconsistent results.
• When you delete a symbolic variable from the MATLAB workspace using clear, all assumptions
that you set on that variable remain in the symbolic engine. If later you declare a new symbolic
variable with the same name, it inherits these assumptions.
• To clear all assumptions set on a symbolic variable var use this command.

assume(var,'clear')
• To clear all objects in the MATLAB workspace and close the Symbolic Math Toolbox engine
associated with the MATLAB workspace resetting all its assumptions, use this command.

clear all
• MATLAB projects complex numbers in inequalities to the real axis. If condition is an inequality,
then both sides of the inequality must represent real values. Inequalities with complex numbers
are invalid because the field of complex numbers is not an ordered field. (It is impossible to tell
whether 5 + i is greater or less than 2 + 3*i.) For example, x > i becomes x > 0, and x <=
3 + 2*i becomes x <= 3.
• The toolbox does not support assumptions on symbolic functions. Make assumptions on symbolic
variables and expressions instead.
• Instead of adding assumptions one by one, you can set several assumptions in one function call. To
set several assumptions, use assume and combine these assumptions by using the logical
operators and, or, xor, not, all, any, or their shortcuts.

Version History
Introduced in R2012a

See Also
and | assume | assumptions | in | isAlways | not | or | piecewise | sym | syms

Topics
“Set Assumptions” on page 1-41
“Check Existing Assumptions” on page 1-42
“Delete Symbolic Objects and Their Assumptions” on page 1-42
“Default Assumption” on page 1-41

7-82
 assumptions

assumptions
Show assumptions affecting symbolic variable, expression, or function

Syntax
assumptions(var)
assumptions

Description
assumptions(var) returns all assumptions that affect variable var. If var is an expression or
function, assumptions returns all assumptions that affect all variables in var.

assumptions returns all assumptions that affect all variables in MATLAB Workspace.

Examples
Assumptions on Variables

Assume that the variable n is an integer using assume. Return the assumption using assumptions.
syms n
assume(n,'integer')
assumptions

ans =
in(n, 'integer')

The syntax in(n, 'integer') indicates n is an integer.

Assume that n is less than x and that x < 42 using assume. The assume function replaces old
assumptions on input with the new assumptions. Return all assumptions that affect n.
syms x
assume(n<x & x<42)
assumptions(n)

ans =
[ n < x, x < 42]

assumptions returns the assumption x < 42 because it affects n through the assumption n < x.
Thus, assumptions returns the transitive closure of assumptions, which is all assumptions that
mathematically affect the input.

Set the assumption on variable m that 1 < m < 3. Return all assumptions on m and x using
assumptions.
syms m
assume(1<m<3)
assumptions([m x])

ans =
[ n < x, 1 < m, m < 3, x < 42]

7-83
7 Functions

To see the assumptions that affect all variables, use assumptions without any arguments.
assumptions

ans =
[ n < x, 1 < m, m < 3, x < 42]

For further computations, clear the assumptions.

assume([m n x],'clear')

Multiple Assumptions on One Variable

You cannot set an additional assumption on a variable using assume because assume clears all
previous assumptions on that variable. To set an additional assumption on a variable, using
assumeAlso.

Set an assumption on x using assume. Set an additional assumption on x use assumeAlso. Use
assumptions to return the multiple assumptions on x.
syms x
assume(x,'real')
assumeAlso(x<0)
assumptions(x)

ans =
[ in(x, 'real'), x < 0]

The syntax in(x, 'real') indicates x is real.

For further computations, clear the assumptions.

assume(x,'clear')

Assumptions Affecting Expressions and Functions

assumptions accepts symbolic expressions and functions as input and returns all assumptions that
affect all variables in the symbolic expressions or functions.

Set assumptions on variables in a symbolic expression. Find all assumptions that affect all variables
in the symbolic expression using assumptions.
syms a b c
expr = a*exp(b)*sin(c);
assume(a+b > 3 & in(a,'integer') & in(c,'real'))
assumptions(expr)

ans =
[ 3 < a + b, in(a, 'integer'), in(c, 'real')

Find all assumptions that affect all variables that are inputs to a symbolic function.
syms f(a,b,c)
assumptions(f)

ans =
[ 3 < a + b, in(a, 'integer'), in(c, 'real')]

Clear the assumptions for further computations.

7-84
 assumptions

assume([a b c],'clear')

Restore Old Assumptions

To restore old assumptions, first store the assumptions returned by assumptions. Then you can
restore these assumptions at any point by calling assume or assumeAlso.

Solve the equation for a spring using dsolve under the assumptions that the mass and spring
constant are positive.
syms m k positive
syms x(t)
dsolve(m*diff(x,t,t) == -k*x, x(0)==0)

ans =
C8*sin((k^(1/2)*t)/m^(1/2))

Suppose you want to explore solutions unconstrained by assumptions, but want to restore the
assumptions afterwards. First store the assumptions using assumptions, then clear the assumptions
and solve the equation. dsolve returns unconstrained solutions.
tmp = assumptions;
assume([m k],'clear')
dsolve(m*diff(x,t,t) == -k*x, x(0)==0)

ans =
C10*exp((t*(-k*m)^(1/2))/m) + C10*exp(-(t*(-k*m)^(1/2))/m)

Restore the original assumptions using assume.

assume(tmp)

After computations are complete, clear assumptions using assume.

assume([m k],'clear')

Input Arguments
var — Symbolic input to check for assumptions
symbolic variable | symbolic expression | symbolic function | symbolic vector | symbolic matrix |
symbolic multidimensional array

Symbolic input for which to show assumptions, specified as a symbolic variable, expression, or
function, or a vector, matrix, or multidimensional array of symbolic variables, expressions, or
functions.

Tips
• When you delete a symbolic object from the MATLAB workspace by using clear, all assumptions
that you set on that object remain in the symbolic engine. If you declare a new symbolic variable
with the same name, it inherits these assumptions.
• To clear all assumptions set on a symbolic variable var use this command.
assume(var,'clear')
• To clear all objects in the MATLAB workspace and close the Symbolic Math Toolbox engine
associated with the MATLAB workspace resetting all its assumptions, use this command.

7-85
7 Functions

clear all

Version History
Introduced in R2012a

See Also
and | assume | assumeAlso | clear | in | isAlways | not | or | piecewise | sym | syms

Topics
“Set Assumptions” on page 1-41
“Check Existing Assumptions” on page 1-42
“Delete Symbolic Objects and Their Assumptions” on page 1-42
“Default Assumption” on page 1-41

7-86
 atan

atan
Symbolic inverse tangent

Syntax
P = atan(Z)
P = atan(Y,X)

Description
P = atan(Z) returns the inverse tangent on page 7-90 (arctangent) of the elements of Z. All angles
are in radians.

• For real values of Z, atan(Z) returns values in the interval [-pi/2,pi/2].

• For complex values of Z, atan(Z) returns complex values with the real parts in the interval [-
pi/2,pi/2].

P = atan(Y,X) returns the four-quadrant inverse tangent on page 7-90 of the elements of Y and X.
This syntax with two input arguments is the same as atan2(Y,X).

Symbolic arguments X and Y are assumed to be real, and atan(Y,X) returns values in the interval
[-pi,pi].

Examples

Inverse Tangent Function for Numeric and Symbolic Arguments

Depending on its arguments, atan returns floating-point or exact symbolic results.

Compute the inverse tangent function for these numbers. Because these numbers are not symbolic
objects, atan returns floating-point results.
P = atan([-1, -1/3, -1/sqrt(3), 1/2, 1, sqrt(3)])

P = 1×6

-0.7854 -0.3218 -0.5236 0.4636 0.7854 1.0472

Compute the inverse tangent function for the numbers converted to symbolic objects. For many
symbolic (exact) numbers, atan returns unresolved symbolic calls.
symP = atan(sym([-1, -1/3, -1/sqrt(3), 1/2, 1, sqrt(3)]))

symP =
π 1 π 1 π π
− −atan − atan
4 3 6 2 4 3

Use vpa to approximate symbolic results with floating-point numbers.

vpaP = vpa(symP)

7-87
7 Functions

vpaP = −0.78539816339744830961566084581988 −0.32175055439664219340140461435866 −0.52359877559829887307

Plot Inverse Tangent Function

Plot the inverse tangent function on the interval from -10 to 10.
syms x
fplot(atan(x),[-10 10])
grid on

Handle Expressions Containing Inverse Tangent Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing atan.

Find the first and second derivatives of the inverse tangent function.
syms z
D1 = diff(atan(z),z)

D1 =
1
z2 + 1

7-88
 atan

D2 = diff(atan(z),z,z)

D2 =
2z
− 2
z2 + 1

Find the indefinite integral of the inverse tangent function.

I = int(atan(z),z)

I =
log z2 + 1
z atan z −
2

Find the Taylor series expansion of atan(z).

T = taylor(atan(z),z)

T =
z5 z3
− +z
5 3

Rewrite the inverse tangent function in terms of the natural logarithm.

R = rewrite(atan(z),'log')

R =
log 1 − z i i log 1 + z i i
−
2 2

Input Arguments
Z — Tangent of angle
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix | symbolic array

Tangent of angle, specified as a symbolic number, variable, expression, or function, or as a vector,

matrix, or array of symbolic numbers, variables, expressions, or functions.

Y — y-coordinates
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix | symbolic array

y-coordinates, specified as a symbolic number, variable, expression, or function, or as a vector,

matrix, or array of symbolic numbers, variables, expressions, or functions. All numerical elements of
Y must be real.

Inputs Y and X must either be the same size or have sizes that are compatible (for example, Y is an M-
by-N matrix and X is a scalar or 1-by-N row vector). For more information, see “Compatible Array
Sizes for Basic Operations”.

X — x-coordinates
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix | symbolic array

7-89
7 Functions

x-coordinates, specified as a symbolic number, variable, expression, or function, or as a vector,

matrix, or array of symbolic numbers, variables, expressions, or functions. All numerical elements of
X must be real.

Inputs Y and X must either be the same size or have sizes that are compatible (for example, Y is an M-
by-N matrix and X is a scalar or 1-by-N row vector). For more information, see “Compatible Array
Sizes for Basic Operations”.

More About
Inverse Tangent

The inverse tangent is defined as

i 1 − iZ
atan(Z) = log .
2 1 + iZ

Four-Quadrant Inverse Tangent

If X ≠ 0 and Y ≠ 0, then

Y π
atan Y, X = atan( ) + sign Y 1 − sign X .
X 2

Results returned by atan(Y,X) belong to the closed interval [-pi,pi]. Meanwhile, results returned
by atan(Y/X) belong to the closed interval [-pi/2,pi/2].

Version History
Introduced before R2006a

See Also
acos | asin | acsc | asec | acot | atan2 | sin | cos | tan | csc | sec | cot

7-90
 atan2

atan2
Symbolic four-quadrant inverse tangent

Syntax
P = atan2(Y,X)

Description
P = atan2(Y,X) computes the four-quadrant inverse tangent on page 7-92 (arctangent) of Y and
X.

Symbolic arguments X and Y are assumed to be real, and atan2(Y,X) returns values in the interval
[-pi,pi].

Examples

Four-Quadrant Inverse Tangent for Numeric and Symbolic Arguments

Compute the arctangents of these parameters. Because these numbers are not symbolic objects, you
get floating-point results.

P = [atan2(1,1), atan2(pi,4), atan2(Inf,Inf)]

P = 1×3

0.7854 0.6658 0.7854

Compute the arctangents of these parameters which are converted to symbolic objects.

P = [atan2(sym(1),1), atan2(sym(pi),sym(4)), atan2(Inf,sym(Inf))]

P =
π π π
atan
4 4 4

Limit of Four-Quadrant Inverse Tangent

Compute the limits of this symbolic expression.

syms x
P_minusinf = limit(atan2(x^2/(1 + x),x),x,-Inf)

P_minusinf =
3π
−
4

P_plusinf = limit(atan2(x^2/(1 + x),x),x,Inf)

7-91
7 Functions

P_plusinf =
π
4

Four-Quadrant Inverse Tangent of Array Input

Compute the arctangents of the elements of matrices Y and X.

Y = sym([3 sqrt(3); 1 1]);
X = sym([sqrt(3) 3; 1 0]);
P = atan2(Y,X)

P =
π π
3 6
π π
4 2

Input Arguments
Y — y-coordinates
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix | symbolic array

y-coordinates, specified as a symbolic number, variable, expression, or function, or as a vector,

matrix, or array of symbolic numbers, variables, expressions, or functions. All numerical elements of
Y must be real.

Inputs Y and X must either be the same size or have sizes that are compatible (for example, Y is an M-
by-N matrix and X is a scalar or 1-by-N row vector). For more information, see “Compatible Array
Sizes for Basic Operations”.

X — x-coordinates
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix | symbolic array

x-coordinates, specified as a symbolic number, variable, expression, or function, or as a vector,

matrix, or array of symbolic numbers, variables, expressions, or functions. All numerical elements of
X must be real.

Inputs Y and X must either be the same size or have sizes that are compatible (for example, Y is an M-
by-N matrix and X is a scalar or 1-by-N row vector). For more information, see “Compatible Array
Sizes for Basic Operations”.

More About
Four-Quadrant Inverse Tangent

If X ≠ 0 and Y ≠ 0, then

Y π
atan2 Y, X = atan( ) + sign Y 1 − sign X
X 2

7-92
 atan2

Results returned by atan2(Y,X) belong to the closed interval [-pi,pi]. Meanwhile, results
returned by atan(Y/X) belong to the closed interval [-pi/2,pi/2].

Tips
• Calling atan2 for numbers (or vectors or matrices of numbers) that are not symbolic objects
invokes the MATLAB atan2 function.
• If one of the arguments X and Y is a vector or a matrix, and another one is a scalar, then atan2
expands the scalar into a vector or a matrix of the same length with all elements equal to that
scalar.
• If X = 0 and Y > 0, then atan2(Y,X) returns pi/2.

If X = 0 and Y < 0, then atan2(Y,X) returns -pi/2.

If X = Y = 0, then atan2(Y,X) returns 0.

Alternatives
For complex Z = X + Y*i, the call atan2(Y,X) is equivalent to angle(Z).

Version History
Introduced in R2013a

See Also
angle | atan | conj | imag | real

7-93
7 Functions

atanh
Symbolic inverse hyperbolic tangent function

Syntax
atanh(X)

Description
atanh(X) returns the inverse hyperbolic tangent function of X.

Examples
Inverse Hyperbolic Tangent Function for Numeric and Symbolic Arguments

Depending on its arguments, atanh returns floating-point or exact symbolic results.

Compute the inverse hyperbolic tangent function for these numbers. Because these numbers are not
symbolic objects, atanh returns floating-point results.

A = atanh([-i, 0, 1/6, i/2, i, 2])

A =
0.0000 - 0.7854i 0.0000 + 0.0000i 0.1682 + 0.0000i...
0.0000 + 0.4636i 0.0000 + 0.7854i 0.5493 + 1.5708i

Compute the inverse hyperbolic tangent function for the numbers converted to symbolic objects. For
many symbolic (exact) numbers, atanh returns unresolved symbolic calls.

symA = atanh(sym([-i, 0, 1/6, i/2, i, 2]))

symA =
[ -(pi*1i)/4, 0, atanh(1/6), atanh(1i/2), (pi*1i)/4, atanh(2)]

Use vpa to approximate symbolic results with floating-point numbers:

vpa(symA)

ans =
[ -0.78539816339744830961566084581988i,...
0,...
0.1682361183106064652522967051085,...
0.46364760900080611621425623146121i,...
0.78539816339744830961566084581988i,...
0.54930614433405484569762261846126 - 1.5707963267948966192313216916398i]

Plot Inverse Hyperbolic Tangent Function

Plot the inverse hyperbolic tangent function on the interval from -1 to 1.

7-94
 atanh

syms x
fplot(atanh(x),[-1 1])
grid on

Handle Expressions Containing Inverse Hyperbolic Tangent Function

Many functions, such as diff, int, taylor, and rewrite, can handle expressions containing
atanh.

Find the first and second derivatives of the inverse hyperbolic tangent function:

syms x
diff(atanh(x), x)
diff(atanh(x), x, x)

ans =
-1/(x^2 - 1)

ans =
(2*x)/(x^2 - 1)^2

Find the indefinite integral of the inverse hyperbolic tangent function:

int(atanh(x), x)

ans =
log(x^2 - 1)/2 + x*atanh(x)

7-95
7 Functions

Find the Taylor series expansion of atanh(x):

taylor(atanh(x), x)

ans =
x^5/5 + x^3/3 + x

Rewrite the inverse hyperbolic tangent function in terms of the natural logarithm:

rewrite(atanh(x), 'log')

ans =
log(x + 1)/2 - log(1 - x)/2

Input Arguments
X — Input
symbolic number | symbolic variable | symbolic expression | symbolic function | symbolic vector |
symbolic matrix

Input, specified as a symbolic number, variable, expression, or function, or as a vector or matrix of

symbolic numbers, variables, expressions, or functions.

Version History
Introduced before R2006a

See Also
acosh | asinh | acsch | asech | acoth | sinh | cosh | tanh | csch | sech | coth

7-96
 baseUnits

baseUnits
Base units of unit system

Syntax
baseUnits(unitSystem)

Description
baseUnits(unitSystem) returns the base units of the unit system unitSystem as a vector of
symbolic units. You can use the returned units to create new unit systems by using newUnitSystem.

Examples

Base Units of Unit System

Get the base units of a unit system by using baseUnits. Then, modify the base units and create a
new unit system using the modified base units. Available unit systems include SI, CGS, and US. For all
unit systems, see “Unit Systems List” on page 2-68.

Get the base units of the SI unit system.

SIUnits = baseUnits('SI')

SIUnits =
[ [kg], [s], [m], [A], [cd], [mol], [K]]

Note Do not define a variable called baseUnits because the variable will prevent access to the
baseUnits function.

Define base units that use kilometer for length and hour for time by modifying SIUnits using subs.

u = symunit;
newUnits = subs(SIUnits,[u.m u.s],[u.km u.hr])

newUnits =
[ [kg], [h], [km], [A], [cd], [mol], [K]]

Define the new unit system by using newUnitSystem.

newUnitSystem('SI_km_hr',newUnits)

ans =
"SI_km_hr"

7-97
7 Functions

To convert units between unit systems, see “Unit Conversions and Unit Systems” on page 2-50.

Input Arguments
unitSystem — Name of unit system
string | character vector

Name of the unit system, specified as a string or character vector.

Version History
Introduced in R2017b

See Also
derivedUnits | newUnitSystem | removeUnitSystem | rewrite | symunit

Topics
“Units of Measurement Tutorial” on page 2-44
“Unit Conversions and Unit Systems” on page 2-50
“Units and Unit Systems List” on page 2-57

External Websites
The International System of Units (SI)

7-98
 bernoulli

bernoulli
Bernoulli numbers and polynomials

Syntax
bernoulli(n)
bernoulli(n,x)

Description
bernoulli(n) returns the nth Bernoulli number on page 7-102.

bernoulli(n,x) returns the nth Bernoulli polynomial on page 7-102.

Examples
Bernoulli Numbers with Odd and Even Indices

The 0th Bernoulli number is 1. The next Bernoulli number can be -1/2 or 1/2, depending on the
definition. The bernoulli function uses -1/2. The Bernoulli numbers with even indices n > 1
alternate the signs. Any Bernoulli number with an odd index n > 2 is 0.

Compute the even-indexed Bernoulli numbers with the indices from 0 to 10. Because these indices
are not symbolic objects, bernoulli returns floating-point results.

bernoulli(0:2:10)

ans =
1.0000 0.1667 -0.0333 0.0238 -0.0333 0.0758

Compute the same Bernoulli numbers for the indices converted to symbolic objects:

bernoulli(sym(0:2:10))

ans =
[ 1, 1/6, -1/30, 1/42, -1/30, 5/66]

Compute the odd-indexed Bernoulli numbers with the indices from 1 to 11:

bernoulli(sym(1:2:11))

ans =
[ -1/2, 0, 0, 0, 0, 0]

Bernoulli Polynomials

For the Bernoulli polynomials, use bernoulli with two input arguments.

Compute the first, second, and third Bernoulli polynomials in variables x, y, and z, respectively:

syms x y z
bernoulli(1, x)

7-99
7 Functions

bernoulli(2, y)
bernoulli(3, z)

ans =
x - 1/2

ans =
y^2 - y + 1/6

ans =
z^3 - (3*z^2)/2 + z/2

If the second argument is a number, bernoulli evaluates the polynomial at that number. Here, the
result is a floating-point number because the input arguments are not symbolic numbers:

bernoulli(2, 1/3)

ans =
-0.0556

To get the exact symbolic result, convert at least one of the numbers to a symbolic object:

bernoulli(2, sym(1/3))

ans =
-1/18

Plot Bernoulli Polynomials

Plot the first six Bernoulli polynomials.

syms x
fplot(bernoulli(0:5, x), [-0.8 1.8])
title('Bernoulli Polynomials')
grid on

7-100
 bernoulli

Handle Expressions Containing Bernoulli Polynomials

Many functions, such as diff and expand, handles expressions containing bernoulli.

Find the first and second derivatives of the Bernoulli polynomial:

syms n x
diff(bernoulli(n,x^2), x)

ans =
2*n*x*bernoulli(n - 1, x^2)

diff(bernoulli(n,x^2), x, x)

ans =
2*n*bernoulli(n - 1, x^2) +...
4*n*x^2*bernoulli(n - 2, x^2)*(n - 1)

Expand these expressions containing the Bernoulli polynomials:

expand(bernoulli(n, x + 3))

ans =
bernoulli(n, x) + (n*(x + 1)^n)/(x + 1) +...
(n*(x + 2)^n)/(x + 2) + (n*x^n)/x

expand(bernoulli(n, 3*x))

7-101
7 Functions

ans =
(3^n*bernoulli(n, x))/3 + (3^n*bernoulli(n, x + 1/3))/3 +...
(3^n*bernoulli(n, x + 2/3))/3

Input Arguments
n — Index of the Bernoulli number or polynomial
nonnegative integer | symbolic nonnegative integer | symbolic variable | symbolic expression |
symbolic function | symbolic vector | symbolic matrix

Index of the Bernoulli number or polynomial, specified as a nonnegative integer, symbolic

nonnegative integer, variable, expression, function, vector, or matrix. If n is a vector or matrix,
bernoulli returns Bernoulli numbers or polynomials for each element of n. If one input argument is
a scalar and the other one is a vector or a matrix, bernoulli(n,x) expands the scalar into a vector
or matrix of the same size as the other argument with all elements equal to that scalar.

x — Polynomial variable
symbolic variable | symbolic expression | symbolic function | symbolic vector | symbolic matrix

Polynomial variable, specified as a symbolic variable, expression, function, vector, or matrix. If x is a

vector or matrix, bernoulli returns Bernoulli numbers or polynomials for each element of x. When
you use the bernoulli function to find Bernoulli polynomials, at least one argument must be a
scalar or both arguments must be vectors or matrices of the same size. If one input argument is a
scalar and the other one is a vector or a matrix, bernoulli(n,x) expands the scalar into a vector or
matrix of the same size as the other argument with all elements equal to that scalar.

More About
Bernoulli Polynomials

The Bernoulli polynomials are defined as follows:

∞
text tn
= ∑ bernoulli n, x
n!
et − 1 n=0

Bernoulli Numbers

The Bernoulli numbers are defined as follows:

bernoulli n = bernoulli n, 0

Version History
Introduced in R2014a

See Also
euler

7-102
 bernstein

bernstein
Bernstein polynomials

Syntax
bernstein(f,n,t)
bernstein(g,n,t)
bernstein(g,var,n,t)

Description
bernstein(f,n,t) with a function handle f returns the nth-order Bernstein polynomial on page 7-
107 symsum(nchoosek(n,k)*t^k*(1-t)^(n-k)*f(k/n),k,0,n), evaluated at the point t. This
polynomial approximates the function f over the interval [0,1].

bernstein(g,n,t) with a symbolic expression or function g returns the nth-order Bernstein

polynomial, evaluated at the point t. This syntax regards g as a univariate function of the variable
determined by symvar(g,1).

If any argument is symbolic, bernstein converts all arguments except a function handle to symbolic,
and converts a function handle’s results to symbolic.

bernstein(g,var,n,t) with a symbolic expression or function g returns the approximating nth-

order Bernstein polynomial, regarding g as a univariate function of the variable var.

Examples
Approximation of Sine Function Specified as Function Handle

Approximate the sine function by the 10th- and 100th-degree Bernstein polynomials.

syms t
b10 = bernstein(@(t) sin(2*pi*t), 10, t);
b100 = bernstein(@(t) sin(2*pi*t), 100, t);

Plot sin(2*pi*t) and its approximations.

fplot(sin(2*pi*t),[0,1])
hold on
fplot(b10,[0,1])
fplot(b100,[0,1])

legend('sine function','10th-degree polynomial',...

'100th-degree polynomial')
title('Bernstein polynomials')
hold off

7-103
7 Functions

Approximation of Exponential Function Specified as Symbolic Expression

Approximate the exponential function by the second-order Bernstein polynomial in the variable t:
syms x t
bernstein(exp(x), 2, t)

ans =
(t - 1)^2 + t^2*exp(1) - 2*t*exp(1/2)*(t - 1)

Approximate the multivariate exponential function. When you approximate a multivariate function,
bernstein regards it as a univariate function of the default variable determined by symvar. The
default variable for the expression y*exp(x*y) is x:
syms x y t
symvar(y*exp(x*y), 1)

ans =
x

bernstein treats this expression as a univariate function of x:

bernstein(y*exp(x*y), 2, t)

ans =
y*(t - 1)^2 + t^2*y*exp(y) - 2*t*y*exp(y/2)*(t - 1)

To treat y*exp(x*y) as a function of the variable y, specify the variable explicitly:

7-104
 bernstein

bernstein(y*exp(x*y), y, 2, t)

ans =
t^2*exp(x) - t*exp(x/2)*(t - 1)

Approximation of Linear Ramp Specified as Symbolic Function

Approximate function f representing a linear ramp by the fifth-order Bernstein polynomials in the
variable t:

syms f(t)
f(t) = triangularPulse(1/4, 3/4, Inf, t);
p = bernstein(f, 5, t)

p =
7*t^3*(t - 1)^2 - 3*t^2*(t - 1)^3 - 5*t^4*(t - 1) + t^5

Simplify the result:

simplify(p)

ans =
-t^2*(2*t - 3)

Numerical Stability of Simplified Bernstein Polynomials

When you simplify a high-order symbolic Bernstein polynomial, the result often cannot be evaluated
in a numerically stable way.

Approximate this rectangular pulse function by the 100th-degree Bernstein polynomial, and then
simplify the result.

f = @(x)rectangularPulse(1/4,3/4,x);
b1 = bernstein(f, 100, sym('t'));
b2 = simplify(b1);

Convert the polynomial b1 and the simplified polynomial b2 to MATLAB® functions.

f1 = matlabFunction(b1);
f2 = matlabFunction(b2);

Compare the plot of the original rectangular pulse function, its numerically stable Bernstein
representation f1, and its simplified version f2. The simplified version is not numerically stable.

t = 0:0.001:1;
plot(t, f(t), t, f1(t), t, f2(t))
hold on
legend('original function','Bernstein polynomial',...
'simplified Bernstein polynomial')
hold off

7-105
7 Functions

Input Arguments
f — Function to be approximated by a polynomial
function handle

Function to be approximated by a polynomial, specified as a function handle. f must accept one

scalar input argument and return a scalar value.

g — Function to be approximated by a polynomial

symbolic expression | symbolic function

Function to be approximated by a polynomial, specified as a symbolic expression or function.

n — Bernstein polynomial order

nonnegative integer

Bernstein polynomial order, specified as a nonnegative number.

t — Evaluation point
number | symbolic number | symbolic variable | symbolic expression | symbolic function

Evaluation point, specified as a number, symbolic number, variable, expression, or function. If t is a

symbolic function, the evaluation point is the mathematical expression that defines t. To extract the
mathematical expression defining t, bernstein uses formula(t).

7-106
 bernstein

var — Free variable

symbolic variable

Free variable, specified as a symbolic variable.

More About
Bernstein Polynomials

A Bernstein polynomial is a linear combination of Bernstein basis polynomials.

A Bernstein polynomial of degree n is defined as follows:

n
Bt = ∑ βkbk, n t .
k=0

Here,

n k n−k
bk, n t = t 1−t , k = 0, …, n
k

n
are the Bernstein basis polynomials, and is a binomial coefficient.
k

The coefficients βk are called Bernstein coefficients or Bezier coefficients.

If f is a continuous function on the interval [0, 1] and

n
k
Bn f t = ∑ f b
n k, n
t
k=0

is the approximating Bernstein polynomial, then

lim Bn f t = f t
n ∞

uniformly in t on the interval [0, 1].

Tips
• Symbolic polynomials returned for symbolic t are numerically stable when substituting numerical
values between 0 and 1 for t.
• If you simplify a symbolic Bernstein polynomial, the result can be unstable when substituting
numerical values for the curve parameter t.

Version History
Introduced in R2013b

See Also
bernsteinMatrix | formula | nchoosek | symvar | symsum

7-107
7 Functions

bernsteinMatrix
Bernstein matrix

Syntax
B = bernsteinMatrix(n,t)

Description
B = bernsteinMatrix(n,t), where t is a vector, returns the length(t)-by-(n+1) Bernstein
matrix B, such that B(i,k+1)= nchoosek(n,k)*t(i)^k*(1-t(i))^(n-k). Here, the index i
runs from 1 to length(t), and the index k runs from 0 to n.

The Bernstein matrix is also called the Bezier matrix.

Use Bernstein matrices to construct Bezier curves:

bezierCurve = bernsteinMatrix(n, t)*P

Here, the n+1 rows of the matrix P specify the control points of the Bezier curve. For example, to
construct the second-order 3-D Bezier curve, specify the control points as:

P = [p0x, p0y, p0z; p1x, p1y, p1z; p2x, p2y, p2z]

Examples

2-D Bezier Curve

Plot the fourth-order Bezier curve specified by the control points p0 = [0 1], p1 = [4 3], p2 =
[6 2], p3 = [3 0], p4 = [2 4]. Create a matrix with each row representing a control point.

P = [0 1; 4 3; 6 2; 3 0; 2 4];

Compute the fourth-order Bernstein matrix B.

syms t
B = bernsteinMatrix(4,t);

Construct the Bezier curve.

bezierCurve = simplify(B*P);

Plot the curve adding the control points to the plot.

fplot(bezierCurve(1), bezierCurve(2), [0, 1])

hold on
scatter(P(:,1), P(:,2),'filled')
title('Fourth-order Bezier curve')
hold off

7-108
 bernsteinMatrix

3-D Bezier Curve

Construct the third-order Bezier curve specified by the 4-by-3 matrix P of control points. Each control
point corresponds to a row of the matrix P.

P = [0 0 0; 2 2 2; 2 -1 1; 6 1 3];

Compute the third-order Bernstein matrix.

syms t
B = bernsteinMatrix(3,t);

Construct the Bezier curve.

bezierCurve = simplify(B*P);

Plot the curve adding the control points to the plot.

fplot3(bezierCurve(1), bezierCurve(2), bezierCurve(3), [0, 1])

hold on
scatter3(P(:,1), P(:,2), P(:,3),'filled')
hold off

7-109
7 Functions

3-D Bezier Curve with the Evaluation Point Specified as a Vector

Construct the third-order Bezier curve with the evaluation point specified by the following 1-by-101
vector t.

t = 0:1/100:1;

Compute the third-order 101-by-4 Bernstein matrix and specify the control points.

B = bernsteinMatrix(3,t);
P = [0 0 0; 2 2 2; 2 -1 1; 6 1 3];

Construct and plot the Bezier curve. Add grid lines and control points to the plot.

bezierCurve = B*P;
plot3(bezierCurve(:,1), bezierCurve(:,2), bezierCurve(:,3))
hold on
grid
scatter3(P(:,1), P(:,2), P(:,3),'filled')
hold off

7-110
 bernsteinMatrix

Input Arguments
n — Approximation order
nonnegative integer

Approximation order, specified as a nonnegative integer.

t — Evaluation point
number | vector | symbolic number | symbolic variable | symbolic expression | symbolic vector

Evaluation point, specified as a number, symbolic number, variable, expression, or vector.

Output Arguments
B — Bernstein matrix
matrix

Bernstein matrix, returned as a length(t)-by-n+1 matrix.

Version History
Introduced in R2013b

7-111
7 Functions

See Also
bernstein | nchoosek | symvar | symsum

7-112
 besselh

besselh
Bessel function of third kind (Hankel function) for symbolic expressions

Syntax
H = besselh(nu,K,z)
H = besselh(nu,z)
H = besselh(nu,K,z,1)

Description

H = besselh(nu,K,z) computes the Hankel function Hν(K)(z), where K = 1 or 2, for each element of
the complex array z. The output H has the symbolic data type if any input argument is symbolic. See
“Bessel’s Equation” on page 7-115.

H = besselh(nu,z) uses K = 1.

H = besselh(nu,K,z,1) scales Hν(K)(z) by exp(-i*z) if K = 1, and by exp(+i*z) if K = 2.

Examples

Compute Hankel Function

Specify the Hankel function for a symbolic variable.

syms z
H = besselh(3/2,1,z)

H =
i
2 ez i 1 + z
−
z π

Evaluate the function symbolically and numerically at the point z = 1 + 2i.

Hval = subs(H,z,1+2i)

Hval =
7 1
2 e−2 + i − 5 − 5 i
1+2 i π

vpa(Hval)

ans = −0.084953341280586443678471523210602 − 0.056674847869835575940327724800155 i

Specify the function without the second argument, K = 1.

H2 = besselh(3/2,z)

H2 =

7-113
7 Functions

i
2 ez i 1 + z
−
z π

Notice that the functions H and H2 are identical.

Scale the function by e−iz by using the four-argument syntax.

Hnew = besselh(3/2,1,z,1)

Hnew =
i
2 1+ z
−
z π

Find the derivative of H.

diffH = diff(H)

diffH =
i i
2 ez i i 2 ez i 1 + z i 2 ez i 1 + z
− +
z5/2 π z π 2 z3/2 π

Input Arguments
nu — Hankel function order
symbolic array | double array

Hankel function order, specified as a symbolic array or double array. 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
size.
Example: nu = 3*sym(pi)/2

K — Kind of Hankel function

symbolic 1 or 2 | double 1 or 2

Kind of Hankel function, specified as a symbolic or double 1 or 2. K identifies the sign of the added
Bessel function Y:

Hν(1)(z) = Jν(z) + iY ν(z)

Hν(2)(z) = Jν(z) − iY ν(z) .

Example: K = sym(2)

z — Hankel function argument

symbolic array | double array

Hankel function argument, specified as a symbolic array or double array. 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
size.
Example: z = sym(1+1i)

7-114
 besselh

More About
Bessel’s Equation

The differential equation

2
d w dw
z2 +z + z2 − ν2 w = 0,
dz 2 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 ν. 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

Hν(1)(z) = Jν(z) + iY ν(z)

Hν(2)(z) = Jν(z) − iY ν(z) .

Here, Jν(z) is besselj, and Yν(z) is bessely.

Version History
Introduced in R2018b

References
[1] Abramowitz, M., and I. A. Stegun. Handbook of Mathematical Functions. National Bureau of
Standards, Applied Math. Series #55, Dover Publications, 1965.

See Also
besseli | besselj | besselk | bessely

7-115
7 Functions

besseli
Modified Bessel function of the first kind for symbolic expressions

Syntax
besseli(nu,z)

Description
besseli(nu,z) returns the modified Bessel function of the first kind on page 7-119, Iν(z).

Examples
Find Modified Bessel Function of First Kind

Compute the modified Bessel functions of the first kind for these numbers. Because these numbers
are not symbolic objects, you get floating-point results.
[besseli(0, 5), besseli(-1, 2), besseli(1/3, 7/4), besseli(1, 3/2 + 2*i)]

ans =
27.2399 + 0.0000i 1.5906 + 0.0000i 1.7951 + 0.0000i -0.1523 + 1.0992i

Compute the modified Bessel functions of the first kind for the numbers converted to symbolic
objects. For most symbolic (exact) numbers, besseli returns unresolved symbolic calls.

[besseli(sym(0), 5), besseli(sym(-1), 2),...

besseli(1/3, sym(7/4)), besseli(sym(1), 3/2 + 2*i)]

ans =
[ besseli(0, 5), besseli(1, 2), besseli(1/3, 7/4), besseli(1, 3/2 + 2i)]

For symbolic variables and expressions, besseli also returns unresolved symbolic calls:

syms x y
[besseli(x, y), besseli(1, x^2), besseli(2, x - y), besseli(x^2, x*y)]

ans =
[ besseli(x, y), besseli(1, x^2), besseli(2, x - y), besseli(x^2, x*y)]

Solve Bessel Differential Equation for Modified Bessel Functions

Solve this second-order differential equation. The solutions are the modified Bessel functions of the
first and the second kind.

syms nu w(z)
dsolve(z^2*diff(w, 2) + z*diff(w) -(z^2 + nu^2)*w == 0)

ans =
C2*besseli(nu, z) + C3*besselk(nu, z)

Verify that the modified Bessel function of the first kind is a valid solution of the modified Bessel
differential equation.

7-116
 besseli

syms nu z
isAlways(z^2*diff(besseli(nu, z), z, 2) + z*diff(besseli(nu, z), z)...
- (z^2 + nu^2)*besseli(nu, z) == 0)

ans =
logical
1

Special Values of Modified Bessel Function of First Kind

If the first parameter is an odd integer multiplied by 1/2, besseli rewrites the Bessel functions in
terms of elementary functions:

syms x
besseli(1/2, x)

ans =
(2^(1/2)*sinh(x))/(x^(1/2)*pi^(1/2))

besseli(-1/2, x)

ans =
(2^(1/2)*cosh(x))/(x^(1/2)*pi^(1/2))

besseli(-3/2, x)

ans =
(2^(1/2)*(sinh(x) - cosh(x)/x))/(x^(1/2)*pi^(1/2))

besseli(5/2, x)

ans =
-(2^(1/2)*((3*cosh(x))/x - sinh(x)*(3/x^2 + 1)))/(x^(1/2)*pi^(1/2))

Differentiate Modified Bessel Function of First Kind

Differentiate the expressions involving the modified Bessel functions of the first kind:

syms x y
diff(besseli(1, x))
diff(diff(besseli(0, x^2 + x*y -y^2), x), y)

ans =
besseli(0, x) - besseli(1, x)/x

ans =
besseli(1, x^2 + x*y - y^2) +...
(2*x + y)*(besseli(0, x^2 + x*y - y^2)*(x - 2*y) -...
(besseli(1, x^2 + x*y - y^2)*(x - 2*y))/(x^2 + x*y - y^2))

Bessel Function for Matrix Input

Call besseli for the matrix A and the value 1/2. The result is a matrix of the modified Bessel
functions besseli(1/2, A(i,j)).

syms x
A = [-1, pi; x, 0];
besseli(1/2, A)

7-117
7 Functions

ans =
[ (2^(1/2)*sinh(1)*1i)/pi^(1/2), (2^(1/2)*sinh(pi))/pi]
[ (2^(1/2)*sinh(x))/(x^(1/2)*pi^(1/2)), 0]

Plot the Modified Bessel Functions of the First Kind

Plot the modified Bessel functions of the first kind for v = 0, 1, 2, 3.

syms x y
fplot(besseli(0:3, x))
axis([0 4 -0.1 4])
grid on

ylabel('I_v(x)')
legend('I_0','I_1','I_2','I_3', 'Location','Best')
title('Modified Bessel functions of the first kind')

Input Arguments
nu — Input
number | vector | matrix | multidimensional array | symbolic number | symbolic array | symbolic
function | symbolic expression

7-118
 besseli

Input, specified as a number, vector, matrix, array, or a symbolic number, variable, expression,
function, or array. If nu is a vector or matrix, besseli returns the modified Bessel function of the
first kind for each element of nu.

z — Input
number | vector | matrix | multidimensional array | symbolic number | symbolic array | symbolic
function | symbolic expression

Input, specified as a number, vector, matrix, array, or a symbolic number, variable, expression,
function, or array. If nu is a vector or matrix, besseli returns the modified Bessel function of the
first kind for each element of nu.

More About
Modified Bessel Functions of the First Kind

The modified Bessel differential equation

2
d w dw
z2 +z − z2 + ν2 w = 0
dz 2 dz

has two linearly independent solutions. These solutions are represented by the modified Bessel
functions of the first kind, Iν(z), and the modified Bessel functions of the second kind, Kν(z):

w z = C1Iν z + C2Kν z

This formula is the integral representation of the modified Bessel functions of the first kind:

ν π
Iν z =
z/2
πΓ ν + 1/2 ∫e
0
zcos t sin t
2ν
dt

Tips
• Calling besseli for a number that is not a symbolic object invokes the MATLAB besseli
function.
• At least one input argument must be a scalar or both arguments must be vectors or matrices of
the same size. If one input argument is a scalar and the other one is a vector or a matrix,
besseli(nu,z) expands the scalar into a vector or matrix of the same size as the other
argument with all elements equal to that scalar.

Version History
Introduced in R2014a

References
[1] Olver, F. W. J. “Bessel Functions of Integer Order.” Handbook of Mathematical Functions with
Formulas, Graphs, and Mathematical Tables. (M. Abramowitz and I. A. Stegun, eds.). New
York: Dover, 1972.

7-119
7 Functions

[2] Antosiewicz, H. A. “Bessel Functions of Fractional Order.” Handbook of Mathematical Functions

with Formulas, Graphs, and Mathematical Tables. (M. Abramowitz and I. A. Stegun, eds.).
New York: Dover, 1972.

See Also
airy | besselh | besselj | besselk | bessely

7-120
 besselj

besselj
Bessel function of the first kind for symbolic expressions

Syntax
besselj(nu,z)

Description
besselj(nu,z) returns the Bessel function of the first kind on page 7-124, Jν(z).

Examples
Find Bessel Function of First Kind

Compute the Bessel functions of the first kind for these numbers. Because these numbers are floating
point, you get floating-point results.

[besselj(0,5) besselj(-1,2) besselj(1/3,7/4) besselj(1,3/2+2*i)]

ans =
-0.1776 + 0.0000i -0.5767 + 0.0000i 0.5496 + 0.0000i 1.6113 + 0.3982i

Compute the Bessel functions of the first kind for the numbers converted to symbolic form. For most
symbolic (exact) numbers, besselj returns unresolved symbolic calls.

[besselj(sym(0),5) besselj(sym(-1),2)...
besselj(1/3,sym(7/4)) besselj(sym(1),3/2+2*i)]

ans =
[ besselj(0, 5), -besselj(1, 2), besselj(1/3, 7/4), besselj(1, 3/2 + 2i)]

For symbolic variables and expressions, besselj also returns unresolved symbolic calls.

syms x y
[besselj(x,y) besselj(1,x^2) besselj(2,x-y) besselj(x^2,x*y)]

ans =
[ besselj(x, y), besselj(1, x^2), besselj(2, x - y), besselj(x^2, x*y)]

Solve Bessel Differential Equation for Bessel Functions

Solve this second-order differential equation. The solutions are the Bessel functions of the first and
the second kind.

syms nu w(z)
ode = z^2*diff(w,2) + z*diff(w) +(z^2-nu^2)*w == 0;
dsolve(ode)

ans =
C2*besselj(nu, z) + C3*bessely(nu, z)

Verify that the Bessel function of the first kind is a valid solution of the Bessel differential equation.

7-121
7 Functions

cond = subs(ode,w,besselj(nu,z));
isAlways(cond)

ans =
logical
1

Special Values of Bessel Function of First Kind

Show that if the first parameter is an odd integer multiplied by 1/2, besselj rewrites the Bessel
functions in terms of elementary functions.

syms x
besselj(1/2,x)

ans =
(2^(1/2)*sin(x))/(x^(1/2)*pi^(1/2))

besselj(-1/2,x)

ans =
(2^(1/2)*cos(x))/(x^(1/2)*pi^(1/2))

besselj(-3/2,x)

ans =
-(2^(1/2)*(sin(x) + cos(x)/x))/(x^(1/2)*pi^(1/2))

besselj(5/2,x)

ans =
-(2^(1/2)*((3*cos(x))/x - sin(x)*(3/x^2 - 1)))/(x^(1/2)*pi^(1/2))

Differentiate Bessel Function of First Kind

Differentiate expressions involving the Bessel functions of the first kind.

syms x y
diff(besselj(1,x))

ans =
besselj(0, x) - besselj(1, x)/x

diff(diff(besselj(0,x^2+x*y-y^2), x), y)

ans =
- besselj(1, x^2 + x*y - y^2) -...
(2*x + y)*(besselj(0, x^2 + x*y - y^2)*(x - 2*y) -...
(besselj(1, x^2 + x*y - y^2)*(x - 2*y))/(x^2 + x*y - y^2))

Find Bessel Function for Matrix Input

Call besselj for the matrix A and the value 1/2. besselj acts element-wise to return matrix of
Bessel functions.

syms x
A = [-1, pi; x, 0];
besselj(1/2, A)

7-122
 besselj

ans =
[ (2^(1/2)*sin(1)*1i)/pi^(1/2), 0]
[ (2^(1/2)*sin(x))/(x^(1/2)*pi^(1/2)), 0]

Plot Bessel Functions of First Kind

Plot the Bessel functions of the first kind for 0, 1, 2, 3.

syms x y
fplot(besselj(0:3, x))
axis([0 10 -0.5 1.1])
grid on

ylabel('J_v(x)')
legend('J_0','J_1','J_2','J_3', 'Location','Best')
title('Bessel functions of the first kind')

Input Arguments
nu — Input
number | vector | matrix | array | symbolic number | symbolic variable | symbolic array | symbolic
function | symbolic expression

Input, specified as a number, vector, matrix, or array, or a symbolic number, variable, array, function,
or expression.

7-123
7 Functions

If nu is a vector or matrix, besselj returns the modified Bessel function of the first kind for each
element of nu.

z — Input
number | vector | matrix | array | symbolic number | symbolic variable | symbolic array | symbolic
function | symbolic expression

Input, specified as a number, vector, matrix, or array, or a symbolic number, variable, array, function,
or expression.

If nu is a vector or matrix, besselj returns the modified Bessel function of the first kind for each
element of nu.

More About
Bessel Functions of the First Kind

The Bessel functions are solutions of the Bessel differential equation.

2
d w dw
z2 +z + z2 − ν2 w = 0
dz2 dz

These solutions are the Bessel functions of the first kind, Jν(z), and the Bessel functions of the second
kind, Yν(z).

w z = C1 Jν z + C2Y ν z

This formula is the integral representation of the Bessel functions of the first kind.

ν π
Jν z =
z/2
πΓ ν + 1/2 ∫ cos zcos t
0
sin t
2ν
dt

Tips
• Calling besselj for a number that is not a symbolic object invokes the MATLAB besselj
function.
• At least one input argument must be a scalar or both arguments must be vectors or matrices of
the same size. If one input argument is a scalar and the other one is a vector or a matrix,
besselj(nu,z) expands the scalar into a vector or matrix of the same size as the other
argument with all elements equal to that scalar.

Version History
Introduced in R2014a

References
[1] Olver, F. W. J. “Bessel Functions of Integer Order.” Handbook of Mathematical Functions with
Formulas, Graphs, and Mathematical Tables. (M. Abramowitz and I. A. Stegun, eds.). New
York: Dover, 1972.

7-124
 besselj

[2] Antosiewicz, H. A. “Bessel Functions of Fractional Order.” Handbook of Mathematical Functions

with Formulas, Graphs, and Mathematical Tables. (M. Abramowitz and I. A. Stegun, eds.).
New York: Dover, 1972.

See Also
airy | besselh | besseli | besselk | bessely

7-125
7 Functions

besselk
Modified Bessel function of the second kind for symbolic expressions

Syntax
besselk(nu,z)

Description
besselk(nu,z) returns the modified Bessel function of the second kind on page 7-129, Kν(z).

Examples
Find Modified Bessel Function of Second Kind

Compute the modified Bessel functions of the second kind for these numbers. Because these numbers
are not symbolic objects, you get floating-point results.

[besselk(0, 5), besselk(-1, 2), besselk(1/3, 7/4),...

besselk(1, 3/2 + 2*i)]
ans =
0.0037 + 0.0000i 0.1399 + 0.0000i 0.1594 + 0.0000i -0.1620 - 0.1066i

Compute the modified Bessel functions of the second kind for the numbers converted to symbolic
objects. For most symbolic (exact) numbers, besselk returns unresolved symbolic calls.

[besselk(sym(0), 5), besselk(sym(-1), 2),...

besselk(1/3, sym(7/4)), besselk(sym(1), 3/2 + 2*i)]

ans =
[ besselk(0, 5), besselk(1, 2), besselk(1/3, 7/4), besselk(1, 3/2 + 2i)]

For symbolic variables and expressions, besselk also returns unresolved symbolic calls:

syms x y
[besselk(x, y), besselk(1, x^2), besselk(2, x - y), besselk(x^2, x*y)]

ans =
[ besselk(x, y), besselk(1, x^2), besselk(2, x - y), besselk(x^2, x*y)]

Special Values of Modified Bessel Function of Second Kind

If the first parameter is an odd integer multiplied by 1/2, besselk rewrites the Bessel functions in
terms of elementary functions:

syms x
besselk(1/2, x)

ans =
(2^(1/2)*pi^(1/2)*exp(-x))/(2*x^(1/2))

besselk(-1/2, x)

7-126
 besselk

ans =
(2^(1/2)*pi^(1/2)*exp(-x))/(2*x^(1/2))

besselk(-3/2, x)

ans =
(2^(1/2)*pi^(1/2)*exp(-x)*(1/x + 1))/(2*x^(1/2))

besselk(5/2, x)

ans =
(2^(1/2)*pi^(1/2)*exp(-x)*(3/x + 3/x^2 + 1))/(2*x^(1/2))

Solve Bessel Differential Equation for Bessel Functions

Solve this second-order differential equation. The solutions are the modified Bessel functions of the
first and the second kind.
syms nu w(z)
dsolve(z^2*diff(w, 2) + z*diff(w) -(z^2 + nu^2)*w == 0)

ans =
C2*besseli(nu, z) + C3*besselk(nu, z)

Verify that the modified Bessel function of the second kind is a valid solution of the modified Bessel
differential equation:
syms nu z
isAlways(z^2*diff(besselk(nu, z), z, 2) + z*diff(besselk(nu, z), z)...
- (z^2 + nu^2)*besselk(nu, z) == 0)

ans =
logical
1

Differentiate Modified Bessel Function of Second Kind

Differentiate the expressions involving the modified Bessel functions of the second kind:
syms x y
diff(besselk(1, x))
diff(diff(besselk(0, x^2 + x*y -y^2), x), y)

ans =
- besselk(1, x)/x - besselk(0, x)

ans =
(2*x + y)*(besselk(0, x^2 + x*y - y^2)*(x - 2*y) +...
(besselk(1, x^2 + x*y - y^2)*(x - 2*y))/(x^2 + x*y - y^2)) -...
besselk(1, x^2 + x*y - y^2)

Find Bessel Function for Matrix Input

Call besselk for the matrix A and the value 1/2. The result is a matrix of the modified Bessel
functions besselk(1/2, A(i,j)).
syms x
A = [-1, pi; x, 0];
besselk(1/2, A)

7-127
7 Functions

ans =
[ -(2^(1/2)*pi^(1/2)*exp(1)*1i)/2, (2^(1/2)*exp(-pi))/2]
[ (2^(1/2)*pi^(1/2)*exp(-x))/(2*x^(1/2)), Inf]

Plot Modified Bessel Functions of Second Kind

Plot the modified Bessel functions of the second kind for v = 0, 1, 2, 3.

syms x y
fplot(besselk(0:3, x))
axis([0 4 0 4])
grid on

ylabel('K_v(x)')
legend('K_0','K_1','K_2','K_3', 'Location','Best')
title('Modified Bessel functions of the second kind')

Input Arguments
nu — Input
number | vector | matrix | multidimensional array | symbolic number | symbolic array | symbolic
function | symbolic expression

7-128
 besselk

Input, specified as a number, vector, matrix, array, or a symbolic number, variable, expression,
function, or array. If nu is a vector or matrix, besseli returns the modified Bessel function of the
first kind for each element of nu.

z — Input
number | vector | matrix | multidimensional array | symbolic number | symbolic array | symbolic
function | symbolic expression

Input, specified as a number, vector, matrix, array, or a symbolic number, variable, expression,
function, or array. If nu is a vector or matrix, besseli returns the modified Bessel function of the
first kind for each element of nu.

More About
Modified Bessel Functions of the Second Kind

The modified Bessel differential equation

2
d w dw
z2 +z − z2 + ν2 w = 0
dz 2 dz

has two linearly independent solutions. These solutions are represented by the modified Bessel
functions of the first kind, Iν(z), and the modified Bessel functions of the second kind, Kν(z):

w z = C1Iν z + C2Kν z

The modified Bessel functions of the second kind are defined via the modified Bessel functions of the
first kind:

π/2
Kν z = I z − Iν z
sin νπ −ν

Here Iν(z) are the modified Bessel functions of the first kind:

ν π
Iν z =
z/2
πΓ ν + 1/2 ∫e
0
zcos t sin t
2ν
dt

Tips
• Calling besselk for a number that is not a symbolic object invokes the MATLAB besselk
function.
• At least one input argument must be a scalar or both arguments must be vectors or matrices of
the same size. If one input argument is a scalar and the other one is a vector or a matrix,
besselk(nu,z) expands the scalar into a vector or matrix of the same size as the other
argument with all elements equal to that scalar.

Version History
Introduced in R2014a

7-129
7 Functions

References
[1] Olver, F. W. J. “Bessel Functions of Integer Order.” Handbook of Mathematical Functions with
Formulas, Graphs, and Mathematical Tables. (M. Abramowitz and I. A. Stegun, eds.). New
York: Dover, 1972.

[2] Antosiewicz, H. A. “Bessel Functions of Fractional Order.” Handbook of Mathematical Functions

with Formulas, Graphs, and Mathematical Tables. (M. Abramowitz and I. A. Stegun, eds.).
New York: Dover, 1972.

See Also
airy | besselh | besseli | besselj | bessely

7-130
 bessely

bessely
Bessel function of the second kind for symbolic expressions

Syntax
bessely(nu,z)

Description
bessely(nu,z) returns the Bessel function of the second kind on page 7-134, Yν(z).

Examples
Find Bessel Function of Second Kind

Compute the Bessel functions of the second kind for these numbers. Because these numbers are not
symbolic objects, you get floating-point results.
[bessely(0, 5), bessely(-1, 2), bessely(1/3, 7/4), bessely(1, 3/2 + 2*i)]

ans =
-0.3085 + 0.0000i 0.1070 + 0.0000i 0.2358 + 0.0000i -0.4706 + 1.5873i

Compute the Bessel functions of the second kind for the numbers converted to symbolic objects. For
most symbolic (exact) numbers, bessely returns unresolved symbolic calls.

[bessely(sym(0), 5), bessely(sym(-1), 2),...

bessely(1/3, sym(7/4)), bessely(sym(1), 3/2 + 2*i)]

ans =
[ bessely(0, 5), -bessely(1, 2), bessely(1/3, 7/4), bessely(1, 3/2 + 2i)]

For symbolic variables and expressions, bessely also returns unresolved symbolic calls:

syms x y
[bessely(x, y), bessely(1, x^2), bessely(2, x - y), bessely(x^2, x*y)]

ans =
[ bessely(x, y), bessely(1, x^2), bessely(2, x - y), bessely(x^2, x*y)]

Solve Bessel Differential Equation for Bessel Functions

Solve this second-order differential equation. The solutions are the Bessel functions of the first and
the second kind.

syms nu w(z)
dsolve(z^2*diff(w, 2) + z*diff(w) +(z^2 - nu^2)*w == 0)

ans =
C2*besselj(nu, z) + C3*bessely(nu, z)

Verify that the Bessel function of the second kind is a valid solution of the Bessel differential equation:

7-131
7 Functions

syms nu z
isAlways(z^2*diff(bessely(nu, z), z, 2) + z*diff(bessely(nu, z), z)...
+ (z^2 - nu^2)*bessely(nu, z) == 0)

ans =
logical
1

Special Values of Bessel Function of Second Kind

If the first parameter is an odd integer multiplied by 1/2, bessely rewrites the Bessel functions in
terms of elementary functions:

syms x
bessely(1/2, x)

ans =
-(2^(1/2)*cos(x))/(x^(1/2)*pi^(1/2))

bessely(-1/2, x)

ans =
(2^(1/2)*sin(x))/(x^(1/2)*pi^(1/2))

bessely(-3/2, x)

ans =
(2^(1/2)*(cos(x) - sin(x)/x))/(x^(1/2)*pi^(1/2))

bessely(5/2, x)

ans =
-(2^(1/2)*((3*sin(x))/x + cos(x)*(3/x^2 - 1)))/(x^(1/2)*pi^(1/2))

Differentiate Bessel Functions of Second Kind

Differentiate the expressions involving the Bessel functions of the second kind:

syms x y
diff(bessely(1, x))
diff(diff(bessely(0, x^2 + x*y -y^2), x), y)

ans =
bessely(0, x) - bessely(1, x)/x

ans =
- bessely(1, x^2 + x*y - y^2) -...
(2*x + y)*(bessely(0, x^2 + x*y - y^2)*(x - 2*y) -...
(bessely(1, x^2 + x*y - y^2)*(x - 2*y))/(x^2 + x*y - y^2))

Find Bessel Function for Matrix Input

Call bessely for the matrix A and the value 1/2. The result is a matrix of the Bessel functions
bessely(1/2, A(i,j)).

syms x
A = [-1, pi; x, 0];
bessely(1/2, A)

7-132
 bessely

ans =
[ (2^(1/2)*cos(1)*1i)/pi^(1/2), 2^(1/2)/pi]
[ -(2^(1/2)*cos(x))/(x^(1/2)*pi^(1/2)), Inf]

Plot Bessel Functions of Second Kind

Plot the Bessel functions of the second kind for v = 0, 1, 2, 3.

syms x y
fplot(bessely(0:3,x))
axis([0 10 -1 0.6])
grid on

ylabel('Y_v(x)')
legend('Y_0','Y_1','Y_2','Y_3', 'Location','Best')
title('Bessel functions of the second kind')

Input Arguments
nu — Input
number | vector | matrix | array | symbolic number | symbolic variable | symbolic array | symbolic
function | symbolic expression

Input, specified as a number, vector, matrix, or array, or a symbolic number, variable, array, function,
or expression.

7-133
7 Functions

If nu is a vector or matrix, bessely returns the Bessel function of the second kind for each element
of nu.

z — Input
number | vector | matrix | array | symbolic number | symbolic variable | symbolic array | symbolic
function | symbolic expression

Input, specified as a number, vector, matrix, or array, or a symbolic number, variable, array, function,
or expression.

If z is a vector or matrix, bessely returns the Bessel function of the second kind for each element of
z.

More About
Bessel Function of the Second Kind

The Bessel differential equation

2
d w dw
z2 +z + z2 − ν2 w = 0
dz 2 dz

has two linearly independent solutions. These solutions are represented by the Bessel functions of the
first kind, Jν(z), and the Bessel functions of the second kind, Yν(z):

w z = C1 Jν z + C2Y ν z

The Bessel functions of the second kind are defined via the Bessel functions of the first kind:

Jν z cos νπ − J−ν z
Yν z =
sin νπ

Here Jν(z) are the Bessel function of the first kind:

ν π
Jν z =
z/2
πΓ ν + 1/2 ∫ cos zcos t
0
sin t
2ν
dt

Tips
• Calling bessely for a number that is not a symbolic object invokes the MATLAB bessely
function.

At least one input argument must be a scalar or both arguments must be vectors or matrices of
the same size. If one input argument is a scalar and the other one is a vector or a matrix,
bessely(nu,z) expands the scalar into a vector or matrix of the same size as the other
argument with all elements equal to that scalar.

Version History
Introduced in R2014a

7-134
 bessely

References
[1] Olver, F. W. J. “Bessel Functions of Integer Order.” Handbook of Mathematical Functions with
Formulas, Graphs, and Mathematical Tables. (M. Abramowitz and I. A. Stegun, eds.). New
York: Dover, 1972.

[2] Antosiewicz, H. A. “Bessel Functions of Fractional Order.” Handbook of Mathematical Functions

with Formulas, Graphs, and Mathematical Tables. (M. Abramowitz and I. A. Stegun, eds.).
New York: Dover, 1972.

See Also
airy | besselh | besseli | besselj | besselk

7-135
7 Functions

beta
Beta function

Syntax
beta(x,y)

Description
beta(x,y) returns the beta function on page 7-138 of x and y.

Examples
Compute Beta Function for Numeric Inputs

Compute the beta function for these numbers. Because these numbers are not symbolic objects, you
get floating-point results:
[beta(1, 5), beta(3, sqrt(2)), beta(pi, exp(1)), beta(0, 1)]

ans =
0.2000 0.1716 0.0379 Inf

Compute Beta Function for Symbolic Inputs

Compute the beta function for the numbers converted to symbolic objects:
[beta(sym(1), 5), beta(3, sym(2)), beta(sym(4), sym(4))]

ans =
[ 1/5, 1/12, 1/140]

If one or both parameters are complex numbers, convert these numbers to symbolic objects:
[beta(sym(i), 3/2), beta(sym(i), i), beta(sym(i + 2), 1 - i)]

ans =
[ (pi^(1/2)*gamma(1i))/(2*gamma(3/2 + 1i)), gamma(1i)^2/gamma(2i),...
(pi*(1/2 + 1i/2))/sinh(pi)]

Compute Beta Function for Negative Parameters

Compute the beta function for negative parameters. If one or both arguments are negative numbers,
convert these numbers to symbolic objects:
[beta(sym(-3), 2), beta(sym(-1/3), 2), beta(sym(-3), 4), beta(sym(-3), -2)]

ans =
[ 1/6, -9/2, Inf, Inf]

Compute Beta Function for Matrix Inputs

Call beta for the matrix A and the value 1. The result is a matrix of the beta functions
beta(A(i,j),1):

7-136
 beta

A = sym([1 2; 3 4]);
beta(A,1)

ans =
[ 1, 1/2]
[ 1/3, 1/4]

Differentiate Beta Function

Differentiate the beta function, then substitute the variable t with the value 2/3 and approximate the
result using vpa:

syms t
u = diff(beta(t^2 + 1, t))
vpa(subs(u, t, 2/3), 10)

u =
beta(t, t^2 + 1)*(psi(t) + 2*t*psi(t^2 + 1) -...
psi(t^2 + t + 1)*(2*t + 1))

ans =
-2.836889094

Expand Beta Function

Expand these beta functions:

syms x y
expand(beta(x, y))
expand(beta(x + 1, y - 1))

ans =
(gamma(x)*gamma(y))/gamma(x + y)

ans =
-(x*gamma(x)*gamma(y))/(gamma(x + y) - y*gamma(x + y))

Input Arguments
x — Input
number | vector | matrix | array | symbolic number | symbolic variable | symbolic array | symbolic
function | symbolic expression

Input, specified as a number, vector, matrix, or array, or a symbolic number, variable, array, function,
or expression.

If x is a vector or matrix, beta returns the beta function for each element of x.

y — Input
number | vector | matrix | array | symbolic number | symbolic variable | symbolic array | symbolic
function | symbolic expression

Input, specified as a number, vector, matrix, or array, or a symbolic number, variable, array, function,
or expression.

If y is a vector or matrix, beta returns the beta function for each element of y.

7-137
7 Functions

More About
Beta Function

This integral defines the beta function:

1
Β x, y = ∫t
0
x−1
1−t
y−1
dt =
ΓxΓ y
Γ x+y

Tips
• The beta function is uniquely defined for positive numbers and complex numbers with positive real
parts. It is approximated for other numbers.
• Calling beta for numbers that are not symbolic objects invokes the MATLAB beta function. This
function accepts real arguments only. If you want to compute the beta function for complex
numbers, use sym to convert the numbers to symbolic objects, and then call beta for those
symbolic objects.
• If one or both parameters are negative numbers, convert these numbers to symbolic objects using
sym, and then call beta for those symbolic objects.
• If the beta function has a singularity, beta returns the positive infinity Inf.
• beta(sym(0),0), beta(0,sym(0)), and beta(sym(0),sym(0)) return NaN.
• beta(x,y) = beta(y,x) and beta(x,A) = beta(A,x).
• At least one input argument must be a scalar or both arguments must be vectors or matrices of
the same size. If one input argument is a scalar and the other one is a vector or a matrix,
beta(x,y) expands the scalar into a vector or matrix of the same size as the other argument with
all elements equal to that scalar.

Version History
Introduced in R2014a

References
[1] Zelen, M. and N. C. Severo. “Probability Functions.” Handbook of Mathematical Functions with
Formulas, Graphs, and Mathematical Tables. (M. Abramowitz and I. A. Stegun, eds.). New
York: Dover, 1972.

See Also
gamma | factorial | nchoosek | psi

7-138
 cat

cat
Concatenate symbolic arrays along specified dimension

Syntax
cat(dim,A1,...,AN)

Description
cat(dim,A1,...,AN) concatenates the arrays A1,...,AN along dimension dim. The remaining
dimensions must be the same size.

Examples
Concatenate Two Vectors into Matrix

Create vectors A and B.

A = sym('a%d',[1 4])
B = sym('b%d',[1 4])

A =
[ a1, a2, a3, a4]
B =
[ b1, b2, b3, b4]

To concatenate A and B into a matrix, specify dimension dim as 1.

cat(1,A,B)

ans =
[ a1, a2, a3, a4]
[ b1, b2, b3, b4]

Alternatively, use the syntax [A;B].

[A;B]

ans =
[ a1, a2, a3, a4]
[ b1, b2, b3, b4]

Concatenate Two Vectors into One Vector

To concatenate two vectors into one vector, specify dimension dim as 2.

A = sym('a%d',[1 4]);
B = sym('b%d',[1 4]);
cat(2,A,B)

ans =
[ a1, a2, a3, a4, b1, b2, b3, b4]

Alternatively, use the syntax [A B].

7-139
7 Functions

[A B]

ans =
[ a1, a2, a3, a4, b1, b2, b3, b4]

Concatenate Multidimensional Arrays Along Their Third Dimension

Create arrays A and B.

A = sym('a%d%d',[2 2]);
A(:,:,2) = -A
B = sym('b%d%d', [2 2]);
B(:,:,2) = -B

A(:,:,1) =
[ a11, a12]
[ a21, a22]
A(:,:,2) =
[ -a11, -a12]
[ -a21, -a22]

B(:,:,1) =
[ b11, b12]
[ b21, b22]
B(:,:,2) =
[ -b11, -b12]
[ -b21, -b22]

Concatenate A and B by specifying dimension dim as 3.

cat(3,A,B)

ans(:,:,1) =
[ a11, a12]
[ a21, a22]
ans(:,:,2) =
[ -a11, -a12]
[ -a21, -a22]
ans(:,:,3) =
[ b11, b12]
[ b21, b22]
ans(:,:,4) =
[ -b11, -b12]
[ -b21, -b22]

Input Arguments
dim — Dimension to concatenate arrays along
positive integer

Dimension to concatenate arrays along, specified as a positive integer.

A1,...,AN — Input arrays

symbolic variables | symbolic vectors | symbolic matrices | symbolic multidimensional arrays

Input arrays, specified as symbolic variables, vectors, matrices, or multidimensional arrays.

7-140
 cat

Version History
Introduced in R2010b

Concatenate symbolic matrix functions

The cat function accepts input arguments of type symfunmatrix.

Concatenate symbolic matrix variables

The cat function accepts input arguments of type symmatrix.

See Also
horzcat | reshape | vertcat

7-141
7 Functions

catalan
Catalan constant

Syntax
catalan

Description
catalan represents the Catalan constant on page 7-142. To get a floating-point approximation with
the current precision set by digits, use vpa(catalan).

Examples
Approximate Catalan Constant

Find a floating-point approximation of the Catalan constant with the default number of digits and with
the 10-digit precision.

Use vpa to approximate the Catalan constant with the default 32-digit precision:

vpa(catalan)

ans =
0.91596559417721901505460351493238

Set the number of digits to 10 and approximate the Catalan constant:

old = digits(10);
vpa(catalan)

ans =
0.9159655942

Restore the default number of digits:

digits(old)

More About
Catalan Constant

The Catalan constant is defined as follows:

∞ i
−1 1 1 1 1
catalan = ∑ 2
= 2
− 2
+ 2
− +…
i=0 2i + 1 1 3 5 72

Version History
Introduced in R2014a

7-142
 catalan

See Also
dilog | eulergamma

7-143
7 Functions

ccode
C code representation of symbolic expression

Syntax
ccode(f)
ccode(f,Name,Value)

Description
ccode(f) returns C code for the symbolic expression f.

ccode(f,Name,Value) uses additional options specified by one or more Name,Value pair

arguments.

Examples

Generate C Code from Symbolic Expression

Generate C code from the symbolic expression log(1+x).

syms x
f = log(1+x);
ccode(f)

ans =
' t0 = log(x+1.0);'

Generate C code for the 3-by-3 Hilbert matrix.

H = sym(hilb(3));
ccode(H)

ans =
' H[0][0] = 1.0;
H[0][1] = 1.0/2.0;
H[0][2] = 1.0/3.0;
H[1][0] = 1.0/2.0;
H[1][1] = 1.0/3.0;
H[1][2] = 1.0/4.0;
H[2][0] = 1.0/3.0;
H[2][1] = 1.0/4.0;
H[2][2] = 1.0/5.0;'

Initialize Arrays Efficiently

Because generated C code initializes only non-zero elements, you can efficiently initialize arrays by
setting all elements to 0 directly in your C code. Then, use the generated C code to initialize only
nonzero elements. This approach enables efficient initialization of matrices, especially sparse
matrices.

7-144
 ccode

Initialize the 3-by-3 identity matrix. First initialize the matrix with all elements set to 0 in your C
code. Then use the generated C code to initialize the nonzero values.

I3 = sym(eye(3));
I3code = ccode(I3)

I3code =
' I3[0][0] = 1.0;
I3[1][1] = 1.0;
I3[2][2] = 1.0;'

Write Optimized C Code to File with Comments

Write C code to the file ccodetest.c by specifying the File option. When writing to a file, ccode
optimizes the code by using intermediate variables named t0, t1, and so on.

syms x
f = diff(tan(x));
ccode(f,'File','ccodetest.c')

t0 = pow(tan(x),2.0)+1.0;

Include the comment Version: 1.1 in the file by using the Comments option. ccode uses block
comments.

ccode(f,'File','ccodetest.c','Comments','Version: 1.1')

/*
Version: 1.1
*/
t0 = pow(tan(x),2.0)+1.0;

Input Arguments
f — Symbolic input
symbolic expression

Symbolic input, specified as a symbolic expression.

Name-Value Pair Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the

argument name and Value is the corresponding value. Name-value arguments must appear after
other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose Name in quotes.
Example: ccode(x^2,'File','ccode.c','Comments','V1.2')

File — File to write to

character vector | string

File to write to, specified as a character vector or string. When writing to a file, ccode optimizes the
code by using intermediate variables named t0, t1, and so on.

7-145
7 Functions

Comments — Comments to include in file header

character vector | cell array of character vectors | string vector

Comments to include in the file header, specified as a character vector, cell array of character
vectors, or string vector. Because ccode uses block comments, the comments must not contain /* or
*/.

Tips
• To generate optimized C or C++ code from a symbolic expression, especially for a large
expression, you can use the MATLAB Coder app instead of using the ccode function. This way, the
generated code is better integrated into the MATLAB ecosystem. First, convert the symbolic
expression to a deployable MATLAB function using matlabFunction. Then, generate C or C++
code from the MATLAB function using the MATLAB Coder app. For an example, see “Generate C
Code from Symbolic Expressions Using the MATLAB Coder App” on page 5-16.

Version History
Introduced before R2006a

See Also
fortran | latex | matlabFunction

7-146
 cell2sym

cell2sym
Convert cell array to symbolic array

Syntax
S = cell2sym(C)
S = cell2sym(C,flag)

Description
S = cell2sym(C) converts a cell array C to a symbolic array S. The elements of C must be
convertible to symbolic objects.

If each element of the input cell array C is a scalar, then size(S) = size(C), and S(k) =
sym(C(k)) for all indices k. If the cell array C contains nonscalar elements, then the contents of C
must support concatenation into an N-dimensional rectangle. Otherwise, the results are undefined.
For example, the contents of cells in the same column must have the same number of columns.
However, they do not need to have the same number of rows. See figure.

S = cell2sym(C,flag) uses the technique specified by flag for converting floating-point numbers
to symbolic numbers.

Examples

Convert Cell Array of Scalars

Convert a cell array of only scalar elements to a symbolic array.

Create a cell array of scalar elements.

C = {'x','y','z'; 1 2 3}

C=2×3 cell array

{'x'} {'y'} {'z'}
{[1]} {[2]} {[3]}

Convert this cell array to a symbolic array.

S = cell2sym(C)

S =

7-147
7 Functions

x y z
123

cell2sym does not create symbolic variables x, y, and z in the MATLAB® workspace. To access an
element of S, use parentheses.
S(1,1)

ans = x

Convert Cell Array Containing Nonscalar Elements

Convert a cell array whose elements are scalars, vectors, and matrices into a symbolic array. Such
conversion is possible only if the contents of the cell array can be concatenated into an N-dimensional
rectangle.

Create a cell array, the elements of which are a scalar, a row vector, a column vector, and a matrix.
C = {'x' [2 3 4]; ['y'; sym(9)] [6 7 8; 10 11 12]}

C=2×2 cell array

{'x' } {[ 2 3 4]}
{2x1 sym} {2x3 double}

Convert this cell array to a symbolic array.

S = cell2sym(C)

S =
x 2 3 4
y 6 7 8
9 10 11 12

Choose Conversion Technique for Floating-Point Values

When converting a cell array containing floating-point numbers, you can explicitly specify the
conversion technique.

Create a cell array pi with two elements: the double-precision value of the constant pi and the exact
value pi.
C = {pi,sym(pi)}

C=1×2 cell array

{[3.1416]} {[pi]}

Convert this cell array to a symbolic array. By default, cell2sym uses the rational conversion mode.
Thus, results returned by cell2sym without a flag are the same as results returned by cell2sym
with the flag 'r'.
S = cell2sym(C)

7-148
 cell2sym

S = π π

S = cell2sym(C,'r')

S = π π

Convert the same cell array to a symbolic array using the flags 'd', 'e', and 'f'. See the “Input
Arguments” on page 7-149 section for the details about conversion techniques.

S = cell2sym(C,'d')

S = 3.1415926535897931159979634685442 π

S = cell2sym(C,'e')

S =
198 eps
π− π
359

S = cell2sym(C,'f')

S =
884279719003555
π
281474976710656

Input Arguments
C — Input cell array
cell array

Input cell array, specified as a cell array. The elements of C must be convertible to symbolic objects.

flag — Conversion technique

'r' (default) | 'd' | 'e' | 'f'

Conversion technique, specified as one of the characters listed in this table.

'r' In the rational mode, cell2sym converts floating-point numbers obtained by evaluating
expressions of the form p/q, p*pi/q, sqrt(p), 2^q, and 10^q for modest sized integers
p and q to the corresponding symbolic form. This approach effectively compensates for
the round-off error involved in the original evaluation, but might not represent the
floating-point value precisely. If cell2sym cannot find simple rational approximation,
then it uses the same technique as it would use with the flag 'f'.
'd' In the decimal mode, cell2sym takes the number of digits from the current setting of
digits. Conversions with fewer than 16 digits lose some accuracy, while more than 16
digits might not be warranted. For example, cell2sym({4/3},'d') with the 10-digit
accuracy returns 1.333333333, while with the 20-digit accuracy it returns
1.3333333333333332593. The latter does not end in 3s, but it is an accurate decimal
representation of the floating-point number nearest to 4/3.
'e' In the estimate error mode, cell2sym supplements a result obtained in the rational
mode by a term involving the variable eps. This term estimates the difference between
the theoretical rational expression and its actual floating-point value. For example,
cell2sym({3*pi/4},'e') returns (3*pi)/4 - (103*eps)/249.

7-149
7 Functions

'f' In the floating-point mode, cell2sym represents all values in the form N*2^e or -N*2^e,
where N >= 0 and e are integers. For example, cell2sym({1/10},'f') returns
3602879701896397/36028797018963968. The returned rational value is the exact
value of the floating-point number that you convert to a symbolic number.

Output Arguments
S — Resulting symbolic array
symbolic array

Resulting symbolic array, returned as a symbolic array.

Version History
Introduced in R2016a

See Also
sym2cell | cell2mat | mat2cell | num2cell

7-150