Solve a linear matrix equation
This functionality does not run in MATLAB.
numeric::matlinsolve(A
, B
, options
)
numeric::matlinsolve(A, B)
returns the matrix
solution X of
the matrix equation A X = B together
with the kernel of the matrix A.
numeric::matlinsolve
is a fast numerical
linear solver for both sparse and dense systems. It is also a recommended
solver for linear systems with exact or symbolic coefficients (use
option Symbolic
).
If no return type is specified via the option ReturnType
= d
, the domain type of the return data depends on the type
of the input matrix A
:
The special solution X as well as the kernel of an array A are returned as arrays.
The special solution X as well as the kernel of an hfarray A are returned as hfarrays.
For a dense matrixA of
type Dom::DenseMatrix()
, both the special solution X as
well as the kernel of A are
returned as matrices of type Dom::DenseMatrix()
over
the ring of MuPAD^{®} expressions.
For all other matrices of category Cat::Matrix
, both the special
solution X as
well as the kernel of A are
returned as matrices of type Dom::Matrix()
over
the ring of MuPAD expressions. This includes input matrices A
of
type Dom::Matrix(...)
, Dom::SquareMatrix(...)
, Dom::MatrixGroup(...)
etc.
Without Symbolic
, exact numerical input data
such as PI + sqrt(2)
, sin(3)
etc.
are converted to floatingpoint numbers. Floating point arithmetic
is used. Its precision is given the environment variable DIGITS
.
If symbolic data are found that cannot be converted to floatingpoint
numbers, numeric::matlinsolve
automatically switches
to its symbolic mode, issuing a warning. This warning may be suppressed
via NoWarning
.
With Symbolic
, symbolic parameters in the
coefficient matrix A
as well as in the right hand
side B
are accepted and processed without a warning.
With SofwareFloats
, the right hand side B
may
contain symbolic parameters that cannot be converted to floatingpoint
numbers. All entries of the coefficient matrix A
,
however, must be convertible to floatingpoint numbers.
With HardwareFloats
, neither A nor B must
contain symbolic parameters that cannot be converted to floatingpoint
numbers.
X
is a special solution
of the equation A X = B.
If A has
a nontrivial kernel, the solution X is
not unique.
Note:
The result computed with 
Cf. Example 9.
The n×d matrix KernelBasis
is
the most general solution of A X =
0. Its columns span the ddimensional
kernel of A.
Thus, the kernel of A may
be computed via numeric::matlinsolve(A, [0, ..., 0])[2]
.
If the kernel is 0dimensional,
the return value of KernelBasis
is the integer 0.
If KernelBasis
is returned as an array, the dimension d of
the kernel is d
= op(KernelBasis, [0,
3, 2]])
. If KernelBasis
is returned as
a matrix of type Dom::Matrix()
or Dom::DenseMatrix()
,
the dimension d of
the kernel is d
= KernelBasis::dom::matdim(KernelBasis)[2]
.
Note:
Due to roundoff errors, some or all basis vectors in the kernel
of 
The special solution X
in conjunction with KernelBasis
provides
the general solution of A X = B.
Solutions generated without the option ShowAssumptions
are
valid for arbitrary complex values of the symbolic parameters which
may be present in A
and B
. If
no such solution exists, then [FAIL,NIL]
is returned.
Solutions that are valid only for special values of the symbolic parameters
may be obtained with ShowAssumptions
. See Example 3, Example 4, and Example 7.
numeric::matlinsolve
internally uses a sparse
representation of the matrices. It is suitable for solving large sparse
systems. See Example 5.
Note:

Note:
Gaussian elimination with partial pivoting is used. Without
the option 
Note:
Apart from matrices of type Note that 
Without the option Symbolic
, the function
is sensitive to the environment variable DIGITS
, which determines
the numerical working precision.
We use equivalent input formats (B_{1},
B_{2})
to represent a vector with components [a,
π]. First, this vector is defined as a 2dimensional
array:
A := array(1..2, 1..3, [[1, 2, 3],[1, 1, 2]]): B1 := array(1..2, 1..1, [[a], [PI]]): numeric::matlinsolve(A, B1)
Next, we use a 1dimensional array and compute an exact solution:
B2 := array(1..2, [a, PI]): numeric::matlinsolve(A, B2, Symbolic)
Now, a list is used to specify the vector. No internal assumptions
were used by numeric::matlinsolve
to obtain the
solution:
B3 := [a, PI]: numeric::matlinsolve(A, B3, ShowAssumptions)
Finally, we use Dom::Matrix
objects
to specify the system. Note that the results are returned as corresponding
matrix objects:
A := matrix([[1, 2, 3],[1, 1, 2]]): B4 := matrix([a, PI]): numeric::matlinsolve(A, B4)
delete A, B1, B2, B3, B4:
We invert a matrix by solving A X = 1:
A := hfarray(1..3, 1..3, [[1, 1, 0], [0, 1, 1], [0, 0, 1]]): B := matrix::identity(3, 3): InverseOfA := numeric::matlinsolve(A, B, Symbolic)[1]
delete A, B, InverseOfA:
We solve an equation with a symbolic parameter x:
A := matrix([[2, 2, 3], [1, 1, 2], [3, 3, 5]]): B := matrix([sin(x)^2, cos(x)^2, 0]): [X, Kernel, Constraints, Pivots] := numeric::matlinsolve(A, B, Symbolic, ShowAssumptions)
This solution holds subject to the constraint sin(x)^{2} + cos(x)^{2} =
0 on the parameter x. numeric::matlinsolve
does
not investigate the Constraints
and does not realize
that they cannot be satisfied. We check the consistency of the "result"
by inserting the solution into the original system. Since the input
matrix A was
of type Dom::Matrix()
, the results X
and Kernel
were
returned as corresponding matrices. The overloaded operators *
and 
for
matrix multiplication and subtraction can be used:
A*X  B, A*Kernel
delete A, B, X, Kernel, Constraints, Pivots:
We give a further demonstration of the option ShowAssumptions
.
The following system does not have a solution for all values of the
parameter a
:
A := array(1..2, 1..2, [[1, 1], [1, 1]]): B := array(1..2, 1..1, [[1], [a]]): numeric::matlinsolve(A, B, Symbolic)
With ShowAssumptions
, numeric::matlinsolve
investigates
under which conditions (on the parameter a a
) there
is a solution:
numeric::matlinsolve(A, B, Symbolic, ShowAssumptions)
We conclude that there is a 1dimensional solution space for a = 1.
delete A, B:
We solve a sparse system with 3 diagonal bands:
n := 100: A := matrix(n, n, [1, 2, 1], Banded): B := array(1..n, [1 $ n]): numeric::matlinsolve(A, B)
delete n, A, B:
The option Symbolic
should not be used for
equations with floatingpoint coefficients, because the symbolic pivoting
strategy favors efficiency instead of numerical stability.
A := array(1..2, 1..2, [[1, 10^20], [1, 1]]): B := array(1..2, 1..1, [[10^20], [0]]):
The float approximation of the exact solution is:
map(numeric::matlinsolve(A, B, Symbolic)[1], float)
We now convert the exact input data to floatingpoint approximations:
A := map(A, float): B := map(B, float):
The default pivoting strategy of the floatingpoint algorithm stabilizes floatingpoint operations. Consequently, one gets a correct result:
numeric::matlinsolve(A, B)[1]
With the option Symbolic
, however, the pivoting
strategy optimizes speed, assuming exact arithmetic. Numerical instabilities
may occur if floatingpoint coefficients are involved. The following
result is caused by internal roundoff effects ("cancellation"):
numeric::matlinsolve(A, B, Symbolic)[1]
We need to increase DIGITS
to obtain a better
result:
DIGITS := 20: numeric::matlinsolve(A, B, Symbolic)[1]
delete A, B, DIGITS:
We demonstrate how a complete solution of the following linear system with symbolic parameters may be found:
A := array(1..3, 1..2, [[1, 1], [a, b], [1, c]]): B := array(1..3, 1..1, [[1], [1], [1]]): numeric::matlinsolve(A, B, Symbolic, ShowAssumptions)
This is the general solution assuming a ≠ b. We now set b = a to investigate further solution branches:
A := subs(A, b = a): numeric::matlinsolve(A, B, Symbolic, ShowAssumptions)
This is the general solution for a = b, assuming c ≠ 1. We finally set c = 1 to obtain the last solution branch:
A := subs(A, c = 1): numeric::matlinsolve(A, B, Symbolic, ShowAssumptions)
From the constraint on a
, we conclude that
there is a 1dimensional solution space for the special values a = b = c =
1 of the symbolic parameters.
delete A, B:
Matrices from a domain such as Dom::Matrix
(...)
are
converted to arrays with numbers or expressions. Hence, numeric::matlinsolve
finds
no solution for the following system:
M := Dom::Matrix(Dom::IntegerMod(7)): A := M([[1, 4], [6, 3], [3, 2]]): B := M([[9], [5], [0]]): numeric::matlinsolve(A, B)
Use linalg::matlinsolve
to
solve the system over the coefficient field of the matrices. A solution
does exist over the field Dom::IntegerMod
(7)
:
linalg::matlinsolve(A, B)
delete M, A, B:
We demonstrate the difference between Symbolic
, HardwareFloats
,
and SoftwareFloats
. The following matrix A has
a 1dimensional kernel. Due to roundoff, a further spurious kernel
vector appears with SoftwareFloats
. No kernel vector
is detected with HardwareFloats
:
A := matrix([[2*10^14 + 2, 2*10^(9), 2*10^(4)], [3*10^15 + 3, 3*10^(8), 3*10^(3)], [4*10^16 + 4, 4*10^(7), 4*10^(2)] ]): b := matrix([2*10^(9), 3*10^(8), 4*10^(7)]): float(numeric::matlinsolve(A, b, Symbolic)); numeric::matlinsolve(A, b, SoftwareFloats); numeric::matlinsolve(A, b, HardwareFloats)
delete A, b:

An m×n matrix
of domain type 

An m×p matrix
of domain type 

With With Compared to the If no If the result cannot be computed with hardware floats, software arithmetic by the MuPAD kernel is tried. If the current value of There may be several reasons for hardware arithmetic to fail:
If neither If Note that The trailing digits in floatingpoint results computed with
 

Prevents the conversion of the input data to floatingpoint
numbers. Exact arithmetic is used. This option overrides This option must be used if the matrix A contains symbolic parameters that cannot be converted to floatingpoint numbers.
 

Returns information on internal assumptions on symbolic parameters
in This option is only useful if the matrices contain symbolic
parameters. Consequently, it should only be used in conjunction with
the option
Such constraints arise if Gaussian elimination leads to equations
of the form 0 = c,
where c is
some expression involving symbolic parameters contained in B.
All such equations are collected in If no such constraints arise, the return value of
 

Suppresses warnings If symbolic coefficients are found,  

Option, specified as Return the (special) solution and the kernel as matrices of domain type  

Use a sparse internal representation for matrices. This option only has an effect when used in conjunction with 
Without the option ShowAssumptions
, a list [X,
KernelBasis]
is returned. The (special) solution X
is
an n×p matrix. KernelBasis
is
an n×d matrix
(d is
the dimension of the kernel of A).
Its columns span the kernel of A.
If the kernel is trivial, KernelBasis
is the integer 0.
[FAIL, NIL]
is returned if the system is
not solvable.
With ShowAssumptions
, a list [X,
KernelBasis, Constraints, Pivots]
is returned. The lists Constraints
and Pivots
contain
equations and inequalities involving symbolic parameters in A
and B
.
Internally these were assumed to hold true when solving the system. [FAIL,
NIL, [], []]
is returned if the system is not solvable.