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

abstractmethod __add__(self, other)

add two matrices

abstractmethod __matmul__(self, other)

multiply matrix with a dense tensor

abstractmethod __mul__(self, other)

multiply matrix with a scalar

abstractmethod __neg__(self)

negate matrix

__weakref__

list of weak references to the object

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:

  • rows (bool/int array selecting rows for keeping)

  • cols (bool/int array selecting columns for keeping)

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

exception nutils.matrix.BackendNotAvailable

Bases: MatrixError

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

exception nutils.matrix.ToleranceNotReached(best)

Bases: MatrixError

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

nutils.matrix.assemble_csr(values, rowptr, colidx, ncols)

Create sparse matrix from CSR sparse data.

Parameters:

  • values – Matrix values in the row and column positions of the subsequent parameters; one dimensional array of any data type.

  • rowptr – Compressed row indices; one dimensonal integer array of a length one up from the number of matrix rows.

  • colidx – Column indices; one dimensional integer array of the same length as the values parameter.

  • ncols – Number of matrix columns.

nutils.matrix.assemble_coo(values, rowidx, nrows, colidx, ncols)

Create sparse matrix from COO sparse data.

Parameters:

  • values – Matrix values in the row and column positions of the subsequent parameters; one dimensional array of any data type.

  • rowptr – Row indices; one dimensonal integer array of the same length as the values parameter.

  • nrows – Number of matrix rows.

  • colidx – Column indices; one dimensional integer array of the same length as the values parameter.

  • ncols – Number of matrix columns.

nutils.matrix.assemble_block_csr(blocks)

Create sparse block matrix from stacked CSR sparse data.

Block columns may differ per row, but must add up the the same number of matrix columns. The matrix type is derived from the block values; in case of varying types Numpy’s casting rules apply.

Parameters:

blocks – Nested sequence of CSR data. The outer sequence represents the matrix rows, the middle sequences the matrix columns, and the inner sequences the arguments to the assemble_csr function.