custom_types

Custom data types for linear algebra decompositions and transformations.

This module defines data classes and types for representing various linear algebra decompositions (PLU, QR, SVD, etc.), shape properties, and mathematical structures used throughout the library.

Classes:

Shape –

Enumeration for different matrix shapes and structural properties.
Printable –

Base class for objects that can be printed as \(\rm\LaTeX\).
PartGen –

Represents a matrix as the sum of a particular solution and a general solution.
ScalarFactor –

Represents a matrix factored into a diagonal matrix and a full matrix.
PLU –

Represents a PLU decomposition of a matrix.
RREF –

Represents the reduced row echelon form (RREF) of a matrix.
RREFCase –

Represents one symbolic-RREF case produced by rref_cases.
VecDecomp –

Represents a vector decomposition into projection and normal components.
QR –

Represents a QR decomposition of a matrix.
PDP –

Represents a PDP diagonalization of a matrix.
SVD –

Represents a symbolic Singular Value Decomposition (SVD) of a matrix.
NumSVD –

Represents a numerical Singular Value Decomposition (SVD) of a matrix.

`Shape` ¶

Bases: Enum

Enumeration for different matrix shapes and structural properties.

This enum defines various matrix shapes that can be used to specify the structure of matrices in mathematical operations and optimizations. Each shape represents a specific pattern of zero and non-zero elements.

Examples:

Python Console Session
>>> shape = Shape.SYMMETRIC
>>> print(shape.value)
SYMMETRIC

Attributes:

DIAGONAL –

Diagonal matrix.
SCALAR –

Scalar matrix (diagonal matrix with equal diagonal entries).
STRICT_UPPER –

Strictly upper triangular matrix.
STRICT_LOWER –

Strictly lower triangular matrix.
UPPER –

Upper triangular matrix.
LOWER –

Lower triangular matrix.
SYMMETRIC –

Symmetric matrix.

`DIAGONAL = 'DIAGONAL'` `class-attribute` `instance-attribute` ¶

Diagonal matrix.

A matrix where all off-diagonal entries are zero. Only elements on the main diagonal (\(i,j\) where \(i = j\)) can be non-zero. The diagonal entries can have different values and need not be square (unlike SCALAR matrices).

Example

\[ \begin{pmatrix} a & 0 & 0 \\ 0 & b & 0 \\ 0 & 0 & c \end{pmatrix} \]

`SCALAR = 'SCALAR'` `class-attribute` `instance-attribute` ¶

Scalar matrix (diagonal matrix with equal diagonal entries).

A square matrix where all diagonal entries are equal to the same scalar value, and all off-diagonal entries are zero. This is also known as a scalar matrix or scalar multiple of the identity matrix.

Example

\[ \begin{pmatrix} c & 0 & 0 \\ 0 & c & 0 \\ 0 & 0 & c \end{pmatrix} \]

`STRICT_UPPER = 'STRICT_UPPER'` `class-attribute` `instance-attribute` ¶

Strictly upper triangular matrix.

A matrix where all elements on and below the main diagonal are zero. Only elements above the main diagonal (\(i,j\) where \(i < j\)) can be non-zero.

Example

\[ \begin{pmatrix} 0 & a & b \\ 0 & 0 & c \\ 0 & 0 & 0 \end{pmatrix} \]

`STRICT_LOWER = 'STRICT_LOWER'` `class-attribute` `instance-attribute` ¶

Strictly lower triangular matrix.

A matrix where all elements on and above the main diagonal are zero. Only elements below the main diagonal (\(i,j\) where \(i > j\)) can be non-zero.

Example

\[ \begin{pmatrix} 0 & 0 & 0 \\ a & 0 & 0 \\ b & c & 0 \end{pmatrix} \]

`UPPER = 'UPPER'` `class-attribute` `instance-attribute` ¶

Upper triangular matrix.

A matrix where all elements below the main diagonal are zero. Elements on and above the main diagonal (\(i,j\) where \(i <= j\)) can be non-zero.

Example

\[ \begin{pmatrix} a & b & c \\ 0 & d & e \\ 0 & 0 & f \end{pmatrix} \]

`LOWER = 'LOWER'` `class-attribute` `instance-attribute` ¶

Lower triangular matrix.

A matrix where all elements above the main diagonal are zero. Elements on and below the main diagonal (\(i,j\) where \(i >= j\)) can be non-zero.

Example

\[ \begin{pmatrix} a & 0 & 0 \\ b & c & 0 \\ d & e & f \end{pmatrix} \]

`SYMMETRIC = 'SYMMETRIC'` `class-attribute` `instance-attribute` ¶

Symmetric matrix.

A square matrix where elements are symmetric about the main diagonal, meaning \(A_{i, j} = A_{j,i}\) for all valid indices \(i\) and \(j\).

Example

\[ \begin{pmatrix} a & b & c \\ b & d & e \\ c & e & f \end{pmatrix} \]

`Printable()` `dataclass` ¶

Base class for objects that can be printed as \(\rm\LaTeX\).

Methods:

eval –

Evaluates the object to a matrix.
evalf –

Evaluates the object to a matrix of floats.

`eval() -> Matrix` `abstractmethod` ¶

Evaluates the object to a matrix.

Source code in src/ma1522/custom_types.py

Python
@abstractmethod
def eval(self) -> Matrix:
    """Evaluates the object to a matrix."""
    ...

`evalf(*args, **kwargs)` ¶

Evaluates the object to a matrix of floats.

`PartGen(part_sol: Matrix, gen_sol: Matrix)` `dataclass` ¶

Bases: Printable

Represents a matrix as the sum of a particular solution and a general solution.

This dataclass is used to express the general solution to a linear system as the sum of a particular solution (with all free variables set to zero) and a general solution (the homogeneous part).

Attributes:

part_sol (Matrix) –

The particular solution matrix.
gen_sol (Matrix) –

The general (homogeneous) solution matrix.

Methods:

eval –

Evaluate and return the full solution matrix.

`eval() -> Matrix` ¶

Evaluate and return the full solution matrix.

Returns:

Matrix –

The sum of the particular and general solutions.

Source code in src/ma1522/custom_types.py

Python
def eval(self) -> Matrix:
    """Evaluate and return the full solution matrix.

    Returns:
        The sum of the particular and general solutions.
    """
    return (self.part_sol + self.gen_sol).doit()

`ScalarFactor(diag: Matrix, full: Matrix, order: Literal['FD', 'DF'])` `dataclass` ¶

Bases: Printable

Represents a matrix factored into a diagonal matrix and a full matrix.

This dataclass is used to express a matrix as the product of a diagonal matrix (containing scalar factors) and a matrix with the common divisors factored out. The order of multiplication is specified by the 'order' attribute.

Attributes:

diag (Matrix) –

The diagonal matrix containing the scalar factors.
full (Matrix) –

The matrix with common divisors factored out.
order (Literal['FD', 'DF']) –

The order of multiplication, either 'FD' (full @ diag) or 'DF' (diag @ full).

Methods:

eval –

Evaluate and return the factored matrix.

`eval() -> Matrix` ¶

Evaluate and return the factored matrix.

Returns:

Matrix –

The product of the full matrix and diagonal matrix in the specified order.

Source code in src/ma1522/custom_types.py

Python
def eval(self) -> Matrix:
    """Evaluate and return the factored matrix.

    Returns:
        The product of the full matrix and diagonal matrix in the specified order.
    """
    if self.order == "FD":
        return (self.full @ self.diag).doit()
    else:
        return (self.diag @ self.full).doit()

`PLU(P: Matrix, L: Matrix, U: Matrix)` `dataclass` ¶

Bases: Printable

Represents a PLU decomposition of a matrix.

This dataclass stores the permutation matrix (P), lower triangular matrix (L), and upper triangular matrix (U) such that the original matrix can be written as P @ L @ U.

Attributes:

P (Matrix) –

The permutation matrix.
L (Matrix) –

The lower triangular matrix.
U (Matrix) –

The upper triangular matrix.

Methods:

eval –

Evaluate and return the original matrix from PLU decomposition.

`eval() -> Matrix` ¶

Evaluate and return the original matrix from PLU decomposition.

Returns:

Matrix –

The product P @ L @ U.

Source code in src/ma1522/custom_types.py

Python
def eval(self) -> Matrix:
    """Evaluate and return the original matrix from PLU decomposition.

    Returns:
        The product P @ L @ U.
    """
    return (self.P @ self.L @ self.U).doit()

`RREF(rref: Matrix, pivots: tuple[int, ...])` `dataclass` ¶

Bases: Printable

Represents the reduced row echelon form (RREF) of a matrix.

This dataclass stores the RREF of a matrix and the tuple of pivot column indices.

Attributes:

rref (Matrix) –

The matrix in reduced row echelon form.
pivots (tuple[int, ...]) –

The indices of the pivot columns.

Methods:

eval –

Evaluate and return the RREF matrix.

`eval() -> Matrix` ¶

Evaluate and return the RREF matrix.

Returns:

Matrix –

The reduced row echelon form.

Source code in src/ma1522/custom_types.py

Python
def eval(self) -> Matrix:
    """Evaluate and return the RREF matrix.

    Returns:
        The reduced row echelon form.
    """
    return self.rref

`RREFCase(conditions: dict, excluded: list, rref: Matrix, pivots: tuple, free_params: int, is_consistent: bool | None)` `dataclass` ¶

Bases: Printable

Represents one symbolic-RREF case produced by rref_cases.

When a pivot entry contains free symbols that may equal zero, the RREF procedure branches into separate cases. Each branch yields one RREFCase describing the conditions assumed, the resulting RREF, and derived solution information.

Attributes:

conditions (dict) –

Substitution map {symbol: value} that defines this case (e.g. {a: 0} means "this case holds when a = 0").
excluded (list[dict]) –

Zero-conditions found in other branches that are not assumed here. Redundant alternatives for symbols already fixed in conditions are omitted.
rref (Matrix) –

The RREF matrix (augmented with the RHS if one was supplied to rref_cases.
pivots (tuple[int, ...]) –

Column indices of the pivot positions.
free_params (int) –

Number of free parameters in the solution (= n_var_cols - len(pivots) restricted to variable columns).
is_consistent (bool | None) –

Whether the system is consistent under these conditions. None when no RHS was provided.

Methods:

eval –

Evaluate and return the RREF matrix for this case.

`eval() -> Matrix` ¶

Evaluate and return the RREF matrix for this case.

Returns:

Matrix –

The reduced row echelon form for this particular case.

Source code in src/ma1522/custom_types.py

Python
def eval(self) -> Matrix:
    """Evaluate and return the RREF matrix for this case.

    Returns:
        The reduced row echelon form for this particular case.
    """
    return self.rref

`VecDecomp(proj: Matrix, norm: Matrix)` `dataclass` ¶

Bases: Printable

Represents a vector decomposition into projection and normal components.

This dataclass is used to express a vector as the sum of its projection onto a subspace and its orthogonal component.

Attributes:

proj (Matrix) –

The projection component.
norm (Matrix) –

The orthogonal (normal) component.

Methods:

eval –

Evaluate and return the original vector from decomposition.

`eval() -> Matrix` ¶

Evaluate and return the original vector from decomposition.

Returns:

Matrix –

The sum of the projection and normal components.

Source code in src/ma1522/custom_types.py

Python
def eval(self) -> Matrix:
    """Evaluate and return the original vector from decomposition.

    Returns:
        The sum of the projection and normal components.
    """
    return (self.proj + self.norm).doit()

`QR(Q: Matrix, R: Matrix)` `dataclass` ¶

Bases: Printable

Represents a QR decomposition of a matrix.

This dataclass stores the orthogonal matrix (Q) and the upper triangular matrix (R) such that the original matrix = Q @ R.

Attributes:

Q (Matrix) –

The orthogonal matrix.
R (Matrix) –

The upper triangular matrix.

Methods:

eval –

Evaluate and return the original matrix from QR decomposition.

`eval() -> Matrix` ¶

Evaluate and return the original matrix from QR decomposition.

Returns:

Matrix –

The product Q @ R.

Source code in src/ma1522/custom_types.py

Python
def eval(self) -> Matrix:
    """Evaluate and return the original matrix from QR decomposition.

    Returns:
        The product Q @ R.
    """
    return (self.Q @ self.R).doit()

`PDP(P: Matrix, D: Matrix)` `dataclass` ¶

Bases: Printable

Represents a PDP diagonalization of a matrix.

This dataclass stores the matrices P and D such that the original matrix = P @ D @ P^{-1}.

Attributes:

P (Matrix) –

The matrix of eigenvectors.
D (Matrix) –

The diagonal matrix of eigenvalues.

Methods:

eval –

Evaluate and return the original matrix from PDP diagonalization.

`eval() -> Matrix` ¶

Evaluate and return the original matrix from PDP diagonalization.

Returns:

Matrix –

The product P @ D @ P^(-1).

Source code in src/ma1522/custom_types.py

Python
def eval(self) -> Matrix:
    """Evaluate and return the original matrix from PDP diagonalization.

    Returns:
        The product P @ D @ P^(-1).
    """
    return (self.P @ self.D @ self.P.inv()).doit()

`SVD(U: Matrix, S: Matrix, V: Matrix)` `dataclass` ¶

Bases: Printable

Represents a symbolic Singular Value Decomposition (SVD) of a matrix.

This dataclass stores the matrices U, S, and V such that the original matrix = U @ S @ V.T.

Attributes:

U (Matrix) –

The left singular vectors.
S (Matrix) –

The diagonal matrix of singular values.
V (Matrix) –

The right singular vectors.

Methods:

eval –

Evaluate and return the original matrix from SVD.

`eval() -> Matrix` ¶

Evaluate and return the original matrix from SVD.

Returns:

Matrix –

The product U @ S @ V.T.

Source code in src/ma1522/custom_types.py

Python
def eval(self) -> Matrix:
    """Evaluate and return the original matrix from SVD.

    Returns:
        The product U @ S @ V.T.
    """
    return (self.U @ self.S @ self.V.T).doit()

`NumSVD` ¶

Bases: NamedTuple

Represents a numerical Singular Value Decomposition (SVD) of a matrix.

This named tuple stores the numerical matrices U, S, and V from a numerical SVD computation.

Attributes:

U (NDArray) –

The left singular vectors.
S (NDArray) –

The diagonal matrix of singular values.
V (NDArray) –

The right singular vectors.

Methods:

eval –

Evaluate and return the original matrix from numerical SVD.

`eval() -> np.typing.NDArray` ¶

Evaluate and return the original matrix from numerical SVD.

Returns:

NDArray –

The product U @ S @ V.T.

Source code in src/ma1522/custom_types.py

Python
def eval(self) -> np.typing.NDArray:
    """Evaluate and return the original matrix from numerical SVD.

    Returns:
        The product U @ S @ V.T.
    """
    return self.U @ self.S @ self.V.T

custom_types

Shape ¶

DIAGONAL = 'DIAGONAL' class-attribute instance-attribute ¶

SCALAR = 'SCALAR' class-attribute instance-attribute ¶

STRICT_UPPER = 'STRICT_UPPER' class-attribute instance-attribute ¶

STRICT_LOWER = 'STRICT_LOWER' class-attribute instance-attribute ¶

UPPER = 'UPPER' class-attribute instance-attribute ¶

LOWER = 'LOWER' class-attribute instance-attribute ¶

SYMMETRIC = 'SYMMETRIC' class-attribute instance-attribute ¶

Printable() dataclass ¶

eval() -> Matrix abstractmethod ¶

evalf(*args, **kwargs) ¶

PartGen(part_sol: Matrix, gen_sol: Matrix) dataclass ¶

eval() -> Matrix ¶

ScalarFactor(diag: Matrix, full: Matrix, order: Literal['FD', 'DF']) dataclass ¶

eval() -> Matrix ¶

PLU(P: Matrix, L: Matrix, U: Matrix) dataclass ¶

eval() -> Matrix ¶

RREF(rref: Matrix, pivots: tuple[int, ...]) dataclass ¶

eval() -> Matrix ¶

RREFCase(conditions: dict, excluded: list, rref: Matrix, pivots: tuple, free_params: int, is_consistent: bool | None) dataclass ¶

eval() -> Matrix ¶

VecDecomp(proj: Matrix, norm: Matrix) dataclass ¶

eval() -> Matrix ¶

QR(Q: Matrix, R: Matrix) dataclass ¶

eval() -> Matrix ¶

PDP(P: Matrix, D: Matrix) dataclass ¶

eval() -> Matrix ¶

SVD(U: Matrix, S: Matrix, V: Matrix) dataclass ¶

eval() -> Matrix ¶

NumSVD ¶

eval() -> np.typing.NDArray ¶

`Shape` ¶

`DIAGONAL = 'DIAGONAL'` `class-attribute` `instance-attribute` ¶

`SCALAR = 'SCALAR'` `class-attribute` `instance-attribute` ¶

`STRICT_UPPER = 'STRICT_UPPER'` `class-attribute` `instance-attribute` ¶

`STRICT_LOWER = 'STRICT_LOWER'` `class-attribute` `instance-attribute` ¶

`UPPER = 'UPPER'` `class-attribute` `instance-attribute` ¶

`LOWER = 'LOWER'` `class-attribute` `instance-attribute` ¶

`SYMMETRIC = 'SYMMETRIC'` `class-attribute` `instance-attribute` ¶

`Printable()` `dataclass` ¶

`eval() -> Matrix` `abstractmethod` ¶

`evalf(*args, **kwargs)` ¶

`PartGen(part_sol: Matrix, gen_sol: Matrix)` `dataclass` ¶

`eval() -> Matrix` ¶

`ScalarFactor(diag: Matrix, full: Matrix, order: Literal['FD', 'DF'])` `dataclass` ¶

`eval() -> Matrix` ¶

`PLU(P: Matrix, L: Matrix, U: Matrix)` `dataclass` ¶

`eval() -> Matrix` ¶

`RREF(rref: Matrix, pivots: tuple[int, ...])` `dataclass` ¶

`eval() -> Matrix` ¶

`RREFCase(conditions: dict, excluded: list, rref: Matrix, pivots: tuple, free_params: int, is_consistent: bool | None)` `dataclass` ¶

`eval() -> Matrix` ¶

`VecDecomp(proj: Matrix, norm: Matrix)` `dataclass` ¶

`eval() -> Matrix` ¶

`QR(Q: Matrix, R: Matrix)` `dataclass` ¶

`eval() -> Matrix` ¶

`PDP(P: Matrix, D: Matrix)` `dataclass` ¶

`eval() -> Matrix` ¶

`SVD(U: Matrix, S: Matrix, V: Matrix)` `dataclass` ¶

`eval() -> Matrix` ¶

`NumSVD` ¶

`eval() -> np.typing.NDArray` ¶