next up previous contents
Next: COMPARISONOPS Array Comparison Operators Up: Mathematical Operators Previous: DOTLEFTDIVIDE Element-wise Left-Division Operator   Contents

Subsections

DOTPOWER Element-wise Power Operator

Usage

Raises one numerical array to another array (elementwise). There are three operators all with the same general syntax:

  y = a .^ b

The result y depends on which of the following three situations applies to the arguments a and b:

  1. a is a scalar, b is an arbitrary n-dimensional numerical array, in which case the output is a raised to the power of each element of b, and the output is the same size as b.
  2. a is an n-dimensional numerical array, and b is a scalar, then the output is the same size as a, and is defined by each element of a raised to the power b.
  3. a and b are both n-dimensional numerical arrays of the same size. In this case, each element of the output is the corresponding element of a raised to the power defined by the corresponding element of b.
The output follows the standard type promotion rules, although types are not generally preserved under the power operation. In particular, integers are automatically converted to double type, and negative numbers raised to fractional powers can return complex values.

Function Internals

There are three formulae for this operator. For the first form

$\displaystyle y(m_1,\ldots,m_d) = a^{b(m_1,\ldots,m_d)},
$

and the second form

$\displaystyle y(m_1,\ldots,m_d) = a(m_1,\ldots,m_d)^b,
$

and in the third form

$\displaystyle y(m_1,\ldots,m_d) = a(m_1,\ldots,m_d)^{b(m_1,\ldots,m_d)}.
$

Examples

We demonstrate the three forms of the dot-power operator using some simple examples. First, the case of a scalar raised to a series of values.

--> a = 2
a = 
  <int32>  - size: [1 1]
             2  
--> b = 1:4
b = 
  <int32>  - size: [1 4]
 
Columns 1 to 4
             1              2              3              4  
--> c = a.^b
c = 
  <double>  - size: [1 4]
 
Columns 1 to 2
    2.000000000000000         4.000000000000000      
 
Columns 3 to 4
    8.000000000000000        16.0000000000000

The second case shows a vector raised to a scalar.

--> c = b.^a
c = 
  <double>  - size: [1 4]
 
Columns 1 to 2
    1.000000000000000         4.000000000000000      
 
Columns 3 to 4
    9.000000000000000        16.0000000000000

The third case shows the most general use of the dot-power operator.

--> A = [1,2;3,2]
A = 
  <int32>  - size: [2 2]
 
Columns 1 to 2
             1              2  
             3              2  
--> B = [2,1.5;0.5,0.6]
B = 
  <double>  - size: [2 2]
 
Columns 1 to 2
    2.000000000000000         1.500000000000000      
    0.500000000000000         0.600000000000000      
--> C = A.^B
C = 
  <double>  - size: [2 2]
 
Columns 1 to 2
    1.000000000000000         2.828427124746190      
    1.732050807568877         1.515716566510398


next up previous contents
Next: COMPARISONOPS Array Comparison Operators Up: Mathematical Operators Previous: DOTLEFTDIVIDE Element-wise Left-Division Operator   Contents
Samit K. Basu 2005-03-16