Skip to content

Family operators

discrete_modulus.families.family_operators

Operator functors on families.

SumShortest 

SumShortest(F: Sequence[ShortestObjectFinder])

Shortest object operator for a summation of families.

Given a collection of families, finds the "sum" object obtained by combining the shortest object from each family -- i.e. implements ShortestObjectFinder for Gamma_1 + Gamma_2 + ... + Gamma_k.

Parameters:

Name Type Description Default
F sequence of ShortestObjectFinder

The finders for the families being summed.

 required
Source code in discrete_modulus/families/family_operators.py 
68
69
70
71
72
73
74
75
def __init__(self, F: Sequence[ShortestObjectFinder]) -> None:
    """
    Parameters
    ----------
    F : sequence of ShortestObjectFinder
        The finders for the families being summed.
    """
    self.F = F

__call__ 

__call__(
    rho: FloatArray | ExactArray, tol: float
) -> ShortestResult

Combines the shortest object from each family in the sum.

Parameters:

Name Type Description Default
rho numpy array

The current density.

 required
tol float

Passed through to each finder in F; otherwise unused here.

 required

Returns:

Type Description
ShortestResult

cons is the list of each family's individual result (in the order of F); n is the elementwise sum of their usage vectors, with the same dtype as rho.
Source code in discrete_modulus/families/family_operators.py 
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
def __call__(self, rho: FloatArray | ExactArray, tol: float) -> ShortestResult:
    """
    Combines the shortest object from each family in the sum.

    Parameters
    ----------
    rho : numpy array
        The current density.

    tol : float
        Passed through to each finder in `F`; otherwise unused here.

    Returns
    -------
    ShortestResult
        `cons` is the list of each family's individual result (in
        the order of `F`); `n` is the elementwise sum of their usage
        vectors, with the same dtype as `rho`.
    """

    # mypy can't infer, from a union-typed rho, that dtype=rho.dtype
    # produces a same-union-member array.
    n: FloatArray | ExactArray = np.zeros(rho.shape, dtype=rho.dtype)  # type: ignore[assignment]
    cons = []
    for f in self.F:
        result = f(rho, tol)
        assert result.n is not None
        cons.append(result.cons)
        n = n + result.n

    return ShortestResult(cons, n)

UnionShortest 

UnionShortest(F: Sequence[ShortestObjectFinder])

Shortest object operator for a union of families.

Given a collection of families (each represented by a ShortestObjectFinder), finds the single shortest object across all of them -- i.e. implements ShortestObjectFinder for Gamma_1 U Gamma_2 U ... U Gamma_k.

Parameters:

Name Type Description Default
F sequence of ShortestObjectFinder

The finders for the families being unioned.

 required
Source code in discrete_modulus/families/family_operators.py 
22
23
24
25
26
27
28
29
def __init__(self, F: Sequence[ShortestObjectFinder]) -> None:
    """
    Parameters
    ----------
    F : sequence of ShortestObjectFinder
        The finders for the families being unioned.
    """
    self.F = F

__call__ 

__call__(
    rho: FloatArray | ExactArray, tol: float
) -> ShortestResult

Finds the shortest object across all families in the union.

Parameters:

Name Type Description Default
rho numpy array

The current density.

 required
tol float

Passed through to each finder in F; otherwise unused here.

 required

Returns:

Type Description
ShortestResult

The result from whichever finder in F produced the object of smallest rho-length.
Source code in discrete_modulus/families/family_operators.py 
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
def __call__(self, rho: FloatArray | ExactArray, tol: float) -> ShortestResult:
    """
    Finds the shortest object across all families in the union.

    Parameters
    ----------
    rho : numpy array
        The current density.

    tol : float
        Passed through to each finder in `F`; otherwise unused here.

    Returns
    -------
    ShortestResult
        The result from whichever finder in `F` produced the object
        of smallest rho-length.
    """

    results = [f(rho, tol) for f in self.F]
    lengths = []
    for result in results:
        assert result.n is not None
        lengths.append(rho.dot(result.n))
    ind = np.argmin(lengths)
    return results[ind]