| Description | These functions solve the system MA * X = B of simultaneous linear equations. In the general case, MF_solve, LU decomposition is used. For symmetric matrices, assumed to be positive-definite, MFsym_solve provides a roughly two times faster way, employing Cholesky decomposition.
First, MF_solve is described. MFsym_solve follows at the end.
MF_solve works well in all cases where there is one unique solution. If successful, it returns FALSE (0).
If, on the other hand, the system is ill-determined, which happens in all cases where one or more of the equations are linear combinations of other equations of the same system, the resulting matrix becomes singular and the function fails with an error message.
To avoid outright failure in an application where ill-determined matrices might occur, 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_solve and MF_solvewEdit indicates if the linear system could successfully be solved:
| Return value | Meaning |
| 0 | Matrix MA is regular; linear system successfully solved |
| 1 | Under-determined system; matrix MA is singular; result X contains no useful information |
| 2 | Under-determined system; matrix MA is (nearly) singular; solution was achieved only by pivot editing; it depends on the specific application, if the result is useful or not. |
To check if MF_solve was successful, in single-thread programs, you may also call MF_LUDresult, whose return value will be FALSE (0), if the system could be solved 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_solve the call to MF_LUDresult would refer to. So, here, inspection of the return value of MF_solve is the only option.
As an often preferrable alternative to pivot editing, you might switch to MF_safeSolve or MF_solveBySVD.
For symmetric matrices, we already noticed that MFsym_solve provides a potentially much faster way. This routine first tries Cholesky decomposition. If the matrix turns out not to be positive-definite, LU decomposition is used. The return value of MFsym_solve indicates if the linear system could successfully be solved:
| Return value | Meaning |
| 0 | Linear system successfully solved, either by Cholesky or by LUD |
| 1 | Under-determined system; both Cholesky and LUD failed; matrix MA is singular; result X contains no useful information |
| 2 | Under-determined system; matrix MA is (nearly) singular; solution was achieved only by LUD with pivot editing; it depends on the specific application, if the result is partially useful or not. |
|