nodes

AssemblyExpression

Bases: AssemblyNode, ExpressionTerm

Assembly AST expression base class.

An assembly expression is a program node which evaluates to a value.

Source code in src/finch/finch_assembly/nodes.py

class AssemblyExpression(AssemblyNode, ExpressionTerm):
    """
    Assembly AST expression base class.

    An assembly expression is a program node which evaluates to a value.
    """

    @property
    @abstractmethod
    def result_type(self) -> BufferFType:
        """Returns the type of the expression."""
        ...

result_type abstractmethod property

Returns the type of the expression.

AssemblyNode

Bases: Term

AssemblyNode

Represents a FinchAssembly IR node. FinchAssembly is the final intermediate representation before code generation (translation to the output language). It is a low-level imperative description of the program, with control flow, linear memory regions called "buffers", and explicit memory management.

Source code in src/finch/finch_assembly/nodes.py

class AssemblyNode(Term):
    """
    AssemblyNode

    Represents a FinchAssembly IR node. FinchAssembly is the final intermediate
    representation before code generation (translation to the output language).
    It is a low-level imperative description of the program, with control flow,
    linear memory regions called "buffers", and explicit memory management.
    """

    @classmethod
    def head(cls):
        """Returns the head of the node."""
        return cls

    @classmethod
    def make_term(cls, head, *args):
        """Creates a term with the given head and arguments."""
        return head.from_children(*args)

    @classmethod
    def from_children(cls, *children):
        """
        Creates a term from the given children. This is used to create terms
        from the children of a node.
        """
        return cls(*children)

    def __str__(self):
        """Returns a string representation of the node."""
        ctx = AssemblyPrinterContext()
        res = ctx(self)
        return res if res is not None else ctx.emit()

__str__()

Returns a string representation of the node.

Source code in src/finch/finch_assembly/nodes.py

def __str__(self):
    """Returns a string representation of the node."""
    ctx = AssemblyPrinterContext()
    res = ctx(self)
    return res if res is not None else ctx.emit()

from_children(*children) classmethod

Creates a term from the given children. This is used to create terms from the children of a node.

Source code in src/finch/finch_assembly/nodes.py

@classmethod
def from_children(cls, *children):
    """
    Creates a term from the given children. This is used to create terms
    from the children of a node.
    """
    return cls(*children)

head() classmethod

Returns the head of the node.

Source code in src/finch/finch_assembly/nodes.py

@classmethod
def head(cls):
    """Returns the head of the node."""
    return cls

make_term(head, *args) classmethod

Creates a term with the given head and arguments.

Source code in src/finch/finch_assembly/nodes.py

@classmethod
def make_term(cls, head, *args):
    """Creates a term with the given head and arguments."""
    return head.from_children(*args)

AssemblyStatement

Bases: AssemblyNode

Assembly AST statement base class.

An assembly statement is a program node nested inside a function which does not produce a value, but may modify the state of the machine.

Source code in src/finch/finch_assembly/nodes.py

class AssemblyStatement(AssemblyNode):
    """
    Assembly AST statement base class.

    An assembly statement is a program node nested inside a function which does
    not produce a value, but may modify the state of the machine.
    """

AssemblyTree dataclass

Bases: AssemblyNode, TermTree

Source code in src/finch/finch_assembly/nodes.py

class AssemblyTree(AssemblyNode, TermTree):
    @property
    def children(self):
        """Returns the children of the node."""
        raise Exception(f"`children` isn't supported for {self.__class__}.")

children property

Returns the children of the node.

Assert dataclass

Bases: AssemblyTree, AssemblyStatement

Checks that an expression is true at runtime. Also used in dataflow analysis to record conditions in conditionals and loops.

Attributes:

Name	Type	Description
exp	AssemblyExpression	Expression which is being asserted.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Assert(AssemblyTree, AssemblyStatement):
    """
    Checks that an expression is true at runtime. Also used in dataflow analysis
    to record conditions in conditionals and loops.

    Attributes:
        exp: Expression which is being asserted.
    """

    exp: AssemblyExpression

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.exp]

children property

Returns the children of the node.

Assign dataclass

Bases: AssemblyTree, AssemblyStatement

Represents a logical AST statement that evaluates rhs, binding the result to lhs.

Attributes:

Name	Type	Description
lhs	Variable	The left-hand side of the binding.
rhs	AssemblyExpression	The right-hand side to evaluate.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Assign(AssemblyTree, AssemblyStatement):
    """
    Represents a logical AST statement that evaluates `rhs`, binding the result
    to `lhs`.

    Attributes:
        lhs: The left-hand side of the binding.
        rhs: The right-hand side to evaluate.
    """

    lhs: Variable
    rhs: AssemblyExpression

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.lhs, self.rhs]

children property

Returns the children of the node.

Block dataclass

Bases: AssemblyTree, AssemblyStatement

Represents a statement that executes a sequence of statements bodies....

Attributes:

Name	Type	Description
bodies	tuple[AssemblyStatement | AssemblyExpression, ...]	The sequence of statements to execute.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Block(AssemblyTree, AssemblyStatement):
    """
    Represents a statement that executes a sequence of statements `bodies...`.

    Attributes:
        bodies: The sequence of statements to execute.
    """

    bodies: tuple[AssemblyStatement | AssemblyExpression, ...] = ()

    @property
    def children(self):
        """Returns the children of the node."""
        return [*self.bodies]

    @classmethod
    def from_children(cls, *bodies):
        return cls(bodies)

children property

Returns the children of the node.

Break dataclass

Bases: AssemblyTree, AssemblyStatement

Represents a break statement that exits the current loop.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Break(AssemblyTree, AssemblyStatement):
    """
    Represents a break statement that exits the current loop.
    """

    @property
    def children(self):
        """Returns the children of the node."""
        return []

children property

Returns the children of the node.

BufferLoop dataclass

Bases: AssemblyTree, AssemblyStatement

Represents a loop that iterates over the elements of a buffer.

Attributes:

Name	Type	Description
buffer	AssemblyExpression	The buffer to iterate over.
var	Variable	The loop variable for each element in the buffer.
body	AssemblyStatement	The body of the loop to execute for each element.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class BufferLoop(AssemblyTree, AssemblyStatement):
    """
    Represents a loop that iterates over the elements of a buffer.

    Attributes:
        buffer: The buffer to iterate over.
        var: The loop variable for each element in the buffer.
        body: The body of the loop to execute for each element.
    """

    buffer: AssemblyExpression
    var: Variable
    body: AssemblyStatement

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.buffer, self.var, self.body]

children property

Returns the children of the node.

Call dataclass

Bases: AssemblyExpression, AssemblyTree, CallTerm

Represents an expression for calling the function op on args....

Attributes:

Name	Type	Description
op	AssemblyExpression	The function to call.
args	tuple[AssemblyExpression, ...]	The arguments to call on the function.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Call(AssemblyExpression, AssemblyTree, CallTerm):
    """
    Represents an expression for calling the function `op` on `args...`.

    Attributes:
        op: The function to call.
        args: The arguments to call on the function.
    """

    op: AssemblyExpression
    args: tuple[AssemblyExpression, ...]

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.op, *self.args]

    @classmethod
    def from_children(cls, op, *args):
        return cls(op, args)

    @property
    def result_type(self):
        """Returns the type of the expression."""
        arg_types = [arg.result_type for arg in self.args]
        op_type = self.op.result_type
        assert isinstance(op_type, CallableFType)
        return return_type(op_type, *arg_types)

children property

Returns the children of the node.

result_type property

Returns the type of the expression.

ForLoop dataclass

Bases: AssemblyTree, AssemblyStatement

Represents a for loop that iterates over a range of values.

Attributes:

Name	Type	Description
var	Variable	The loop variable.
start	AssemblyExpression	The starting value of the range.
end	AssemblyExpression	The ending value of the range.
body	AssemblyStatement	The body of the loop to execute.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class ForLoop(AssemblyTree, AssemblyStatement):
    """
    Represents a for loop that iterates over a range of values.

    Attributes:
        var: The loop variable.
        start: The starting value of the range.
        end: The ending value of the range.
        body: The body of the loop to execute.
    """

    var: Variable
    start: AssemblyExpression
    end: AssemblyExpression
    body: AssemblyStatement

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.var, self.start, self.end, self.body]

children property

Returns the children of the node.

Function dataclass

Bases: AssemblyTree

A module-level function definition with arguments args....

Attributes:

Name	Type	Description
name	Variable	The function variable, annotated with its AssemblyKernelFType.
args	tuple[Variable, ...]	The arguments to the function.
body	AssemblyStatement	The body of the function. If it does not contain a return statement, the function returns the value of body.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Function(AssemblyTree):
    """
    A module-level function definition with arguments `args...`.

    Attributes:
        name: The function variable, annotated with its AssemblyKernelFType.
        args: The arguments to the function.
        body: The body of the function. If it does not contain a return statement,
            the function returns the value of `body`.
    """

    name: Variable
    args: tuple[Variable, ...]
    body: AssemblyStatement

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.name, *self.args, self.body]

    @classmethod
    def from_children(cls, *children):
        """Creates a term with the given head and arguments."""
        name, *arg_nodes, body = children
        return cls(name, tuple(arg_nodes), body)

children property

Returns the children of the node.

from_children(*children) classmethod

Creates a term with the given head and arguments.

Source code in src/finch/finch_assembly/nodes.py

@classmethod
def from_children(cls, *children):
    """Creates a term with the given head and arguments."""
    name, *arg_nodes, body = children
    return cls(name, tuple(arg_nodes), body)

GetAttr dataclass

Bases: AssemblyExpression, AssemblyTree

Represents a getter for an attribute attr of an object obj. Attributes: obj: The object to get the attribute from. attr: The name of the attribute to get.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class GetAttr(AssemblyExpression, AssemblyTree):
    """
    Represents a getter for an attribute `attr` of an object `obj`.
    Attributes:
        obj: The object to get the attribute from.
        attr: The name of the attribute to get.
    """

    obj: AssemblyExpression
    attr: Literal

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.obj, self.attr]

    @property
    def result_type(self):
        """Returns the type of the expression."""
        assert isinstance(self.obj.result_type, StructFType)
        return dict(self.obj.result_type.struct_fields)[self.attr.val]

children property

Returns the children of the node.

result_type property

Returns the type of the expression.

If dataclass

Bases: AssemblyTree, AssemblyStatement

Represents an if statement that executes the body if the condition is true.

Attributes:

Name	Type	Description
condition	AssemblyExpression	The condition to evaluate for the if to execute the body.
body	AssemblyStatement	The body of the if statement to execute.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class If(AssemblyTree, AssemblyStatement):
    """
    Represents an if statement that executes the body if the condition is true.

    Attributes:
        condition: The condition to evaluate for the if to execute the body.
        body: The body of the if statement to execute.
    """

    condition: AssemblyExpression
    body: AssemblyStatement

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.condition, self.body]

children property

Returns the children of the node.

IfElse dataclass

Bases: AssemblyTree, AssemblyStatement

Represents an if-else statement that executes the body if the condition is true, otherwise executes else_body.

Attributes:

Name	Type	Description
condition	AssemblyExpression	The condition to evaluate for the if to execute the body.
body	AssemblyStatement	The body of the if statement to execute.
else_body	AssemblyStatement	An alternative body to execute if the condition is false.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class IfElse(AssemblyTree, AssemblyStatement):
    """
    Represents an if-else statement that executes the body if the condition
    is true, otherwise executes else_body.

    Attributes:
        condition: The condition to evaluate for the if to execute the body.
        body: The body of the if statement to execute.
        else_body: An alternative body to execute if the condition is false.
    """

    condition: AssemblyExpression
    body: AssemblyStatement
    else_body: AssemblyStatement

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.condition, self.body, self.else_body]

children property

Returns the children of the node.

Length dataclass

Bases: AssemblyExpression, AssemblyTree

Represents getting the length of a buffer.

Attributes:

Name	Type	Description
buffer	AssemblyExpression	The buffer whose length is queried.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Length(AssemblyExpression, AssemblyTree):
    """
    Represents getting the length of a buffer.

    Attributes:
        buffer: The buffer whose length is queried.
    """

    buffer: AssemblyExpression

    @property
    def children(self):
        return [self.buffer]

    @property
    def result_type(self):
        """Returns the type of the expression."""
        return length_type(self.buffer.result_type)

result_type property

Returns the type of the expression.

Literal dataclass

Bases: AssemblyExpression, LiteralTerm[T]

Represents the literal value val.

Attributes:

Name	Type	Description
val	T	The literal value.

Source code in src/finch/finch_assembly/nodes.py

class Literal(AssemblyExpression, LiteralTerm[T]):
    """
    Represents the literal value `val`.

    Attributes:
        val: The literal value.
    """

    @property
    def result_type(self):
        """Returns the type of the expression."""
        return ftype(self.val)

    def __repr__(self) -> str:
        return literal_repr(type(self).__name__, {"val": self.val})

result_type property

Returns the type of the expression.

Load dataclass

Bases: AssemblyExpression, AssemblyTree

Represents loading a value from a buffer at a given index.

Attributes:

Name	Type	Description
buffer	AssemblyExpression	The buffer to load from.
index	AssemblyExpression	The index to load at.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Load(AssemblyExpression, AssemblyTree):
    """
    Represents loading a value from a buffer at a given index.

    Attributes:
        buffer: The buffer to load from.
        index: The index to load at.
    """

    buffer: AssemblyExpression
    index: AssemblyExpression

    @property
    def children(self):
        return [self.buffer, self.index]

    @property
    def result_type(self) -> FType:
        """Returns the type of the expression."""
        assert isinstance(self.buffer.result_type, BufferFType)
        return self.buffer.result_type.element_type

result_type property

Returns the type of the expression.

Module dataclass

Bases: AssemblyTree

Represents a group of functions. This is the toplevel translation unit for FinchAssembly.

Attributes:

Name	Type	Description
funcs	tuple[Function, ...]	The functions defined in the module.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Module(AssemblyTree):
    """
    Represents a group of functions. This is the toplevel translation unit for
    FinchAssembly.

    Attributes:
        funcs: The functions defined in the module.
    """

    funcs: tuple[Function, ...]

    @property
    def children(self):
        """Returns the children of the node."""
        return [*self.funcs]

    @classmethod
    def from_children(cls, *funcs):
        return cls(funcs)

children property

Returns the children of the node.

Repack dataclass

Bases: AssemblyTree, AssemblyStatement

Registers updates from a symbolic object val with the original object. The original object may now be accessed and modified.

Attributes:

Name	Type	Description
slot		The symbolic object to read from.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Repack(AssemblyTree, AssemblyStatement):
    """
    Registers updates from a symbolic object `val` with the original
    object. The original object may now be accessed and modified.

    Attributes:
        slot: The symbolic object to read from.
    """

    val: Slot

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.val]

children property

Returns the children of the node.

Resize dataclass

Bases: AssemblyTree, AssemblyStatement

Represents resizing a buffer to a new size.

Attributes:

Name	Type	Description
buffer	AssemblyExpression	The buffer to resize.
new_size	AssemblyExpression	The new size for the buffer.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Resize(AssemblyTree, AssemblyStatement):
    """
    Represents resizing a buffer to a new size.

    Attributes:
        buffer: The buffer to resize.
        new_size: The new size for the buffer.
    """

    buffer: AssemblyExpression
    new_size: AssemblyExpression

    @property
    def children(self):
        return [self.buffer, self.new_size]

Return dataclass

Bases: AssemblyTree, AssemblyStatement

Represents a return statement that returns arg from the current function. Halts execution of the function body.

Attributes:

Name	Type	Description
arg	AssemblyExpression	The argument to return.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Return(AssemblyTree, AssemblyStatement):
    """
    Represents a return statement that returns `arg` from the current function.
    Halts execution of the function body.

    Attributes:
        arg: The argument to return.
    """

    arg: AssemblyExpression

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.arg]

children property

Returns the children of the node.

SetAttr dataclass

Bases: AssemblyTree, AssemblyStatement

Represents a setter for an attribute attr of an object obj. Attributes: obj: The object to set the attribute on. attr: The name of the attribute to set. value: The value to set the attribute to.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class SetAttr(AssemblyTree, AssemblyStatement):
    """
    Represents a setter for an attribute `attr` of an object `obj`.
    Attributes:
        obj: The object to set the attribute on.
        attr: The name of the attribute to set.
        value: The value to set the attribute to.
    """

    obj: AssemblyExpression
    attr: Literal
    value: AssemblyExpression

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.obj, self.attr, self.value]

children property

Returns the children of the node.

Slot dataclass

Bases: AssemblyExpression

Represents a register to a symbolic object. Using a register in an expression creates a copy of the object.

Attributes:

Name	Type	Description
name	str	The name of the symbolic object to register.
type	Any	The type of the symbolic object.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Slot(AssemblyExpression):
    """
    Represents a register to a symbolic object. Using a register in an
    expression creates a copy of the object.

    Attributes:
        name: The name of the symbolic object to register.
        type: The type of the symbolic object.
    """

    name: str
    type: Any

    @property
    def result_type(self):
        """Returns the type of the expression."""
        return self.type

    def __repr__(self) -> str:
        return literal_repr(type(self).__name__, asdict(self))

    @property
    def symbol(self) -> str:
        return self.name

result_type property

Returns the type of the expression.

Store dataclass

Bases: AssemblyTree, AssemblyStatement

Represents storing a value into a buffer at a given index.

Attributes:

Name	Type	Description
buffer	AssemblyExpression	The buffer to store into.
index	AssemblyExpression	The index to store at.
value	AssemblyExpression	The value to store.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Store(AssemblyTree, AssemblyStatement):
    """
    Represents storing a value into a buffer at a given index.

    Attributes:
        buffer: The buffer to store into.
        index: The index to store at.
        value: The value to store.
    """

    buffer: AssemblyExpression
    index: AssemblyExpression
    value: AssemblyExpression

    @property
    def children(self):
        return [self.buffer, self.index, self.value]

Unpack dataclass

Bases: AssemblyTree, AssemblyStatement

Attempts to convert rhs into a symbolic, which can be registerd with lhs. The original object must not be accessed or modified until the corresponding Repack node is reached.

Attributes:

Name	Type	Description
lhs	Slot	The symbolic object to write to.
rhs	AssemblyExpression	The original object to read from.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Unpack(AssemblyTree, AssemblyStatement):
    """
    Attempts to convert `rhs` into a symbolic, which can be registerd with
    `lhs`. The original object must not be accessed or modified until the
    corresponding `Repack` node is reached.

    Attributes:
        lhs: The symbolic object to write to.
        rhs: The original object to read from.
    """

    lhs: Slot
    rhs: AssemblyExpression

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.lhs, self.rhs]

children property

Returns the children of the node.

Variable dataclass

Bases: AssemblyExpression, NamedTerm

Represents a logical AST expression for a variable named name, which will hold a value of type type.

Attributes:

Name	Type	Description
name	str	The name of the variable.
type	FType	The type of the variable.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class Variable(AssemblyExpression, NamedTerm):
    """
    Represents a logical AST expression for a variable named `name`, which
    will hold a value of type `type`.

    Attributes:
        name: The name of the variable.
        type: The type of the variable.
    """

    name: str
    type: FType

    @property
    def result_type(self) -> FType:
        """Returns the type of the expression."""
        return self.type

    def __repr__(self) -> str:
        return literal_repr(type(self).__name__, {"name": self.name, "type": self.type})

    @property
    def symbol(self) -> str:
        return self.name

result_type property

Returns the type of the expression.

WhileLoop dataclass

Bases: AssemblyTree, AssemblyStatement

Represents a while loop that executes as long as the condition is true.

Attributes:

Name	Type	Description
condition	AssemblyExpression	The condition to evaluate for the loop to continue.
body	AssemblyStatement	The body of the loop to execute.

Source code in src/finch/finch_assembly/nodes.py

@dataclass(eq=True, frozen=True)
class WhileLoop(AssemblyTree, AssemblyStatement):
    """
    Represents a while loop that executes as long as the condition is true.

    Attributes:
        condition: The condition to evaluate for the loop to continue.
        body: The body of the loop to execute.
    """

    condition: AssemblyExpression
    body: AssemblyStatement

    @property
    def children(self):
        """Returns the children of the node."""
        return [self.condition, self.body]

children property

Returns the children of the node.