Skip to content

qten.validations.symbolics

Module reference for qten.validations.symbolics.

symbolics

Symbolic matrix validator factories.

This module provides reusable validators for dataclasses that store SymPy matrices. Each public function returns a validator compatible with need_validation(). The returned callable looks up a named attribute on the validated instance and raises when the stored matrix does not satisfy the requested symbolic constraint.

check_invertibility 

check_invertibility(
    attr_name: str,
) -> Callable[[Any], None]

Build a validator that enforces matrix invertibility on an instance attribute.

The returned callable looks up attr_name on the provided instance and verifies that the value is a sympy.ImmutableDenseMatrix with a non-zero determinant.

Returned validator raises

TypeError If the named attribute is not an immutable dense SymPy matrix. ValueError If the named matrix is singular.

Parameters:

Name Type Description Default
attr_name str

Name of the instance attribute expected to contain the symbolic matrix.

 required

Returns:

Type Description
Callable[[Any], None]

A validator callable suitable for use in attribute validation hooks.
Source code in src/qten/validations/symbolics.py 
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
def check_invertibility(attr_name: str) -> Callable[[Any], None]:
    """
    Build a validator that enforces matrix invertibility on an instance attribute.

    The returned callable looks up ``attr_name`` on the provided instance and
    verifies that the value is a `sympy.ImmutableDenseMatrix` with a non-zero
    determinant.

    Returned validator raises
    -------------------------
    TypeError
        If the named attribute is not an immutable dense SymPy matrix.
    ValueError
        If the named matrix is singular.

    Parameters
    ----------
    attr_name : str
        Name of the instance attribute expected to contain the symbolic matrix.

    Returns
    -------
    Callable[[Any], None]
        A validator callable suitable for use in attribute validation hooks.
    """

    def validator(instance: Any) -> None:
        matrix = getattr(instance, attr_name)
        if not isinstance(matrix, sy.ImmutableDenseMatrix):
            raise TypeError(f"{attr_name} must be an ImmutableDenseMatrix")
        if matrix.det() == 0:
            raise ValueError(f"{attr_name} must have non-zero determinant")

    return validator

check_proper_transformation 

check_proper_transformation(
    attr_name: str,
) -> Callable[[Any], None]

Build a validator that enforces a positive determinant on a matrix attribute.

The returned callable retrieves attr_name from the provided instance and verifies that the value is a sympy.ImmutableDenseMatrix whose determinant is strictly positive.

This validator is useful when the matrix represents an orientation-preserving linear transformation.

Returned validator raises

TypeError If the named attribute is not an immutable dense SymPy matrix. ValueError If the named matrix has a non-positive determinant.

Parameters:

Name Type Description Default
attr_name str

Name of the instance attribute expected to contain the symbolic matrix.

 required

Returns:

Type Description
Callable[[Any], None]

A validator callable suitable for use in attribute validation hooks.
Source code in src/qten/validations/symbolics.py 
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
def check_proper_transformation(attr_name: str) -> Callable[[Any], None]:
    """
    Build a validator that enforces a positive determinant on a matrix attribute.

    The returned callable retrieves ``attr_name`` from the provided instance and
    verifies that the value is a `sympy.ImmutableDenseMatrix` whose determinant
    is strictly positive.

    This validator is useful when the matrix represents an orientation-preserving
    linear transformation.

    Returned validator raises
    -------------------------
    TypeError
        If the named attribute is not an immutable dense SymPy matrix.
    ValueError
        If the named matrix has a non-positive determinant.

    Parameters
    ----------
    attr_name : str
        Name of the instance attribute expected to contain the symbolic matrix.

    Returns
    -------
    Callable[[Any], None]
        A validator callable suitable for use in attribute validation hooks.
    """

    def validator(instance: Any) -> None:
        matrix = getattr(instance, attr_name)
        if not isinstance(matrix, sy.ImmutableDenseMatrix):
            raise TypeError(f"{attr_name} must be an ImmutableDenseMatrix")
        if matrix.det() <= 0:
            raise ValueError(f"{attr_name} must have positive determinant")

    return validator

check_numerical 

check_numerical(attr_name: str) -> Callable[[Any], None]

Build a validator that enforces numerical matrix entries on an attribute.

The returned callable looks up attr_name on the provided instance and verifies that the value is a sympy.ImmutableDenseMatrix whose entries all report is_number as true.

Returned validator raises

TypeError If the named attribute is not an immutable dense SymPy matrix. ValueError If any matrix entry is symbolic or otherwise non-numeric.

Parameters:

Name Type Description Default
attr_name str

Name of the instance attribute expected to contain the symbolic matrix.

 required

Returns:

Type Description
Callable[[Any], None]

A validator callable suitable for use in attribute validation hooks.
Source code in src/qten/validations/symbolics.py 
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
def check_numerical(attr_name: str) -> Callable[[Any], None]:
    """
    Build a validator that enforces numerical matrix entries on an attribute.

    The returned callable looks up ``attr_name`` on the provided instance and
    verifies that the value is a `sympy.ImmutableDenseMatrix` whose entries all
    report `is_number` as true.

    Returned validator raises
    -------------------------
    TypeError
        If the named attribute is not an immutable dense SymPy matrix.
    ValueError
        If any matrix entry is symbolic or otherwise non-numeric.

    Parameters
    ----------
    attr_name : str
        Name of the instance attribute expected to contain the symbolic matrix.

    Returns
    -------
    Callable[[Any], None]
        A validator callable suitable for use in attribute validation hooks.
    """

    def validator(instance: Any) -> None:
        matrix = getattr(instance, attr_name)
        if not isinstance(matrix, sy.ImmutableDenseMatrix):
            raise TypeError(f"{attr_name} must be an ImmutableDenseMatrix")
        if any(not entry.is_number for entry in matrix):
            raise ValueError(f"{attr_name} must contain only numerical entries")

    return validator