| Description | The inverse of the matrix MA is stored in MInv. If MA is non-invertible, the function fails with an error message. In the general case, MF_inv, inversion is accomplished via LU decomposition. In the special case of symmetric matrices, MFsym_inv can perform the inversion about two times faster, if the matrix is positive-definite.
In order to prevent MF_inv from failing, you can define a minimum pivot for the decomposition. If you wish to do so for all calls to MF_LUdecompose and to the functions based upon it, namely MF_inv and MF_solve, you can do so by calling MF_LUDsetEdit. However, as this method is not thread-safe, you cannot use it in order to set different thresholds for different calls to the functions mentioned. Instead of defining a default editing threshold then, use their "wEdit" variants, i.e. MF_LUdecomposewEdit, MF_invwEdit or MF_solvewEdit. They take the desired threshold as the additional argument thresh. Note that thresh is always real, also in the complex versions.
The return value of MF_inv and MF_invwEdit indicates if the inversion was successful:
| Return value | Meaning |
| 0 | Matrix MA is regular; inversion successful |
| 1 | Matrix MA is singular; result matrix contains no useful information |
| 2 | Matrix MA is (nearly) singular; could be inverted only by pivot editing; if the result is still useful, depends on the specific application. |
To check if MF_inv was successful, in single-thread programs, you may also call MF_LUDresult, whose return value will be FALSE (0), if the MA could be inverted without problems (and without pivot editing), and TRUE (1) for singular MA. In multi-thread programs, on the other hand, it would not be clear wich instance of MF_inv the call to MF_LUDresult would refer to. So, here, inspection of the return value of MF_inv is the only option.
The matrix inversion functions need buffer memory. The "normal" versions (prefixes MF_, MCF_ etc.) allocate it themselves, whereas the version with the prefixes MFb_, MCFb_ etc. take a vector Buf as an additional argument. The required size of Buf can be obtained by calling MFb_inv_sizeBuf() etc., whereby the size is given as the number of elements of Buf in the respective data type (rather than in bytes).
As noted above, symmetric matrices can potentially be inverted faster by MFsym_inv. The syntax and the meaning of the return value is the same as for MF_inv. Internally, this function first attempts Cholesky decomposition. Only if that fails (i.e. the input matrix is not positive-definite), the way via LUD is used. |