1 /* ----------------------------------------------------------------------
2 * Project: CMSIS DSP Library
3 * Title: arm_mat_inverse_f64.c
4 * Description: Floating-point matrix inverse
5 *
6 * $Date: 23 April 2021
7 * $Revision: V1.9.0
8 *
9 * Target Processor: Cortex-M and Cortex-A cores
10 * -------------------------------------------------------------------- */
11 /*
12 * Copyright (C) 2010-2021 ARM Limited or its affiliates. All rights reserved.
13 *
14 * SPDX-License-Identifier: Apache-2.0
15 *
16 * Licensed under the Apache License, Version 2.0 (the License); you may
17 * not use this file except in compliance with the License.
18 * You may obtain a copy of the License at
19 *
20 * www.apache.org/licenses/LICENSE-2.0
21 *
22 * Unless required by applicable law or agreed to in writing, software
23 * distributed under the License is distributed on an AS IS BASIS, WITHOUT
24 * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
25 * See the License for the specific language governing permissions and
26 * limitations under the License.
27 */
28
29 #include "dsp/matrix_functions.h"
30 #include "dsp/matrix_utils.h"
31
32 /**
33 @ingroup groupMatrix
34 */
35
36
37 /**
38 @addtogroup MatrixInv
39 @{
40 */
41
42 /**
43 @brief Floating-point (64 bit) matrix inverse.
44 @param[in] pSrc points to input matrix structure. The source matrix is modified by the function.
45 @param[out] pDst points to output matrix structure
46 @return execution status
47 - \ref ARM_MATH_SUCCESS : Operation successful
48 - \ref ARM_MATH_SIZE_MISMATCH : Matrix size check failed
49 - \ref ARM_MATH_SINGULAR : Input matrix is found to be singular (non-invertible)
50 */
51
arm_mat_inverse_f64(const arm_matrix_instance_f64 * pSrc,arm_matrix_instance_f64 * pDst)52 arm_status arm_mat_inverse_f64(
53 const arm_matrix_instance_f64 * pSrc,
54 arm_matrix_instance_f64 * pDst)
55 {
56 float64_t *pIn = pSrc->pData; /* input data matrix pointer */
57 float64_t *pOut = pDst->pData; /* output data matrix pointer */
58
59 float64_t *pTmp;
60 uint32_t numRows = pSrc->numRows; /* Number of rows in the matrix */
61 uint32_t numCols = pSrc->numCols; /* Number of Cols in the matrix */
62
63
64 float64_t pivot = 0.0, newPivot=0.0; /* Temporary input values */
65 uint32_t selectedRow,pivotRow,i, rowNb, rowCnt, flag = 0U, j,column; /* loop counters */
66 arm_status status; /* status of matrix inverse */
67
68 #ifdef ARM_MATH_MATRIX_CHECK
69
70 /* Check for matrix mismatch condition */
71 if ((pSrc->numRows != pSrc->numCols) ||
72 (pDst->numRows != pDst->numCols) ||
73 (pSrc->numRows != pDst->numRows) )
74 {
75 /* Set status as ARM_MATH_SIZE_MISMATCH */
76 status = ARM_MATH_SIZE_MISMATCH;
77 }
78 else
79
80 #endif /* #ifdef ARM_MATH_MATRIX_CHECK */
81
82 {
83 /*--------------------------------------------------------------------------------------------------------------
84 * Matrix Inverse can be solved using elementary row operations.
85 *
86 * Gauss-Jordan Method:
87 *
88 * 1. First combine the identity matrix and the input matrix separated by a bar to form an
89 * augmented matrix as follows:
90 * _ _ _ _
91 * | a11 a12 | 1 0 | | X11 X12 |
92 * | | | = | |
93 * |_ a21 a22 | 0 1 _| |_ X21 X21 _|
94 *
95 * 2. In our implementation, pDst Matrix is used as identity matrix.
96 *
97 * 3. Begin with the first row. Let i = 1.
98 *
99 * 4. Check to see if the pivot for row i is zero.
100 * The pivot is the element of the main diagonal that is on the current row.
101 * For instance, if working with row i, then the pivot element is aii.
102 * If the pivot is zero, exchange that row with a row below it that does not
103 * contain a zero in column i. If this is not possible, then an inverse
104 * to that matrix does not exist.
105 *
106 * 5. Divide every element of row i by the pivot.
107 *
108 * 6. For every row below and row i, replace that row with the sum of that row and
109 * a multiple of row i so that each new element in column i below row i is zero.
110 *
111 * 7. Move to the next row and column and repeat steps 2 through 5 until you have zeros
112 * for every element below and above the main diagonal.
113 *
114 * 8. Now an identical matrix is formed to the left of the bar(input matrix, pSrc).
115 * Therefore, the matrix to the right of the bar is our solution(pDst matrix, pDst).
116 *----------------------------------------------------------------------------------------------------------------*/
117
118 /* Working pointer for destination matrix */
119 pTmp = pOut;
120
121 /* Loop over the number of rows */
122 rowCnt = numRows;
123
124 /* Making the destination matrix as identity matrix */
125 while (rowCnt > 0U)
126 {
127 /* Writing all zeroes in lower triangle of the destination matrix */
128 j = numRows - rowCnt;
129 while (j > 0U)
130 {
131 *pTmp++ = 0.0;
132 j--;
133 }
134
135 /* Writing all ones in the diagonal of the destination matrix */
136 *pTmp++ = 1.0;
137
138 /* Writing all zeroes in upper triangle of the destination matrix */
139 j = rowCnt - 1U;
140 while (j > 0U)
141 {
142 *pTmp++ = 0.0;
143 j--;
144 }
145
146 /* Decrement loop counter */
147 rowCnt--;
148 }
149
150 /* Loop over the number of columns of the input matrix.
151 All the elements in each column are processed by the row operations */
152
153 /* Index modifier to navigate through the columns */
154 for(column = 0U; column < numCols; column++)
155 {
156 /* Check if the pivot element is zero..
157 * If it is zero then interchange the row with non zero row below.
158 * If there is no non zero element to replace in the rows below,
159 * then the matrix is Singular. */
160
161 pivotRow = column;
162
163 /* Temporary variable to hold the pivot value */
164 pTmp = ELEM(pSrc,column,column) ;
165 pivot = *pTmp;
166 selectedRow = column;
167
168
169 /* Loop over the number rows present below */
170
171 for (rowNb = column+1; rowNb < numRows; rowNb++)
172 {
173 /* Update the input and destination pointers */
174 pTmp = ELEM(pSrc,rowNb,column);
175 newPivot = *pTmp;
176 if (fabs(newPivot) > fabs(pivot))
177 {
178 selectedRow = rowNb;
179 pivot = newPivot;
180 }
181 }
182
183 /* Check if there is a non zero pivot element to
184 * replace in the rows below */
185 if ((pivot != 0.0) && (selectedRow != column))
186 {
187 /* Loop over number of columns
188 * to the right of the pilot element */
189
190 SWAP_ROWS_F64(pSrc,column, pivotRow,selectedRow);
191 SWAP_ROWS_F64(pDst,0, pivotRow,selectedRow);
192
193
194 /* Flag to indicate whether exchange is done or not */
195 flag = 1U;
196
197 }
198
199
200 /* Update the status if the matrix is singular */
201 if ((flag != 1U) && (pivot == 0.0))
202 {
203 return ARM_MATH_SINGULAR;
204 }
205
206
207 /* Pivot element of the row */
208 pivot = 1.0 / pivot;
209
210 SCALE_ROW_F64(pSrc,column,pivot,pivotRow);
211 SCALE_ROW_F64(pDst,0,pivot,pivotRow);
212
213
214 /* Replace the rows with the sum of that row and a multiple of row i
215 * so that each new element in column i above row i is zero.*/
216
217 rowNb = 0;
218 for (;rowNb < pivotRow; rowNb++)
219 {
220 pTmp = ELEM(pSrc,rowNb,column) ;
221 pivot = *pTmp;
222
223 MAS_ROW_F64(column,pSrc,rowNb,pivot,pSrc,pivotRow);
224 MAS_ROW_F64(0 ,pDst,rowNb,pivot,pDst,pivotRow);
225
226
227 }
228
229 for (rowNb = pivotRow + 1; rowNb < numRows; rowNb++)
230 {
231 pTmp = ELEM(pSrc,rowNb,column) ;
232 pivot = *pTmp;
233
234 MAS_ROW_F64(column,pSrc,rowNb,pivot,pSrc,pivotRow);
235 MAS_ROW_F64(0 ,pDst,rowNb,pivot,pDst,pivotRow);
236
237 }
238
239 }
240
241 /* Set status as ARM_MATH_SUCCESS */
242 status = ARM_MATH_SUCCESS;
243
244 if ((flag != 1U) && (pivot == 0.0))
245 {
246 pIn = pSrc->pData;
247 for (i = 0; i < numRows * numCols; i++)
248 {
249 if (pIn[i] != 0.0)
250 break;
251 }
252
253 if (i == numRows * numCols)
254 status = ARM_MATH_SINGULAR;
255 }
256 }
257
258 /* Return to application */
259 return (status);
260 }
261 /**
262 @} end of MatrixInv group
263 */
264
