ddg.math.symmetric_matrices module

Utility functions for symmetric matrices. Includes diagonalization, and projective/affine normalization.

class ddg.math.symmetric_matrices.Signature(plus: int, minus: int, zero: int = 0)[source]

Bases: object

Projective signature class.

Two projective signatures are equal if and only if quadrics with those signatures are related by a projective transformation.

We want to identify:

Signatures
Quadrics up to projective transformation
Normalized matrices up to nonzero scalar multiplication (-1 in particular), which will be the result of e.g. projective_normalization().

To achieve this, we define a normalized matrix as a diagonal matrix

 I_n |      |
-----|------|---
     | -I_m |
-----|------|---
     |      | 0

or

 -I_n |     |
------|-----|---
      | I_m |
------|-----|---
      |     | 0

where I_n is the (n x n)-identity matrix, 0 means a 0 matrix and n >= m.

Parameters:

plusint
minusint
zeroint (default=0): Number of 1, -1, 0 on the diagonal.

plus: int

minus: int

zero: int = 0

property matrix

Returns the normalized matrix corresponding to the signature.

See the class docstring for how this is defined.

Returns:

numpy.ndarray of shape (n, n)

Notes

This method respects the sign the signature is initialized with, even though the equality operator does not.

property is_degenerate

Whether this is the signature of a degenerate quadric.

Returns:

bool

property rank

Rank of associated matrix.

Returns:

int

property is_positive_definite

Whether the signature is positive definite.

Meaning, if q is a quadratic form with this signature, q(p,p) > 0 for all p != 0.

Returns:

bool

property is_negative_definite

Whether the signature is negative definite.

Meaning, if q is a quadratic form with this signature, q(p,p) < 0 for all p != 0.

Returns:

bool

property is_positive_semi_definite

Whether the signature is positive semi-definite.

Meaning, if q is a quadratic form with this signature, q(p,p) >= 0 for all p.

Returns:

bool

property is_negative_semi_definite

Whether the signature is negative semi-definite.

Meaning, if q is a quadratic form with this signature, q(p,p) <= 0 for all p.

Returns:

bool

property is_indefinite

Whether the signature is positive definite.

Meaning, if q is a quadratic form with this signature, q can have both positive and negative values.

Returns:

bool

property is_definite

Whether the signature is either positive or negative definite.

Returns:

bool

property is_semi_definite

Whether the signature is either positive or negative semi-definite.

Returns:

bool

class ddg.math.symmetric_matrices.AffineSignature(plus: int, minus: int, zero: int = 0, affine_component_entry: Optional[Union[int, str]] = None, affine_component: int = -1)[source]

Bases: Signature

Affine signature class.

Two affine signatures are equal if and only if quadrics with those signatures are related by an affine transformation.

We want to identify:

Affine signatures
Quadrics up to affine transformation
Normalized matrices up to nonzero scalar multiplication (-1 in particular), which will be the result of e.g. affine_normalization().

To achieve this, we define what a normalized matrix is as follows:

In the non-parabolic case: A diagonal matrix with only 1, -1 and 0 on the diagonal. The diagonal without the entry at i looks as follows:

If diag[i] == 0: (s,…,s, -s,…,-s, 0,…,0), and the number of s’s is greater than or equal to the number of -s’s.
If diag[i] == s != 0: (s,…,s, -s,…,-s, 0,…,0).

In the parabolic case: a matrix of the form

 D1 |     |
----|-----|----
    | 0 s |
    | s 0 |     < i
----|-----|----
    |     | D2
        ^
        i

for i != 0 or, for i == 0,

 0 |   | s
---|---|---
   | D |
---|---|---
 s |   | 0

where D1, D2 and D are diagonal matrices with only 1, -1 and 0 on the diagonal. The diagonal is sorted in the order s, -s, 0 except at positions i and i-1 and the number of s’s is greater than or equal to the number of -s’s.

Note that for parabolic cases, flipping the sign of the diagonal is the same as flipping the sign of the off-diagonal entries, which as an affine transformation is a reflection about the plane x_{i-1} = 0.

Parameters:

plusint
minusint
zeroint (default=0): Number of 1, -1 or 0 on the diagonal of the diagonalized matrix. Note that for parabolic cases, these will not be the counts on the diagonal: A 1 and a -1 will be replaced by a 0 and entries on the off-diagonal, see above.
affine_component_entry1, -1, 0 or ‘parabolic’ (default=None): The entry at affine_component on the diagonal. A value of ‘parabolic’ means the matrix [[0, 1], [1, 0]], see above for details. This can be omitted (left as None) if only one of plus, minus or zero is nonzero.
affine_componentint (default=-1)

Raises:

ValueError

If affine_component_entry is ‘parabolic’ and plus or minus are 0
If affine_component_entry was not given and could not be inferred uniquely.
If affine_component_entry was given and is not 1, -1, 0 or ‘parabolic’.

plus: int

minus: int

zero: int = 0

affine_component_entry: Optional[Union[int, str]] = None

affine_component: int = -1

property matrix

Return normalized matrix corresponding to the signature.

See the class docstring for how this is defined.

Returns:

numpy.ndarray of shape (n, n)

Notes

This method respects the sign the signature is initialized with, even though the equality operator does not.

property is_definite

Whether the signature is either positive or negative definite.

Returns:

bool

property is_degenerate

Whether this is the signature of a degenerate quadric.

Returns:

bool

property is_indefinite

Whether the signature is positive definite.

Meaning, if q is a quadratic form with this signature, q can have both positive and negative values.

Returns:

bool

property is_negative_definite

Whether the signature is negative definite.

Meaning, if q is a quadratic form with this signature, q(p,p) < 0 for all p != 0.

Returns:

bool

property is_negative_semi_definite

Whether the signature is negative semi-definite.

Meaning, if q is a quadratic form with this signature, q(p,p) <= 0 for all p.

Returns:

bool

property is_positive_definite

Whether the signature is positive definite.

Meaning, if q is a quadratic form with this signature, q(p,p) > 0 for all p != 0.

Returns:

bool

property is_positive_semi_definite

Whether the signature is positive semi-definite.

Meaning, if q is a quadratic form with this signature, q(p,p) >= 0 for all p.

Returns:

bool

property is_semi_definite

Whether the signature is either positive or negative semi-definite.

Returns:

bool

property rank

Rank of associated matrix.

Returns:

int

ddg.math.symmetric_matrices.signature_from_diagonal(diag)[source]

Create signature from diagonal.

Parameters:

diagnumpy.ndarray of shape (n,) or list: 1D array containing only 1, -1 and 0

Returns:

Signature

Raises:

ValueError: If diag contains entries other than 1, -1 or 0.

ddg.math.symmetric_matrices.affine_signature_from_diagonal(diag, parabolic=False, affine_component=-1)[source]

Create affine signature from diagonal.

Parameters:

diagnumpy.ndarray of shape (n,) or list: 1D array containing only 1, -1 and 0. If parabolic is True, this must have 0 at entries i and i-1, where i is affine_component.
parabolicbool (default=False)
affine_componentint (default=-1)

Returns:

AffineSignature

Raises:

ValueError

If diag contains entries other than 1, -1 or 0.
If parabolic is True and diag does not have 0 at positions i and i-1, where i is affine_component.

ddg.math.symmetric_matrices.symmetrize(A)[source]: Symmetrize square matrix

ddg.math.symmetric_matrices.is_symmetric(A, atol=1e-13, rtol=None)[source]

Checks whether A is symmetric

Notes

This function uses the global tolerance defaults if atol or rtol are set to None. See ddg.abc.NonExact for details.

ddg.math.symmetric_matrices.signature_sort_key(x)[source]: Order of signature values: positive, negative, zero For eigenvalues each class is sorted by absolute value (decreasing)

ddg.math.symmetric_matrices.diagonalize(A, sort_key=<function signature_sort_key>, atol=0, rtol=0)[source]

Diagonalization of symmetric matrix but with customizable order of eigenvalues. Uses np.linalg.eigh, then eigenvalues and eigenvectors. Makes eigenvalues close to zero exact.

Notes

This function uses the global tolerance defaults if atol or rtol are set to None. See ddg.abc.NonExact for details.

ddg.math.symmetric_matrices.projective_normalization(Q, atol=None, rtol=None)[source]

Bring quadric to normal form by projective transformation.

Returns signature sgn and transformation matrix A such that

A.T @ Q @ A == sgn.matrix

See Signature for more information.

Note that this means that the point transformation defined by A transforms sgn.matrix into Q.

Parameters:

Qnumpy.ndarray: Symmetric matrix.
atolfloat
rtolfloat

Returns:

sgnSignature
Anumpy.ndarray: Transformation matrix.

Notes

This function uses the global tolerance defaults if atol or rtol are set to None. See ddg.abc.NonExact for details.

ddg.math.symmetric_matrices.affine_normalization(Q, affine_component=-1, atol=None, rtol=None)[source]

Bring quadric to normal form by affine transformation.

Up to parabolic cases this means diagonalizing Q by an affine transformation.

Returns affine transformation A with affine component i such that

A.T @ Q @ A == sgn.matrix

See AffineSignature for more information.

Parameters:

Qnumpy.ndarray of shape (n,n): Symmetric matrix.
iint: Affine component.
atolfloat
rtolfloat

Returns:

sgnAffineSignature
Anumpy.ndarray of shape (n,n): Affine transformation.

Notes

This function uses the global tolerance defaults if atol or rtol are set to None. See ddg.abc.NonExact for details.

ddg.math.symmetric_matrices.symmetric_matrix_from_diagonal(sgn, parabolic=False, affine_component=-1)[source]

A normalized affine quadric can be reconstructed from its diagonal and the additional knowledge whether it is parabolic.

For what “parabolic” means, see the docstring of AffineSignature.

Parameters:

sgnnumpy.ndarray of shape (n,): Diagonal of the matrix.
parabolicbool (default=False): If this is True, sgn must have 0 at positions i and i-1, where i is affine_component.
affine_componentint (default=-1): Only used when parabolic is True.

Raises:

ddg.geometry.projective.exceptions.ValueError: When parabolic is True but there are no 0s at the relevant positions, see above.