Skip to content

Utilities

ablina.utils

A module providing utility functions for linear algebra operations.

symbols(names, field=None, **kwargs)

Return sympy symbols with the specified names and field.

Parameters:

Name Type Description Default
names str

The names of the symbols to create.

 required
field (R, C)

The field to constrain the symbols to. If R, symbols are real. If C, symbols are complex. If None, no field constraint is applied.

 R
**kwargs Any

Additional keyword arguments to pass to sympy.symbols.

 {}

Returns:

Type Description
Symbol or tuple of Symbol

The created symbol(s) with the specified constraints.
Source code in ablina/utils.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
def symbols(names: str, field: Field | None = None, **kwargs: Any) -> Any:
    """
    Return sympy symbols with the specified names and field.

    Parameters
    ----------
    names : str
        The names of the symbols to create.
    field : {R, C}, optional
        The field to constrain the symbols to. If ``R``, symbols are 
        real. If ``C``, symbols are complex. If None, no field constraint 
        is applied.
    **kwargs
        Additional keyword arguments to pass to sympy.symbols.

    Returns
    -------
    Symbol or tuple of Symbol
        The created symbol(s) with the specified constraints.
    """
    if field is None:
        return sp.symbols(names, **kwargs)
    if field is R:
        return sp.symbols(names, real=True, **kwargs)
    return sp.symbols(names, complex=True, **kwargs)

is_linear(expr, vars=None)

Check whether an expression is linear with respect to the given variables.

Parameters:

Name Type Description Default
expr Expr

The expression to check.

 required
vars iterable of Symbol

The variables to check linearity with respect to. If None, all variables in expr are checked.

 None

Returns:

Type Description
bool

True if the expression is linear with respect to the variables, otherwise False.
Source code in ablina/utils.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
def is_linear(expr: Any, vars: Iterable[Any] | None = None) -> bool:
    """
    Check whether an expression is linear with respect to the given variables.

    Parameters
    ----------
    expr : Expr
        The expression to check.
    vars : iterable of Symbol, optional
        The variables to check linearity with respect to. If None, all 
        variables in `expr` are checked.

    Returns
    -------
    bool
        True if the expression is linear with respect to the variables, 
        otherwise False.
    """
    if vars is None:
        vars = expr.free_symbols
    if not vars:
        return True
    try:
        terms = sp.Poly(expr, *vars).monoms()
    except sp.PolynomialError:
        return False  # Return False if not a polynomial

    for exponents in terms:
        if sum(exponents) not in (0, 1):
            return False
        if not all(i in (0, 1) for i in exponents):
            return False
    return True

is_empty(matrix)

Check whether a matrix is empty.

Parameters:

Name Type Description Default
matrix Matrix

The matrix to check.

 required

Returns:

Type Description
bool

True if the matrix contains no elements, otherwise False.
Source code in ablina/utils.py 
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
def is_empty(matrix: Any) -> bool:
    """
    Check whether a matrix is empty.

    Parameters
    ----------
    matrix : Matrix
        The matrix to check.

    Returns
    -------
    bool
        True if the matrix contains no elements, otherwise False.
    """
    mat = M(matrix)
    return mat.rows == 0 or mat.cols == 0

is_invertible(matrix)

Check whether a matrix is invertible.

Parameters:

Name Type Description Default
matrix Matrix

The matrix to check.

 required

Returns:

Type Description
bool

True if the matrix is invertible, otherwise False.
Source code in ablina/utils.py 
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
def is_invertible(matrix: Any) -> bool | None:
    """
    Check whether a matrix is invertible.

    Parameters
    ----------
    matrix : Matrix
        The matrix to check.

    Returns
    -------
    bool
        True if the matrix is invertible, otherwise False.
    """
    mat = M(matrix)
    if not mat.is_square:
        return False
    is_zero = mat.det().equals(0)
    return None if is_zero is None else not is_zero

is_orthogonal(matrix)

Check whether a matrix is orthogonal.

Parameters:

Name Type Description Default
matrix Matrix

The matrix to check.

 required

Returns:

Type Description
bool

True if the matrix is orthogonal, otherwise False.
See Also

is_unitary

Source code in ablina/utils.py 
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
def is_orthogonal(matrix: Any) -> bool | None:
    """
    Check whether a matrix is orthogonal.

    Parameters
    ----------
    matrix : Matrix
        The matrix to check.

    Returns
    -------
    bool
        True if the matrix is orthogonal, otherwise False.

    See Also
    --------
    is_unitary
    """
    mat = M(matrix)
    if not mat.is_square:
        return False
    identity = M.eye(mat.rows)
    return (mat @ mat.T).equals(identity)

is_unitary(matrix)

Check whether a matrix is unitary.

Parameters:

Name Type Description Default
matrix Matrix

The matrix to check.

 required

Returns:

Type Description
bool

True if the matrix is unitary, otherwise False.
See Also

is_orthogonal

Source code in ablina/utils.py 
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
def is_unitary(matrix: Any) -> bool | None:
    """
    Check whether a matrix is unitary.

    Parameters
    ----------
    matrix : Matrix
        The matrix to check.

    Returns
    -------
    bool
        True if the matrix is unitary, otherwise False.

    See Also
    --------
    is_orthogonal
    """
    mat = M(matrix)
    if not mat.is_square:
        return False
    identity = M.eye(mat.rows)
    return (mat @ mat.H).equals(identity)

is_normal(matrix)

Check whether a matrix is normal.

Parameters:

Name Type Description Default
matrix Matrix

The matrix to check.

 required

Returns:

Type Description
bool

True if the matrix is normal, otherwise False.
Source code in ablina/utils.py 
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
def is_normal(matrix: Any) -> bool | None:
    """
    Check whether a matrix is normal.

    Parameters
    ----------
    matrix : Matrix
        The matrix to check.

    Returns
    -------
    bool
        True if the matrix is normal, otherwise False.
    """
    mat = M(matrix)
    if not mat.is_square:
        return False
    adjoint = mat.H
    return (mat @ adjoint).equals(adjoint @ mat)

rref(matrix, remove=False)

Compute the reduced row echelon form of a matrix.

Parameters:

Name Type Description Default
matrix Matrix

The matrix to compute the rref of.

 required
remove bool

If True, all zero rows are removed from the result.

 False

Returns:

Type Description
Matrix

The reduced row echelon form of the matrix.
Source code in ablina/utils.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
def rref(matrix: Any, remove: bool = False) -> Matrix:
    """
    Compute the reduced row echelon form of a matrix.

    Parameters
    ----------
    matrix : Matrix
        The matrix to compute the rref of.
    remove : bool, default=False
        If True, all zero rows are removed from the result.

    Returns
    -------
    Matrix
        The reduced row echelon form of the matrix.
    """
    mat = M(matrix)
    rref, _ = mat.rref()
    if not remove:
        return M(rref)

    for i in range(rref.rows - 1, -1, -1):
        if any(rref.row(i)):
            break
        rref.row_del(i)
    return M(rref)

of_arity(func, arity)

Check whether a function can accept a given number of positional arguments.

Parameters:

Name Type Description Default
func callable

The function to check.

 required
arity int

The number of positional arguments to check for.

 required

Returns:

Type Description
bool

True if the function can accept arity positional arguments, otherwise False.
Source code in ablina/utils.py 
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
def of_arity(func: Callable[..., Any], arity: int) -> bool:
    """
    Check whether a function can accept a given number of positional arguments.

    Parameters
    ----------
    func : callable
        The function to check.
    arity : int
        The number of positional arguments to check for.

    Returns
    -------
    bool
        True if the function can accept `arity` positional arguments, 
        otherwise False.
    """
    try:
        sig = inspect.signature(func)
    except Exception:
        return False

    # Check for required keyword-only parameters
    # If any exist, function cannot be called with only positional args
    for param in sig.parameters.values():
        if (param.kind == inspect.Parameter.KEYWORD_ONLY 
            and param.default == inspect.Parameter.empty):
            return False

    has_var_positional = False
    min_positional = 0
    max_positional = 0

    for param in sig.parameters.values():
        if param.kind == inspect.Parameter.VAR_POSITIONAL:
            has_var_positional = True
        elif param.kind in (inspect.Parameter.POSITIONAL_ONLY, 
                            inspect.Parameter.POSITIONAL_OR_KEYWORD):
            max_positional += 1
            if param.default == inspect.Parameter.empty:
                min_positional += 1

    if has_var_positional:
        # Function can accept any number >= min_positional
        return arity >= min_positional
    else:
        # Function can accept exactly min_positional to max_positional
        return min_positional <= arity <= max_positional

add_attributes(cls, *attributes)

Dynamically create a subclass with additional attributes.

Creates a new class that inherits from the given class and adds the specified attributes as class attributes.

Parameters:

Name Type Description Default
cls type

The base class to subclass.

 required
*attributes Any

The attributes to add to the new class.

 ()

Returns:

Type Description
type

A new subclass with the added attributes.
Source code in ablina/utils.py 
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
def add_attributes(cls: type, *attributes: Any) -> type:
    """
    Dynamically create a subclass with additional attributes.

    Creates a new class that inherits from the given class and adds the 
    specified attributes as class attributes.

    Parameters
    ----------
    cls : type
        The base class to subclass.
    *attributes
        The attributes to add to the new class.

    Returns
    -------
    type
        A new subclass with the added attributes.
    """
    attributes = {attr.__name__: attr for attr in attributes}
    return type(f"{cls.__name__}_subclass", (cls,), attributes)

ablina.vs_utils

A module providing utility functions for vector space operations.

to_ns_matrix(n, constraints)

Return the matrix representation of the given linear constraints.

Parameters:

Name Type Description Default
n int

The dimension of the vector space (length of vectors).

 required
constraints list of str

The list of linear constraints.

 required

Returns:

Type Description
Matrix

A matrix with the linear constraints as rows.

Raises:

Type Description
ConstraintError

If any constraint has an invalid format.
Source code in ablina/vs_utils.py 
14
15
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
50
51
52
53
54
def to_ns_matrix(n: int, constraints: list[str]) -> Matrix:
    """
    Return the matrix representation of the given linear constraints.

    Parameters
    ----------
    n : int
        The dimension of the vector space (length of vectors).
    constraints : list of str
        The list of linear constraints.

    Returns
    -------
    Matrix
        A matrix with the linear constraints as rows.

    Raises
    ------
    ConstraintError
        If any constraint has an invalid format.
    """
    exprs = set()
    for constraint in constraints:
        exprs.update(split_constraint(constraint))

    mat = []
    allowed_vars = symbols(f"v:{n}")
    for expr in exprs:
        row = [0] * n
        try:
            expr = sympify(expr, allowed_vars)
        except Exception as e:
            raise ConstraintError("Invalid constraint format.") from e

        for var in expr.free_symbols:
            var_idx = int(var.name.lstrip("v"))
            var_coeff = expr.coeff(var, 1)
            row[var_idx] = var_coeff
        mat.append(row)

    return rref(mat, remove=True) if mat else M.zeros(0, n)

to_complement(matrix)

Return the complement of a matrix.

This function works bidirectionally: if given a null space matrix, it returns a row space matrix, and if given a row space matrix, it returns a null space matrix.

Parameters:

Name Type Description Default
matrix Matrix

The matrix to take the complement of.

 required

Returns:

Type Description
Matrix

The complement of matrix.
Source code in ablina/vs_utils.py 
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
def to_complement(matrix: Any) -> Matrix:
    """
    Return the complement of a matrix.

    This function works bidirectionally: if given a null space matrix, it 
    returns a row space matrix, and if given a row space matrix, it 
    returns a null space matrix.

    Parameters
    ----------
    matrix : Matrix
        The matrix to take the complement of.

    Returns
    -------
    Matrix
        The complement of `matrix`.
    """
    mat = M(matrix)
    if mat.rows == 0:
        return M.eye(mat.cols)

    basis = mat.nullspace()
    if not basis:
        return M.zeros(0, mat.cols)
    comp = M.hstack(*basis).T
    return rref(comp, remove=True)

ablina.parser

A module for parsing and processing mathematical expressions and constraints.

sympify(expr, allowed_vars=None)

Return the sympy representation of the given expression.

Parameters:

Name Type Description Default
expr str

The expression to convert to a sympy representation.

 required
allowed_vars iterable

The set of allowed variables in the expression.

 None

Returns:

Type Description
Any

The sympy representation of expr.

Raises:

Type Description
ParsingError

If expr contains variables not in allowed_vars.
Source code in ablina/parser.py 
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 sympify(expr: str, allowed_vars: Iterable[Any] | None = None) -> Any:
    """
    Return the sympy representation of the given expression.

    Parameters
    ----------
    expr : str
        The expression to convert to a sympy representation.
    allowed_vars : iterable, optional
        The set of allowed variables in the expression.

    Returns
    -------
    Any
        The sympy representation of `expr`.

    Raises
    ------
    ParsingError
        If `expr` contains variables not in `allowed_vars`.
    """
    # Filter unrecognized characters for safety (consider regex)
    expr = _sympify(expr, rational=True)  # evaluate flag
    if allowed_vars is not None:
        if not all(var in allowed_vars for var in expr.free_symbols):
            invalid_vars = expr.free_symbols - set(allowed_vars)
            raise ParsingError(f"Unrecognized variables found: {invalid_vars}")
    return expr

split_constraint(constraint)

Split a constraint with multiple relational operators into separate relations.

Parameters:

Name Type Description Default
constraint str

The constraint string to split, containing one or more "==" operators.

 required

Returns:

Name Type Description
relations set of str

A set of relation strings, each representing one equality from the constraint.
Source code in ablina/parser.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
def split_constraint(constraint: str) -> set[str]:
    """
    Split a constraint with multiple relational operators into separate 
    relations.

    Parameters
    ----------
    constraint : str
        The constraint string to split, containing one or more "==" operators.

    Returns
    -------
    relations : set of str
        A set of relation strings, each representing one equality from 
        the constraint.
    """
    exprs = constraint.split("==")
    expr_count = len(exprs)
    if expr_count == 1:
        raise ConstraintError('Constraints must include at least one "==".')

    eqs = set()
    for i in range(expr_count - 1):
        eq = f"{exprs[i]} - ({exprs[i + 1]})"
        eqs.add(eq)
    return eqs