# matrix¶

The matrix module defines an abstract `Matrix` object and several implementations. Matrix objects support basic addition and subtraction operations and provide a consistent insterface for solving linear systems. Matrices can be converted into other forms suitable for external processing via the `export` method.

class nutils.matrix.Matrix(shape, dtype)

Bases: `object`

matrix base class

abstract property T

transpose matrix

abstract __matmul__(self, other)

multiply matrix with a dense tensor

abstract __mul__(self, other)

multiply matrix with a scalar

abstract __neg__(self)

negate matrix

__weakref__

list of weak references to the object (if defined)

export(self, form)

Export matrix data to any of supported forms.

Parameters

form (`str`) –

• “dense” : return matrix as a single dense array

• ”csr” : return matrix as 3-tuple of (data, indices, indptr)

• ”coo” : return matrix as 2-tuple of (data, (row, col))

rowsupp(self, tol=0)

return row indices with nonzero/non-small entries

solve(self, rhs=None, *, lhs0=None, constrain=None, rconstrain=None, solver='arnoldi', atol=0.0, rtol=0.0, **solverargs)

Solve system given right hand side vector and/or constraints.

Parameters
• rhs (`float` vector or `None`) – Right hand side vector. A `None` value implies the zero vector.

• lhs0 (class:float vector or `None`) – Initial values: compute the solution by solving `A dx = b - A lhs0`. A `None` value implies the zero vector, i.e. solving `A x = b` directly.

• constrain (`float` or `bool` array, or `None` Column) – constraints. For float values, a number signifies a constraint, NaN signifies a free dof. For boolean, a `True` value signifies a constraint to the value in `lhs0`, a `False` value signifies a free dof. A `None` value implies no constraints.

• rconstrain (`bool` array or `None`) – Row constrains. A True value signifies a constrains, a False value a free dof. A `None` value implies that the constraints follow those defined in `constrain` (by implication the matrix must be square).

• solver (`str`) – Name of the solver algorithm. The set of available solvers depends on the type of the matrix (i.e. the active backend), although the ‘direct’ and ‘arnoldi’ solvers are always available.

• rtol (`float`) – Relative tolerance: see `atol`.

• atol (`float`) – Absolute tolerance: require that `|A x - b| <= max(atol, rtol |b|)` after applying constraints and the initial value. In case `atol` and `rtol` are both zero (the defaults) solve to machine precision. Otherwise fail with `nutils.matrix.ToleranceNotReached` if the requirement is not reached.

• **kwargs – All remaining arguments are passed on to the selected solver method.

Returns

Left hand side vector.

Return type

`numpy.ndarray`

solve_leniently(self, *args, **kwargs)

Identical to `nutils.matrix.Matrix.solve()`, but emit a warning in case tolerances are not met rather than an exception, while returning the obtained solution vector.

submatrix(self, rows, cols)

Create submatrix from selected rows, columns.

Parameters
Returns

Matrix instance of reduced dimensions

Return type

`Matrix`

exception nutils.matrix.MatrixError

Bases: `Exception`

General error message for matrix-related failure.

__weakref__

list of weak references to the object (if defined)

exception nutils.matrix.BackendNotAvailable

Error message reporting that the selected matrix backend is not available on the system.

exception nutils.matrix.ToleranceNotReached(best)

Error message reporting that the configured linear solver tolerance was not reached. The `.best` attribute carries the non-conforming solution.