# matrixbase::Difference

## Description

Compute the N-th order row wise or column wise difference of the elements in this matrix.

## Syntax

int Difference( matrixbase & mbDifference, int nOrder = 1, int nDim = 1 )


## Parameters

mbDifference
[output] The result matrix containing the difference
nOrder
[input] The order of difference to compute, default is 1
nDim
[input] The Difference function can operate row wise (relative to the first dimension when nDim=1) or column wise (relative to the second dimension when nDim=2), default is 1 or row wise

## Return

Returns 0 on success and a non-zero error code on failure.

## Examples

EX1

void matrixbase_Difference_ex1()
{
matrix mat1 = {
{2,  4,  6},
{3,  7, 11},
{5, 11, 17}
};
int rc = mat1.Difference( mat1 );
if(rc!=0)
printf("Error: Difference failed. rc=%d\n", rc);
else{
printf("The matrix is:\n");
for(int ii=0; ii< mat1.GetNumRows(); ii++){
for(int jj=0; jj< mat1.GetNumCols(); jj++)
printf("%g  ", mat1[ii][jj]);
printf("\r\n");
}
}
}


EX2

// Compute nth-order difference of a matrix
#define MAKEMAT(X) MatrixLayer MatLy##X;MatLy##X.Create();Matrix Mat##X(MatLy##X)
void matrixbase_Difference_ex2()
{
int rc;

matrix mat1 = {
{2,  4,  6},
{3,  7, 11},
{5, 11, 17}
};

MAKEMAT(1); MAKEMAT(2); MAKEMAT(3); MAKEMAT(4);

Mat1=mat1;
printf("  Original matrix is %s.\n",Mat1.GetName());

rc=mat1.Difference(Mat2);
if(rc!=0)
printf("  Error: 1st order difference on %s failed.\n",Mat1.GetName());
else
printf("  1st order differential of %s is in %s\n",
Mat1.GetName(),Mat2.GetName());

rc=mat1.Difference(Mat3,2);
if(rc!=0)
printf("  Error: 2nd order difference on %s failed.\n",Mat1.GetName());
else
printf("  2nd order differential of %s is in %s\n",
Mat1.GetName(),Mat3.GetName());

//    rc=mat1.Difference(Mat4,3);
//    If nOrder is setted as 3, a Command Error will occur.
}


EX3

#define MAKEMAT(X) MatrixLayer MatLy##X;MatLy##X.Create();Matrix Mat##X(MatLy##X)

void matrixbase_Difference_ex3()

{
matrix mat1 = {
{2, 4, 6},
{3, 7, 11},
{5, 11, 17}
};

matrix mat2 = {
{1, 2, 3},
{1, 2, 3},
{1, 2, 3}
};

MAKEMAT(1); MAKEMAT(2); MAKEMAT(3); MAKEMAT(4); MAKEMAT(5);

Mat1=mat1; Mat2=mat2;

Mat3=mat1-mat2;
printf("%s = %s - %s <== element-wise subtraction of 2 matrices\n",Mat3.GetName(),Mat1.GetName(),Mat2.GetName());

Mat4=mat1-2;
printf("%s = %s - 2 <== Scaler subtraction of a matrix\n",Mat4.GetName(),Mat1.GetName());

mat1.Difference(Mat5);
printf("%s = Difference(%s) <== difference of adjacent 2 rows in a matrix (1st order differential)\n",Mat5.GetName(),Mat1.GetName());
}


## Remark

Compute the N-th order row wise or column wise difference of the elements in this matrix. The difference matrix is computed by replacing the current element with the current element minus the previous element along the dimension specified by nDim. The N-th order difference approximates the N-th order derivative. If nOrder is greater than or equal to the size of the dimension identified by nDim than an empty matrix is returned. The underlying base type of this matrix and the result matrix must be the same.

Note

The following is a summary of various matrix operations:

1) Multiplication:

1-1) * ... Proper multiplication of 2 matrices (mat1*mat2)

1-2) * ... Scaler multiplication of a matrix (mat1*A or A*mat1)

1-3) DotMultiply ... Element-wise multiplication of 2 matrices

1-4) Cross ... Cross product of 2 matrices

1-5) CumulativeProduct ... cumulative product of a matrix

2) Division:

2-1) / ... Not defined for 2 matrices. For proper division, multiply Inverse(mat1)

2-2) / ... Scaler division of a matrix (mat1/A)

2-3) DotDivide ... Element-wise division of 2 matrices

3-1) + ... Element-wise addition of 2 matrices

3-2) + ... Scaler addition of a matrix (mat1+A or A+mat1)

3-3) SumColumns ... Summation of each column in a matrix

3-4) CumulativeSum ... Cumulative product of a matrix

4) Subtraction:

4-1) - ... Element-wise subtraction of 2 matrices

4-2) - ... Scaler subtraction of a matrix (mat1-A or A-mat1)

4-3) Difference ... Difference of adjacent 2 rows in a matrix (1st order differential)

5) Power:

5-1) ^ (or pow) ... Not defined as element-wise power of 2 matrices

5-2) ^ (or pow) ... Not defined as scaler power of a matrix

5-3) DotPower ... Element-wise power of 2 matrices

To depict the differences of above subtractions, try the EX2.