Skip to content

NamedShape

Shape specification for named linear operators, pairing input and output dimension names.

torchlinops.nameddim.NamedShape

Bases: NamedDimCollection

A linop shape with input and output dimensions Inherit from this to define custom behavior - e.g. splitting ishape and oshape into subparts that are linked

Source code in src/torchlinops/nameddim/_namedshape.py 
 13
 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
 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
 89
 90
 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
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
class NamedShape(NamedDimCollection):
    """A linop shape with input and output dimensions
    Inherit from this to define custom behavior
    - e.g. splitting ishape and oshape into subparts that are linked
    """

    def __init__(
        self,
        ishape: Optional["Shape | NamedShape"],
        oshape: Optional[Shape] = None,
        **other_shapes,
    ):
        """Construct a NamedShape from input and output dimension names.

        Parameters
        ----------
        ishape : Shape or NamedShape or None
            Input dimension names.  If a ``NamedShape`` instance is passed,
            it is copied directly and *oshape* / *other_shapes* are ignored.
            If ``None``, defaults to the ellipsis shape ``('...',)``.
        oshape : Shape or None, optional
            Output dimension names.  If ``None`` while *ishape* is provided,
            the operator is treated as diagonal (``oshape = ishape``).  If
            both *ishape* and *oshape* are ``None``, both default to
            ``('...',)``.
        **other_shapes
            Additional named shape sequences stored alongside ishape and
            oshape (e.g. auxiliary dimensions for specialised operators).
        """
        # Pass-through
        if isinstance(ishape, type(self)):
            super().__init__(**ishape.shapes)
            return

        if oshape is None:
            if ishape is None:
                # Empty shape
                oshape = ("...",)
            else:
                # Diagonal
                oshape = ishape
        if ishape is None:
            ishape = ("...",)
        super().__init__(ishape=ishape, oshape=oshape, **other_shapes)

    @property
    def other_shapes(self):
        """Shapes that are not ishape or oshape."""
        other_shapes = self.shapes.copy()
        for name in ["ishape", "oshape"]:  # Special attributes
            other_shapes.pop(name)
        return other_shapes

    def adjoint(self):
        """Return a new NamedShape with ishape and oshape swapped.

        Override this method in subclasses that need custom adjoint
        behaviour (e.g. swapping auxiliary shapes as well).

        Returns
        -------
        NamedShape
            A new instance with ``ishape`` and ``oshape`` exchanged.
        """
        new = type(self)(self.oshape, self.ishape, **self.other_shapes)
        return new

    def normal(self):
        """Return the NamedShape for the normal operator (A^H A).

        The resulting shape has ``ishape`` equal to the original ``ishape``
        and ``oshape`` derived from ``ishape`` with indices incremented to
        avoid collisions, representing the domain-to-domain mapping of the
        normal equation.

        Returns
        -------
        NamedShape
            A new instance representing the normal operator shape.
        """
        # If a shape appears in both ishape and oshape, it is considered
        # "diagonal".
        new_oshape = []
        for d in self.ishape:
            if d in self.oshape:
                new_oshape.append(d)
            else:
                new_oshape.append(d.next_unused(self.ishape))
        new = type(self)(self.ishape, new_oshape, **self.other_shapes)
        return new

    @property
    def H(self) -> "NamedShape":
        """The adjoint NamedShape (ishape and oshape swapped)."""
        return self.adjoint()

    @property
    def N(self) -> "NamedShape":
        """The normal NamedShape for the operator A^H A."""
        return self.normal()

    def __repr__(self):
        return f"{self.ishape} -> {self.oshape}"

    def __add__(self, right) -> "NamedShape":
        try:
            _ishape = self.ishape + right.ishape
        except TypeError as e:
            raise TypeError(
                f"Problem combining shapes {self.ishape} + {right.ishape}"
            ) from e
        try:
            _oshape = self.oshape + right.oshape
        except TypeError as e:
            raise TypeError(
                f"Problem combining shapes {self.oshape} + {right.oshape}"
            ) from e
        new = type(self)(ishape=_ishape, oshape=_oshape)
        new.update(self.other_shapes)
        new.update(right.other_shapes)
        return new

    def __radd__(self, left):
        if left is None:
            return self
        return left.__add__(self)

    def __eq__(self, other):
        return isequal(self.ishape, other.ishape) and isequal(self.oshape, other.oshape)

H property 

H: NamedShape

The adjoint NamedShape (ishape and oshape swapped).

N property 

N: NamedShape

The normal NamedShape for the operator A^H A.

other_shapes property 

other_shapes

Shapes that are not ishape or oshape.

__init__ 

__init__(
    ishape: Optional[Shape | NamedShape],
    oshape: Optional[Shape] = None,
    **other_shapes,
)

Construct a NamedShape from input and output dimension names.

PARAMETER DESCRIPTION
ishape

Input dimension names. If a NamedShape instance is passed, it is copied directly and oshape / other_shapes are ignored. If None, defaults to the ellipsis shape ('...',).

TYPE: Shape or NamedShape or None

oshape

Output dimension names. If None while ishape is provided, the operator is treated as diagonal (oshape = ishape). If both ishape and oshape are None, both default to ('...',).

TYPE: Shape or None DEFAULT: None

**other_shapes

Additional named shape sequences stored alongside ishape and oshape (e.g. auxiliary dimensions for specialised operators).

DEFAULT: {}

Source code in src/torchlinops/nameddim/_namedshape.py 
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
55
56
def __init__(
    self,
    ishape: Optional["Shape | NamedShape"],
    oshape: Optional[Shape] = None,
    **other_shapes,
):
    """Construct a NamedShape from input and output dimension names.

    Parameters
    ----------
    ishape : Shape or NamedShape or None
        Input dimension names.  If a ``NamedShape`` instance is passed,
        it is copied directly and *oshape* / *other_shapes* are ignored.
        If ``None``, defaults to the ellipsis shape ``('...',)``.
    oshape : Shape or None, optional
        Output dimension names.  If ``None`` while *ishape* is provided,
        the operator is treated as diagonal (``oshape = ishape``).  If
        both *ishape* and *oshape* are ``None``, both default to
        ``('...',)``.
    **other_shapes
        Additional named shape sequences stored alongside ishape and
        oshape (e.g. auxiliary dimensions for specialised operators).
    """
    # Pass-through
    if isinstance(ishape, type(self)):
        super().__init__(**ishape.shapes)
        return

    if oshape is None:
        if ishape is None:
            # Empty shape
            oshape = ("...",)
        else:
            # Diagonal
            oshape = ishape
    if ishape is None:
        ishape = ("...",)
    super().__init__(ishape=ishape, oshape=oshape, **other_shapes)

adjoint 

adjoint()

Return a new NamedShape with ishape and oshape swapped.

Override this method in subclasses that need custom adjoint behaviour (e.g. swapping auxiliary shapes as well).

RETURNS DESCRIPTION
NamedShape

A new instance with ishape and oshape exchanged.
Source code in src/torchlinops/nameddim/_namedshape.py 
66
67
68
69
70
71
72
73
74
75
76
77
78
def adjoint(self):
    """Return a new NamedShape with ishape and oshape swapped.

    Override this method in subclasses that need custom adjoint
    behaviour (e.g. swapping auxiliary shapes as well).

    Returns
    -------
    NamedShape
        A new instance with ``ishape`` and ``oshape`` exchanged.
    """
    new = type(self)(self.oshape, self.ishape, **self.other_shapes)
    return new

normal 

normal()

Return the NamedShape for the normal operator (A^H A).

The resulting shape has ishape equal to the original ishape and oshape derived from ishape with indices incremented to avoid collisions, representing the domain-to-domain mapping of the normal equation.

RETURNS DESCRIPTION
NamedShape

A new instance representing the normal operator shape.
Source code in src/torchlinops/nameddim/_namedshape.py 
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
def normal(self):
    """Return the NamedShape for the normal operator (A^H A).

    The resulting shape has ``ishape`` equal to the original ``ishape``
    and ``oshape`` derived from ``ishape`` with indices incremented to
    avoid collisions, representing the domain-to-domain mapping of the
    normal equation.

    Returns
    -------
    NamedShape
        A new instance representing the normal operator shape.
    """
    # If a shape appears in both ishape and oshape, it is considered
    # "diagonal".
    new_oshape = []
    for d in self.ishape:
        if d in self.oshape:
            new_oshape.append(d)
        else:
            new_oshape.append(d.next_unused(self.ishape))
    new = type(self)(self.ishape, new_oshape, **self.other_shapes)
    return new