Utilities for sparse matrices (pyfe3d.solver.sparseutils)

The check that a matrix given to the solvers has no null row or column, i.e. no degree-of-freedom without stiffness, done by the solvers before factorizing it, and a cheap test of symmetry, used to select the eigenvalue solvers of symmetric or unsymmetric matrices.

pyfe3d.solver.sparseutils.NUM_LISTED_DOFS = 10

Largest number of degrees-of-freedom listed by the error of check_null_rows_cols()

pyfe3d.solver.sparseutils.check_null_rows_cols(A, name='A')

Raise an error when a square matrix has a null row or column

Called by the solvers of pyfe3d.solver before factorizing the matrix, since a null row or column makes it singular.

Parameters:

Asparse_matrix or np.ndarray

Square matrix, shape (n, n).

namestr, optional

Name of the matrix in the error message. Default 'A'.

Raises:

numpy.linalg.LinAlgError

When a row or a column of A is null. The message gives the number of these degrees-of-freedom, the first NUM_LISTED_DOFS of their indices in A, and how to correct the model.

Notes

A row or column is null when none of its stored entries is non-zero, explicitly stored zeros being ignored; the cost is of the order of the number of stored entries of \(\boldsymbol{A}\).

In a finite element model, a null row or column of the matrix given to the solvers is a degree-of-freedom without stiffness, e.g. an unattached node, an unstiffened drilling rotation or a missing boundary condition, i.e. a modelling error, which is reported instead of being hidden. The known displacements are partitioned out before calling the solvers, e.g. KC0uu = KC0[bu, :][:, bu] with the boolean mask bu of the free degrees-of-freedom, or with Analysis(..., bu=bu), see FreeDofs. This deliberately differs from structsolve, whose semi-analytical Ritz models apply the boundary conditions by zeroing approximation functions, which leaves null rows and columns that its solvers remove.

pyfe3d.solver.sparseutils.is_symmetric(A, rtol=1e-10)

Tell whether a square matrix is symmetric, in the Frobenius norm

The matrix is symmetric when norm(A - A.T) <= rtol*norm(A), both in the Frobenius norm. The cost is of the order of the number of stored entries of A.

Parameters:

Asparse_matrix or np.ndarray

Square matrix, converted to scipy.sparse.csr_matrix.

rtolfloat, optional

Relative tolerance, dimensionless. Default 1.e-10.

Returns:

symmetricbool

True when A is symmetric to the relative tolerance rtol. A null matrix is symmetric.

Notes

The test is \(\|\boldsymbol{A} - \boldsymbol{A}^\top\|_F \le rtol \|\boldsymbol{A}\|_F\). The relative tolerance absorbs the round-off of matrices that are symmetric in exact arithmetic but assembled from terms evaluated in a different order on each side of the diagonal, whereas a genuinely unsymmetric term, such as the load stiffness of a follower load or the aerodynamic matrix of piston theory, gives a relative asymmetry that is not a round-off.