accelforge.frontend.mapping package

Submodules

accelforge.frontend.mapping.mapping module

A module containing the visualization and types needed to run mapspace exploratioon in AccelForge.

class accelforge.frontend.mapping.mapping.Compute

Bases: MappingNode

A node that represents a compute operation. These nodes are the leaves of the LoopTree.

compact_str()

Returns a compact string representation of this node.

Return type:

str

component: str

The name of the compute component performing the computation.

component_object: NoParse[Compute | None]

The Compute object performing the computation.

einsum: str

The Einsum being computed.

class accelforge.frontend.mapping.mapping.Loop

Bases: MappingNode

A bounded loop over a rank variable with a given shape and/or pattern.

Do not instantiate directly; inherited by Temporal and Spatial.

__init__(*args, **kwargs)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

property calculated_n_iterations: int

The number of iterations performed by this loop.

compact_str()

Returns a compact string representation of this Loop.

Return type:

str

initial_tile_shape: EvalsTo[Symbol | Expr | int | str | None]

The shape of the first tile shape. This attribute is optional. If not specified, all tiles have the same shape.

If specified, the initial tile shape may differ. For example, an initial tile shape of 3 and tile shape of 2 creates the following tiles in the iteration space: [0, 1, 2], [3, 4], [5, 6], …

Similarly to tile shape, this value should be an integer when writing a YAML input.

For those developing the mapper, this attribute can be a string. See tile_shape for details.

rank_variable: set[str] | str

The rank variable(s) iterated over in this loop. This may be a single rank variable, or a set of rank variables if the loop is shared between multiple Einsums.

property tile_pattern: TilePattern

tile_shape: EvalsTo[Symbol | Expr | int | str]

The (common) tile shape of the iteration. For example, if the iteration space is range(6) and the tile shape is 3, then we create and iterate over two tiles [0, 1, 2] and [3, 4, 5].

This attribute specifies the common tile shape because initial_tile_shape may be specified.

For users writing YAML, the value should be an integer.

For those developing the mapper, the literal string “symbol” is often used to tell the model to create a sympy symbol to use as the tile shape. Any other string may be specified to explicitly request a variable name (later converted to a sympy variable).

class accelforge.frontend.mapping.mapping.Mapping

Bases: Nested

A Mapping of a workload onto a hardware architecture.

property loops: list[Loop]

Returns all Loop nodes in the Mapping.

remove_reservations()

render()

Return type:

_SVGJupyterRender

render_pydot(with_reservations=True, with_tile_shape=True)

Renders the mapping as a Pydot graph. Returns an SVG string.

Return type:

Dot

split_loop_with_multiple_rank_variables()

split_tensor_holders_with_multiple_tensors()

class accelforge.frontend.mapping.mapping.MappingNode

Bases: EvalableModel

Represents a Node in the Mapping, which can be a loop, a storage node, a compute node, etc.

__init__(*args, **kwargs)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

compact_str()

Returns a compact string representation of this node.

Return type:

str

get_nodes_of_type(types)

Returns all sub-nodes, including this one, that match the given types.

Return type:

List[TypeVar(T, bound= MappingNode)]

accelforge.frontend.mapping.mapping.MappingNodeTypes

The types of MappingNodes possible.

Type:

TypeAlias MappingNodeTypes

alias of Temporal | Spatial | Storage | Pipeline | Sequential | Compute | Reservation | TensorHolder

class accelforge.frontend.mapping.mapping.MappingNodeWithChildren

Bases: MappingNode

A MappingNode that also has child nodes.

clear_nodes(*nodes)

Removes nodes that equal any of the given nodes.

Return type:

None

clear_nodes_of_type(types)

Clears all child nodes that match the given type(s).

Return type:

None

nodes: EvalableList[Annotated[Annotated[Split, Tag(tag=Split)] | Annotated[Compute, Tag(tag=Compute)] | Annotated[Storage, Tag(tag=Storage)] | Annotated[Temporal, Tag(tag=Temporal)] | Annotated[Spatial, Tag(tag=Spatial)] | Annotated[Sequential, Tag(tag=Sequential)] | Annotated[Pipeline, Tag(tag=Pipeline)] | Annotated[Nested, Tag(tag=Nested)] | Annotated[Reservation, Tag(tag=Reservation)] | Annotated[Mapping, Tag(tag=Mapping)] | Annotated[Toll, Tag(tag=Toll)], Discriminator(discriminator=_get_tag, custom_error_type=None, custom_error_message=None, custom_error_context=None)]]

The child nodes.

class accelforge.frontend.mapping.mapping.Nested

Bases: MappingNodeWithChildren

A MappingNodeWithChildren that represents a nested set of nodes. Each node is the parent of the next node.

compact_str()

Returns a compact string representation of this node.

Return type:

str

accelforge.frontend.mapping.mapping.NodeList

EvalableList that can contain and discriminate between MappingNodes of different types.

Type:

TypeAlias NodeList

alias of EvalableList[Annotated[Annotated[Split, Tag(tag=Split)] | Annotated[Compute, Tag(tag=Compute)] | Annotated[Storage, Tag(tag=Storage)] | Annotated[Temporal, Tag(tag=Temporal)] | Annotated[Spatial, Tag(tag=Spatial)] | Annotated[Sequential, Tag(tag=Sequential)] | Annotated[Pipeline, Tag(tag=Pipeline)] | Annotated[Nested, Tag(tag=Nested)] | Annotated[Reservation, Tag(tag=Reservation)] | Annotated[Mapping, Tag(tag=Mapping)] | Annotated[Toll, Tag(tag=Toll)], Discriminator(discriminator=_get_tag, custom_error_type=None, custom_error_message=None, custom_error_context=None)]]

class accelforge.frontend.mapping.mapping.Pipeline

Bases: Split

A Split where each branch operates at the same time in different spatially-organized hardware.

class accelforge.frontend.mapping.mapping.Reservation

Bases: MappingNode

A node that reserves a hardware resource for a specific task.

compact_str()

Returns a compact string representation of this node.

Return type:

str

persistent: bool

Whether this reservation is persistent. Persistent reservations can’t be tiled and must be kept in backing storage for the full duration of the workload’s execution.

property purpose: str

purposes: EvalableList[str]

The reasons for reserving the resource.

resource: str

The resource being reserved.

class accelforge.frontend.mapping.mapping.Sequential

Bases: Split

A Split where branches are processed one-after-another.

class accelforge.frontend.mapping.mapping.Spatial

Bases: Loop

A spatial Loop.

compact_str()

Returns a compact string representation of this Loop.

Return type:

str

component: str

The component name across which different spatial iterations occur.

component_object: NoParse[Leaf]

The component object across which different spatial iterations occur.

name: int | str

The dimension over which the spatial is occuring.

class accelforge.frontend.mapping.mapping.Split

Bases: MappingNodeWithChildren

A MappingNodeWithChildren that splits the tree into multiple branches, each applying to different Einsums.

class accelforge.frontend.mapping.mapping.Storage

Bases: TensorHolder

A Storage TensorHolder that can hold tensors for reuse.

class accelforge.frontend.mapping.mapping.T

TypeVar T: Restricts the allowable types to types of MappingNodes.

alias of TypeVar(‘T’, bound=MappingNode)

class accelforge.frontend.mapping.mapping.Temporal

Bases: Loop

A Temporal Loop.

compact_str()

Returns a compact string representation of this Loop.

Return type:

str

class accelforge.frontend.mapping.mapping.TensorHolder

Bases: MappingNode

A node that represents a hardware Component holding a set of tensors.

compact_str()

Returns a compact string representation of this node.

Return type:

str

component: str

The name of the component holding the tensors.

component_object: NoParse[Component]

The component object holding the tensors.

persistent: bool

Whether this tensor holder is persistent. Persistent tensors can’t be tiled and must be kept in backing storage for the full duration of the workload’s execution.

property tensor: str

If there is one tensor held in this tensor holder, returns its name. Otherwise, raises an error.

tensors: EvalableList[str]

The names of the tensors being held in this node.

class accelforge.frontend.mapping.mapping.TilePattern

Bases: object

TilePattern(tile_shape: accelforge.util._basetypes.EvalsTo[typing.Union[typing.Literal[‘symbol’], sympy.core.symbol.Symbol, int, str, NoneType, sympy.core.expr.Expr]] = ‘symbol’, initial_tile_shape: accelforge.util._basetypes.EvalsTo[typing.Union[typing.Literal[‘symbol’], sympy.core.symbol.Symbol, int, str, NoneType, sympy.core.expr.Expr]] = ‘symbol’, calculated_n_iterations: Union[Literal[‘symbol’], sympy.core.symbol.Symbol, int, str, NoneType, sympy.core.expr.Expr] = None)

__init__(tile_shape='symbol', initial_tile_shape='symbol', calculated_n_iterations=None)

as_str(with_initial_tile_shape=True, with_tile_shape=True)

calculated_n_iterations: Literal['symbol'] | Symbol | int | str | None | Expr = None

The number of iterations in the pattern. Do not set this! Used internally by the mapper.

initial_tile_shape: EvalsTo[Literal['symbol'] | Symbol | int | str | None | Expr] = 'symbol'

The initial tile shape. This is the shape of the tile at the first iteration. Subsequent iterations may be smaller if they overlap previous iterations.

tile_shape: EvalsTo[Literal['symbol'] | Symbol | int | str | None | Expr] = 'symbol'

The common tile shape of the pattern. This is the number of indices by which the tile moves each iteration.

update(**kwargs)

Update the TilePattern with the given keyword arguments.

Return type:

TilePattern

class accelforge.frontend.mapping.mapping.Toll

Bases: TensorHolder

A Toll TensorHolder that acts as a pass-through, where data is not reused but incurs accesses into this Toll.

Module contents

class accelforge.frontend.mapping.Compute

Bases: MappingNode

A node that represents a compute operation. These nodes are the leaves of the LoopTree.

compact_str()

Returns a compact string representation of this node.

Return type:

str

component: str

The name of the compute component performing the computation.

component_object: NoParse[Compute | None]

The Compute object performing the computation.

einsum: str

The Einsum being computed.

class accelforge.frontend.mapping.Loop

Bases: MappingNode

A bounded loop over a rank variable with a given shape and/or pattern.

Do not instantiate directly; inherited by Temporal and Spatial.

__init__(*args, **kwargs)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

property calculated_n_iterations: int

The number of iterations performed by this loop.

compact_str()

Returns a compact string representation of this Loop.

Return type:

str

initial_tile_shape: EvalsTo[Symbol | Expr | int | str | None]

The shape of the first tile shape. This attribute is optional. If not specified, all tiles have the same shape.

If specified, the initial tile shape may differ. For example, an initial tile shape of 3 and tile shape of 2 creates the following tiles in the iteration space: [0, 1, 2], [3, 4], [5, 6], …

Similarly to tile shape, this value should be an integer when writing a YAML input.

For those developing the mapper, this attribute can be a string. See tile_shape for details.

rank_variable: set[str] | str

The rank variable(s) iterated over in this loop. This may be a single rank variable, or a set of rank variables if the loop is shared between multiple Einsums.

property tile_pattern: TilePattern

tile_shape: EvalsTo[Symbol | Expr | int | str]

The (common) tile shape of the iteration. For example, if the iteration space is range(6) and the tile shape is 3, then we create and iterate over two tiles [0, 1, 2] and [3, 4, 5].

This attribute specifies the common tile shape because initial_tile_shape may be specified.

For users writing YAML, the value should be an integer.

For those developing the mapper, the literal string “symbol” is often used to tell the model to create a sympy symbol to use as the tile shape. Any other string may be specified to explicitly request a variable name (later converted to a sympy variable).

class accelforge.frontend.mapping.Mapping

Bases: Nested

A Mapping of a workload onto a hardware architecture.

property loops: list[Loop]

Returns all Loop nodes in the Mapping.

remove_reservations()

render()

Return type:

_SVGJupyterRender

render_pydot(with_reservations=True, with_tile_shape=True)

Renders the mapping as a Pydot graph. Returns an SVG string.

Return type:

Dot

split_loop_with_multiple_rank_variables()

split_tensor_holders_with_multiple_tensors()

class accelforge.frontend.mapping.MappingNode

Bases: EvalableModel

Represents a Node in the Mapping, which can be a loop, a storage node, a compute node, etc.

__init__(*args, **kwargs)

Create a new model by parsing and validating input data from keyword arguments.

Raises [ValidationError][pydantic_core.ValidationError] if the input data cannot be validated to form a valid model.

self is explicitly positional-only to allow self as a field name.

compact_str()

Returns a compact string representation of this node.

Return type:

str

get_nodes_of_type(types)

Returns all sub-nodes, including this one, that match the given types.

Return type:

List[TypeVar(T, bound= MappingNode)]

class accelforge.frontend.mapping.MappingNodeWithChildren

Bases: MappingNode

A MappingNode that also has child nodes.

clear_nodes(*nodes)

Removes nodes that equal any of the given nodes.

Return type:

None

clear_nodes_of_type(types)

Clears all child nodes that match the given type(s).

Return type:

None

nodes: EvalableList[Annotated[Annotated[Split, Tag(tag=Split)] | Annotated[Compute, Tag(tag=Compute)] | Annotated[Storage, Tag(tag=Storage)] | Annotated[Temporal, Tag(tag=Temporal)] | Annotated[Spatial, Tag(tag=Spatial)] | Annotated[Sequential, Tag(tag=Sequential)] | Annotated[Pipeline, Tag(tag=Pipeline)] | Annotated[Nested, Tag(tag=Nested)] | Annotated[Reservation, Tag(tag=Reservation)] | Annotated[Mapping, Tag(tag=Mapping)] | Annotated[Toll, Tag(tag=Toll)], Discriminator(discriminator=_get_tag, custom_error_type=None, custom_error_message=None, custom_error_context=None)]]

The child nodes.

class accelforge.frontend.mapping.Nested

Bases: MappingNodeWithChildren

A MappingNodeWithChildren that represents a nested set of nodes. Each node is the parent of the next node.

compact_str()

Returns a compact string representation of this node.

Return type:

str

class accelforge.frontend.mapping.Pipeline

Bases: Split

A Split where each branch operates at the same time in different spatially-organized hardware.

accelforge.frontend.mapping.RankVariable

alias of str

class accelforge.frontend.mapping.Reservation

Bases: MappingNode

A node that reserves a hardware resource for a specific task.

compact_str()

Returns a compact string representation of this node.

Return type:

str

persistent: bool

Whether this reservation is persistent. Persistent reservations can’t be tiled and must be kept in backing storage for the full duration of the workload’s execution.

property purpose: str

purposes: EvalableList[str]

The reasons for reserving the resource.

resource: str

The resource being reserved.

class accelforge.frontend.mapping.Sequential

Bases: Split

A Split where branches are processed one-after-another.

class accelforge.frontend.mapping.Spatial

Bases: Loop

A spatial Loop.

compact_str()

Returns a compact string representation of this Loop.

Return type:

str

component: str

The component name across which different spatial iterations occur.

component_object: NoParse[Leaf]

The component object across which different spatial iterations occur.

name: int | str

The dimension over which the spatial is occuring.

class accelforge.frontend.mapping.Split

Bases: MappingNodeWithChildren

A MappingNodeWithChildren that splits the tree into multiple branches, each applying to different Einsums.

class accelforge.frontend.mapping.Storage

Bases: TensorHolder

A Storage TensorHolder that can hold tensors for reuse.

class accelforge.frontend.mapping.Temporal

Bases: Loop

A Temporal Loop.

compact_str()

Returns a compact string representation of this Loop.

Return type:

str

class accelforge.frontend.mapping.TensorHolder

Bases: MappingNode

A node that represents a hardware Component holding a set of tensors.

compact_str()

Returns a compact string representation of this node.

Return type:

str

component: str

The name of the component holding the tensors.

component_object: NoParse[Component]

The component object holding the tensors.

persistent: bool

Whether this tensor holder is persistent. Persistent tensors can’t be tiled and must be kept in backing storage for the full duration of the workload’s execution.

property tensor: str

If there is one tensor held in this tensor holder, returns its name. Otherwise, raises an error.

tensors: EvalableList[str]

The names of the tensors being held in this node.

accelforge.frontend.mapping.TensorName

alias of str

class accelforge.frontend.mapping.TilePattern

Bases: object

TilePattern(tile_shape: accelforge.util._basetypes.EvalsTo[typing.Union[typing.Literal[‘symbol’], sympy.core.symbol.Symbol, int, str, NoneType, sympy.core.expr.Expr]] = ‘symbol’, initial_tile_shape: accelforge.util._basetypes.EvalsTo[typing.Union[typing.Literal[‘symbol’], sympy.core.symbol.Symbol, int, str, NoneType, sympy.core.expr.Expr]] = ‘symbol’, calculated_n_iterations: Union[Literal[‘symbol’], sympy.core.symbol.Symbol, int, str, NoneType, sympy.core.expr.Expr] = None)

__init__(tile_shape='symbol', initial_tile_shape='symbol', calculated_n_iterations=None)

as_str(with_initial_tile_shape=True, with_tile_shape=True)

calculated_n_iterations: Literal['symbol'] | Symbol | int | str | None | Expr = None

The number of iterations in the pattern. Do not set this! Used internally by the mapper.

initial_tile_shape: EvalsTo[Literal['symbol'] | Symbol | int | str | None | Expr] = 'symbol'

The initial tile shape. This is the shape of the tile at the first iteration. Subsequent iterations may be smaller if they overlap previous iterations.

tile_shape: EvalsTo[Literal['symbol'] | Symbol | int | str | None | Expr] = 'symbol'

The common tile shape of the pattern. This is the number of indices by which the tile moves each iteration.

update(**kwargs)

Update the TilePattern with the given keyword arguments.

Return type:

TilePattern

class accelforge.frontend.mapping.Toll

Bases: TensorHolder

A Toll TensorHolder that acts as a pass-through, where data is not reused but incurs accesses into this Toll.