Skip to content

level

Level dataclass

Bases: FTyped[LT], ABC

An abstract base class representing a fiber allocator that manages fibers in a tensor.

Source code in src/finch/tensor/level/level.py 
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
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
@dataclass
class Level(FTyped[LT], ABC):
    """
    An abstract base class representing a fiber allocator that manages fibers in
    a tensor.
    """

    @property
    @abstractmethod
    def shape(self) -> tuple:
        """
        Shape of the fibers in the structure.
        """
        ...

    @property
    @abstractmethod
    def val(self) -> Any: ...

    @property
    def ndim(self):
        return self.ftype.ndim

    @property
    def fill_value(self):
        """The fill value itself; see `self.ftype.fill_value` for
        dynamic vs static."""
        return self.ftype.fill_value.value

    @property
    def element_type(self):
        return self.ftype.element_type

    @property
    def shape_type(self):
        return self.ftype.shape_type

    @property
    def position_type(self):
        return self.ftype.position_type

    @property
    def buffer_factory(self):
        return self.ftype.buffer_factory

    @property
    def buffer_type(self):
        return self.ftype.buffer_type

    @abstractmethod
    def with_fill(self, fill_value: AbstractFill) -> Self: ...

fill_value property

The fill value itself; see self.ftype.fill_value for dynamic vs static.

shape abstractmethod property

Shape of the fibers in the structure.

LevelFType dataclass

Bases: FType, ABC

An abstract base class representing the ftype of levels.

Source code in src/finch/tensor/level/level.py 
 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
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
@dataclass
class LevelFType(FType, ABC):
    """
    An abstract base class representing the ftype of levels.
    """

    def level_get_child_type(self, attr: str) -> LevelFType:
        match self:
            case StructFType() if self.struct_hasattr(attr):
                child = self.struct_attrtype(attr)
                match child:
                    case LevelFType():
                        return child
        raise TypeError(f"{self} does not support child {attr!r}")

    def level_get_child(
        self, obj: asm.AssemblyExpression, attr: str
    ) -> asm.AssemblyExpression:
        self.level_get_child_type(attr)
        return asm.GetAttr(obj, asm.Literal(attr))

    def with_fill(self, fill_value: Any) -> LevelFType:
        """Rebuild this level ftype with the leaf fill value replaced."""
        # Level ftypes are dataclasses with a `_lvl_t` child field; non-
        # dataclass levels must override.
        return replace(self, _lvl_t=self.lvl_t.with_fill(fill_value))  # type: ignore[type-var]

    def lower_fill(self, lvl_expr):
        """Assembly expression reading the runtime fill from the leaf level's
        fill field, descending from this level's struct expression."""
        return self.lvl_t.lower_fill(asm.GetAttr(lvl_expr, asm.Literal("lvl")))

    @property
    @abstractmethod
    def ndim(self):
        """
        Number of dimensions of the fibers in the structure.
        """
        ...

    @property
    @abstractmethod
    def fill_value(self) -> AbstractFill:
        """
        Fill value of the fibers, and whether kernels may specialize on it.
        Use `.value` for the value itself.
        """
        ...

    @property
    @abstractmethod
    def element_type(self) -> FType:
        """
        Type of elements stored in the fibers.
        """
        ...

    @property
    @abstractmethod
    def shape_type(self):
        """
        Tuple of types of the dimensions in the shape.
        """
        ...

    @property
    @abstractmethod
    def position_type(self):
        """
        Type of positions within the levels.
        """
        ...

    @property
    @abstractmethod
    def buffer_factory(self):
        """
        Function to create default buffers for the fibers.
        """
        ...

    @property
    @abstractmethod
    def buffer_type(self): ...

    @property
    @abstractmethod
    def lvl_t(self):
        """
        Get the nested level.
        """
        ...

    @abstractmethod
    def level_cost(self, fields, stats, stats_factory, num_pos, lvl):
        """
        Defines cost for a level
        """
        ...

    @abstractmethod
    def level_unfurl(self, ctx, lvl, ext, mode, proto, pos):
        """
        Emit code to unfurl the fiber at position `pos` in the level.
        """
        ...

    @abstractmethod
    def level_lower_freeze(self, ctx, lvl, op, pos):
        """
        Emit code to freeze `pos` previously assembled positions in the level.
        """
        ...

    def level_lower_assemble(self, ctx, lvl, start, stop):
        """Assemble parent positions in the half-open range [start, stop)."""
        raise NotImplementedError(
            f"Assembly is not implemented for {type(self).__name__}"
        )

    @abstractmethod
    def level_lower_thaw(self, ctx, lvl, op, pos):
        """
        Emit code to thaw `pos` previously assembled positions in the level.
        """
        ...

    @abstractmethod
    def level_lower_unwrap(self, ctx, obj, pos):
        """
        Emit code to return the unwrapped scalar at position `pos` in the level.
        """
        ...

    @abstractmethod
    def level_lower_increment(self, ctx, obj, op, val, pos):
        """
        Emit code to increment position `pos` in the level.
        """
        ...

    @abstractmethod
    def level_lower_declare(self, ctx, tns, init, op, shape, pos):
        """
        Emit code to lower a declare of `pos` previously assembled positions in
        the level.
        """
        ...

    @abstractmethod
    def level_lower_dim(self, ctx, obj, r):
        """
        Emit code to return the size of dimension `r` of the subtensors in the level.
        """
        ...

    @abstractmethod
    def construct(self, shape: tuple[Any, ...], *, pos: int) -> Level:
        """
        Construct a level instance with the given shape.
        """
        ...

    @abstractmethod
    def level_format_properties(self, n: int) -> list[FormatProperty]:
        """
        Return the format properties contributed by this level type and children.

        ``n`` is the outer dimension index represented by this level. Nested
        levels use increasing indices, so the returned properties can describe how
        this dimension constrains dimensions further inside the fiber tree.
        """
        ...

buffer_factory abstractmethod property

Function to create default buffers for the fibers.

element_type abstractmethod property

Type of elements stored in the fibers.

fill_value abstractmethod property

Fill value of the fibers, and whether kernels may specialize on it. Use .value for the value itself.

lvl_t abstractmethod property

Get the nested level.

ndim abstractmethod property

Number of dimensions of the fibers in the structure.

position_type abstractmethod property

Type of positions within the levels.

shape_type abstractmethod property

Tuple of types of the dimensions in the shape.

construct(shape, *, pos) abstractmethod

Construct a level instance with the given shape.

Source code in src/finch/tensor/level/level.py 
174
175
176
177
178
179
@abstractmethod
def construct(self, shape: tuple[Any, ...], *, pos: int) -> Level:
    """
    Construct a level instance with the given shape.
    """
    ...

level_cost(fields, stats, stats_factory, num_pos, lvl) abstractmethod

Defines cost for a level

Source code in src/finch/tensor/level/level.py 
111
112
113
114
115
116
@abstractmethod
def level_cost(self, fields, stats, stats_factory, num_pos, lvl):
    """
    Defines cost for a level
    """
    ...

level_format_properties(n) abstractmethod

Return the format properties contributed by this level type and children.

n is the outer dimension index represented by this level. Nested levels use increasing indices, so the returned properties can describe how this dimension constrains dimensions further inside the fiber tree.

Source code in src/finch/tensor/level/level.py 
181
182
183
184
185
186
187
188
189
190
@abstractmethod
def level_format_properties(self, n: int) -> list[FormatProperty]:
    """
    Return the format properties contributed by this level type and children.

    ``n`` is the outer dimension index represented by this level. Nested
    levels use increasing indices, so the returned properties can describe how
    this dimension constrains dimensions further inside the fiber tree.
    """
    ...

level_lower_assemble(ctx, lvl, start, stop)

Assemble parent positions in the half-open range [start, stop).

Source code in src/finch/tensor/level/level.py 
132
133
134
135
136
def level_lower_assemble(self, ctx, lvl, start, stop):
    """Assemble parent positions in the half-open range [start, stop)."""
    raise NotImplementedError(
        f"Assembly is not implemented for {type(self).__name__}"
    )

level_lower_declare(ctx, tns, init, op, shape, pos) abstractmethod

Emit code to lower a declare of pos previously assembled positions in the level.

Source code in src/finch/tensor/level/level.py 
159
160
161
162
163
164
165
@abstractmethod
def level_lower_declare(self, ctx, tns, init, op, shape, pos):
    """
    Emit code to lower a declare of `pos` previously assembled positions in
    the level.
    """
    ...

level_lower_dim(ctx, obj, r) abstractmethod

Emit code to return the size of dimension r of the subtensors in the level.

Source code in src/finch/tensor/level/level.py 
167
168
169
170
171
172
@abstractmethod
def level_lower_dim(self, ctx, obj, r):
    """
    Emit code to return the size of dimension `r` of the subtensors in the level.
    """
    ...

level_lower_freeze(ctx, lvl, op, pos) abstractmethod

Emit code to freeze pos previously assembled positions in the level.

Source code in src/finch/tensor/level/level.py 
125
126
127
128
129
130
@abstractmethod
def level_lower_freeze(self, ctx, lvl, op, pos):
    """
    Emit code to freeze `pos` previously assembled positions in the level.
    """
    ...

level_lower_increment(ctx, obj, op, val, pos) abstractmethod

Emit code to increment position pos in the level.

Source code in src/finch/tensor/level/level.py 
152
153
154
155
156
157
@abstractmethod
def level_lower_increment(self, ctx, obj, op, val, pos):
    """
    Emit code to increment position `pos` in the level.
    """
    ...

level_lower_thaw(ctx, lvl, op, pos) abstractmethod

Emit code to thaw pos previously assembled positions in the level.

Source code in src/finch/tensor/level/level.py 
138
139
140
141
142
143
@abstractmethod
def level_lower_thaw(self, ctx, lvl, op, pos):
    """
    Emit code to thaw `pos` previously assembled positions in the level.
    """
    ...

level_lower_unwrap(ctx, obj, pos) abstractmethod

Emit code to return the unwrapped scalar at position pos in the level.

Source code in src/finch/tensor/level/level.py 
145
146
147
148
149
150
@abstractmethod
def level_lower_unwrap(self, ctx, obj, pos):
    """
    Emit code to return the unwrapped scalar at position `pos` in the level.
    """
    ...

level_unfurl(ctx, lvl, ext, mode, proto, pos) abstractmethod

Emit code to unfurl the fiber at position pos in the level.

Source code in src/finch/tensor/level/level.py 
118
119
120
121
122
123
@abstractmethod
def level_unfurl(self, ctx, lvl, ext, mode, proto, pos):
    """
    Emit code to unfurl the fiber at position `pos` in the level.
    """
    ...

lower_fill(lvl_expr)

Assembly expression reading the runtime fill from the leaf level's fill field, descending from this level's struct expression.

Source code in src/finch/tensor/level/level.py 
45
46
47
48
def lower_fill(self, lvl_expr):
    """Assembly expression reading the runtime fill from the leaf level's
    fill field, descending from this level's struct expression."""
    return self.lvl_t.lower_fill(asm.GetAttr(lvl_expr, asm.Literal("lvl")))

with_fill(fill_value)

Rebuild this level ftype with the leaf fill value replaced.

Source code in src/finch/tensor/level/level.py 
39
40
41
42
43
def with_fill(self, fill_value: Any) -> LevelFType:
    """Rebuild this level ftype with the leaf fill value replaced."""
    # Level ftypes are dataclasses with a `_lvl_t` child field; non-
    # dataclass levels must override.
    return replace(self, _lvl_t=self.lvl_t.with_fill(fill_value))  # type: ignore[type-var]

MultiDimensionLevel dataclass

Bases: Level

Source code in src/finch/tensor/level/level.py 
265
266
267
268
269
270
class MultiDimensionLevel(Level):
    lvl: Level

    def with_fill(self, fill_value: AbstractFill) -> Self:
        """Rebuild this level with the leaf fill value replaced."""
        return replace(self, lvl=self.lvl.with_fill(fill_value))  # type: ignore[type-var, attr-defined]

with_fill(fill_value)

Rebuild this level with the leaf fill value replaced.

Source code in src/finch/tensor/level/level.py 
268
269
270
def with_fill(self, fill_value: AbstractFill) -> Self:
    """Rebuild this level with the leaf fill value replaced."""
    return replace(self, lvl=self.lvl.with_fill(fill_value))  # type: ignore[type-var, attr-defined]

SingleDimensionLevel dataclass

Bases: Level

Source code in src/finch/tensor/level/level.py 
257
258
259
260
261
262
class SingleDimensionLevel(Level):
    lvl: Level

    def with_fill(self, fill_value: AbstractFill) -> Self:
        """Rebuild this level with the leaf fill value replaced."""
        return replace(self, lvl=self.lvl.with_fill(fill_value))  # type: ignore[type-var, attr-defined]

with_fill(fill_value)

Rebuild this level with the leaf fill value replaced.

Source code in src/finch/tensor/level/level.py 
260
261
262
def with_fill(self, fill_value: AbstractFill) -> Self:
    """Rebuild this level with the leaf fill value replaced."""
    return replace(self, lvl=self.lvl.with_fill(fill_value))  # type: ignore[type-var, attr-defined]