accelforge.frontend.arch package#

Submodules#

accelforge.frontend.arch.arch module#

class accelforge.frontend.arch.arch.Arch[source]#

Bases: Hierarchical

Top-level architecture specification.

All attributes in the architecture can refrence variables in the spec-level variables field as well as symbols from the individual Einsum being processed.

extra_attributes_for_all_component_models: EvalExtras#: Extra attributes to pass to all component models. This can be used to pass global attributes, such as technology node or clock period, to every component model.

find_spatial(name, return_spatialable=False)[source]#

Find a spatial dimension by name. Raises an error if zero or more than one spatial dimension has the given name.

Parameters:

name (str) – The name of the spatial dimension to find.
return_spatialable (bool) – Whether to return the node that the spatial dimension is associated with.

Return type:

Spatial | tuple[Spatialable, Spatial]

Returns:

Spatial – The spatial dimension with the given name if return_spatialable is False.
tuple[Spatialable, Spatial] – The node and spatial dimension with the given name if return_spatialable is True.

Raises:

ValueError – If no spatial dimension with the given name exists, or if more than one spatial dimension with the given name exists.

property per_component_total_area: dict[str, float]#

Returns the total area used by each component in the architecture in m^2.

Returns:: A dictionary of component names to their total area in m^2.
Return type:: dict[str, float]

property per_component_total_leak_power: dict[str, float]#

Returns the total leak power of each component in the architecture in W.

Returns:: A dictionary of component names to their total leak power in W.
Return type:: dict[str, float]

property total_area: float#

Returns the total area of the architecture in m^2.

Returns:: The total area of the architecture in m^2.
Return type:: float

property total_leak_power: float#

Returns the total leak power of the architecture in W.

Returns:: The total leak power of the architecture in W.
Return type:: float

variables: EvalExtras#: Like the spec-level variables field, this field is evaluated first and its contents can be referenced elsewhere in the architecture. Unlike the spec-level variables field, this, like ther rest of the architecture, is evaluated per-Einsum and can reference Einsum-specific symbols.

accelforge.frontend.arch.components module#

class accelforge.frontend.arch.components.Action[source]#

Bases: EvalableModel

An action that may be performed by a component.

energy: EvalsTo[int | float | None]#: Dynamic energy of this action. Per-action energy is multiplied by the component’s energy_scale and the action’s energy_scale.

energy_scale: EvalsTo[int | float]#: The scale factor for dynamic energy of this action. Multiplies this action’s energy by this value.

extra_attributes_for_component_model: EvalExtras#: Extra attributes to pass to the component model. In addition to all attributes of this action, any extra attributes will be passed to the component model as arguments to the component model’s action. This can be used to define attributes that are known to the component model, but not accelforge, such as clock frequency.

latency: EvalsTo[int | float | None]#: Latency of this action. Per-action latency is multiplied by the component’s latency_scale and the action’s latency_scale.

latency_scale: EvalsTo[int | float]#: The scale factor for dynamic latency of this action. Multiplies this action’s latency by this value.

name: str#: The name of this action.

class accelforge.frontend.arch.components.Component[source]#

Bases: Spatialable

A component object in the architecture. This is overridden by different component types, such as Memory and Compute.

__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.

actions: EvalableList[Action]#: The actions that this Component can perform.

area: EvalsTo[int | float | None]#: The area of a single instance of this component in m^2. If set, area calculations will use this value.

area_scale: EvalsTo[int | float]#: The scale factor for the area of this comxponent. This is used to scale the area of this component. For example, if the area is 1 m^2 and the scale factor is 2, then the area is 2 m^2.

calculate_action_energy(component_models=None, in_place=False)[source]#

Calculates energy for each action of this component. If energy is set in the action or component (with action taking precedence), that value will be used. Otherwise, the energy will be calculated using hwcomponents. Populates, for each action, the <action>.energy and field. Extends the component_modeling_log field with log messages.

Uses the component_model attribute, or, if not set, the component_class attribute to find the model and populate the component_model attribute.

Note that these methods will be called by the Spec when calculating energy and area. If you call them yourself, note that string expressions may not be evaluated because they need the Spec’s global scope. If you are sure that all necessary values are present and not a result of an expression, you can call these directly. Otherwise, you can call the Spec.calculate_component_area_energy_latency_leak and then grab components from the returned Spec.

Parameters:

component_models (list[ComponentModel] | None) – The models to use for energy calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.

Returns:

A copy of the component with the calculated energy.

Return type:

Self

calculate_action_latency(component_models=None, in_place=False)[source]#

Calculates the latency for each action by this component. Populates the <action>.latency field. Extends the component_modeling_log field with log messages.

Parameters:

component_models (list[ComponentModel] | None) – The models to use for latency calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.

Returns:

A copy of the component with the calculated latency for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)[source]#

Calculates the area for this component. If area is set in the component, that value will be used. Otherwise, the area will be calculated using the hwcomponents library. Populates area field. Extends the component_modeling_log field with log messages.

Uses the component_model attribute, or, if not set, the component_class attribute to find the model and populate the component_model attribute.

Parameters:

component_models (list[ComponentModel] | None) – The models to use for area calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.

Returns:

A copy of the component with the calculated area.

Return type:

Self

calculate_area_energy_latency_leak(component_models=None, in_place=False, _use_cache=False)[source]#

Calculates the area, energy, latency, and leak power for this component. Populates the area, total_area, leak_power, total_leak_power, total_latency, and component_modeling_log fields of this component. Additionally, for each action, populates the <action>.area, <action>.energy, <action>.latency, and <action>.leak_power fields. Extends the component_modeling_log field with log messages.

Parameters:

component_models (list[ComponentModel] | None) – The models to use for energy calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.
_use_cache (bool) – If True, the component model will be cached and reused if the same component class, attributes, and actions are provided. Note that this may return copies of the same object across multiple calls.

Returns:

The component with the calculated energy, area, and leak power.

Return type:

Self

calculate_leak_power(component_models=None, in_place=False)[source]#

Calculates the leak power for this component. If leak power is set in the component, that value will be used. Otherwise, the leak power will be calculated using hwcomponents. Populates leak_power field. Extends the component_modeling_log field with log messages.

Uses the component_model attribute, or, if not set, the component_class attribute to find the model and populate the component_model attribute.

Parameters:

component_models (list[ComponentModel] | None) – The models to use for energy calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.

Returns:

A copy of the component with the calculated energy.

Return type:

Self

component_class: str | None#: The class of this Component. Used if an energy or area model needs to be called for this Component.

component_model: ComponentModel | None#: The model to use for this Component. If not set, the model will be found with hwcomponents.get_models(). If set, the component_class will be ignored.

component_modeling_log: list[str]#: A log of the energy and area calculations for this Component.

enabled: TryEvalTo[bool]#: Whether this component is enabled. If the expression resolves to False, then the component is disabled. This is evaluated per-pmapping-template, so it is a function of the tensors in the current Einsum. For example, you may say len(All) >= 3 and the component will only be enabled with Einsums with three or more tensors.

energy_scale: EvalsTo[int | float]#: The scale factor for dynamic energy of this component. For each action, multiplies this action’s energy. Multiplies the calculated energy of each action.

extra_attributes_for_component_model: _ExtraAttrs#: Extra attributes to pass to the component model. In addition to all attributes of this component, any extra attributes will be passed to the component model. This can be used to define attributes that are known to the component model, but not accelforge, such as the technology node.

get_component_class(trying_to_calculate=None)[source]#

Returns the class of this Component.

Parameters:: trying_toeval (str, optional) – What was trying to be calculated using this component. If provided, the error message will be more specific.
Raises:: EvaluationError – If the component_class is not set.
Return type:: str

latency_scale: EvalsTo[int | float]#: The scale factor for the latency of this component. This is used to scale the latency of this component. For example, if the latency is 1 ns and the scale factor is 2, then the latency is 2 ns. Multiplies the calculated latency of each action.

leak_power: EvalsTo[int | float | None]#: The leak power of a single instance of this component in W. If set, leak power calculations will use this value.

leak_power_scale: EvalsTo[int | float]#: The scale factor for the leak power of this component. This is used to scale the leak power of this component. For example, if the leak power is 1 W and the scale factor is 2, then the leak power is 2 W.

n_parallel_instances: EvalsTo[int | float]#: The number of parallel instances of this component. Increasing parallel instances will proportionally increase area and leakage, while reducing latency (unless latency calculation is overridden).

name: str#: The name of this Component.

populate_component_model(component_models=None, in_place=False, trying_to_calculate=None)[source]#

Populates the component_model attribute with the model for this component. Extends the component_modeling_log field with log messages. Uses the component_class attribute to find the model and populate the component_model attribute. Uses the hwcomponents.get_model() function to find the model.

Parameters:

component_models (list[ComponentModel] | None) – The models to use for energy calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.
trying_to_calculate (str) – What was trying to be calculated using this component. If provided, the error messages for missing component_class will be more specific.

Returns:

A copy of the component with the populated component_model attribute.

Return type:

TypeVar(T, bound= ArchNode)

total_area: EvalsTo[int | float | None]#: The total area of all instances of this component in m^2. Do not set this value. It is calculated when the architecture’s area is calculated.

total_latency: str | int | float#

An expression representing the total latency of this component in seconds. This is used to calculate the latency of a given Einsum. Special variables available are the following:

min: The minimum value of all arguments to the expression.
max: The maximum value of all arguments to the expression.
sum: The sum of all arguments to the expression.
X_actions: The number of times action X is performed. For example, read_actions is the number of times the read action is performed.
X_latency: The total latency of all actions of type X. For example, read_latency is the total latency of all read actions. It is equal to the per-read latency multiplied by the number of read actions.
action2latency: A dictionary of action names to their latency.

Additionally, all component attributes are availble as variables, and all other functions generally available in parsing. Note this expression is evaluated after other component attributes are evaluated.

For example, the following expression calculates latency assuming that each read or write action takes 1ns: 1e-9 * (read_actions + write_actions).

total_leak_power: EvalsTo[int | float | None]#: The total leak power of all instances of this component in W. Do not set this value. It is calculated when the architecture’s leak power is calculated. If instances are power gated, actual leak power may be less than this value.

class accelforge.frontend.arch.components.Compute[source]#

Bases: Component, Leaf

actions: EvalableList[Action]#: The actions that this Compute can perform.

class accelforge.frontend.arch.components.Container[source]#

Bases: Leaf, Spatialable

Creates a container, used to conveniently define spatial arrays, and doesn’t do anything else.

class accelforge.frontend.arch.components.Memory[source]#

Bases: TensorHolder

A Memory is a TensorHolder that stores data over time, allowing for temporal reuse.

actions: EvalableList[TensorHolderAction]#: The actions that this Memory can perform.

size: EvalsTo[int | float]#: The size of this Memory in bits.

class accelforge.frontend.arch.components.Network[source]#

Bases: Component, Leaf

Defines a network component.

The routing is currently defined using the mapping, the routing follows the order of the spatial nodes from top to bottom.

bits_per_action: EvalsTo[int | float | None]#: The number of bits accessed in each of this component’s actions. Overridden by bits_per_action in any action of this component. If set here, acts as a default value for the bits_per_action of all actions of this component.

bits_per_value_scale: EvalsTo[dict]#: A scaling factor for the bits per value of the tensors in this TensorHolder. If this is a dictionary, keys in the dictionary are evaluated as expressions and may reference one or more tensors.

class accelforge.frontend.arch.components.TensorHolder[source]#

Bases: Component, Leaf

A TensorHolder is a component that holds tensors. These are usually Memories, but can also be Tolls.

__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.

actions: EvalableList[TensorHolderAction]#: The actions that this TensorHolder can perform.

bits_per_action: EvalsTo[int | float | None]#: The number of bits accessed in each of this component’s actions. Overridden by bits_per_action in any action of this component. If set here, acts as a default value for the bits_per_action of all actions of this component.

bits_per_value_scale: EvalsTo[dict]#: A scaling factor for the bits per value of the tensors in this TensorHolder. If this is a dictionary, keys in the dictionary are evaluated as expressions and may reference one or more tensors.

tensors: Tensors#: Fields that control which tensor(s) are kept in this TensorHolder and in what order their nodes may appear in the mapping.

class accelforge.frontend.arch.components.TensorHolderAction[source]#

Bases: Action

bits_per_action: EvalsTo[int | float]#: The number of bits accessed in this action. For example, setting bits_per_action to 16 means that each call to this action yields 16 bits.

class accelforge.frontend.arch.components.Tensors[source]#

Bases: EvalableModel

Fields that control which tensor(s) are kept in a TensorHolder and in what order their nodes may appear in the mapping.

back: TryEvalTo[InvertibleSet[str]]#: A set expression describing which tensors must be backed by this accelforge.frontend.arch.TensorHolder. If this is not defined, then no tensors must be backed.

force_memory_hierarchy_order: bool#

If set to true, storage nodes for lower-level memories must be placed below storage nodes for higher-level memories. For example, all MainMemory storage nodes must go above all LocalBuffer storage nodes.

This constraint always applies to same-tensor storage nodes (e.g., MainMemory reusing Output must go above LocalBuffer reusing Output); turning it off will permit things like MainMemory reusing Output going above LocalBuffer reusing Input.

This is identical to the force_memory_hierarchy_order field in the FFM class, but only applies to this tensor holder.

keep: TryEvalTo[InvertibleSet[str]]#: A set expression describing which tensors must be kept in this accelforge.frontend.arch.TensorHolder. If this is not defined, then all tensors must be kept. Any tensors that are in back will also be added to keep.

may_keep: TryEvalTo[InvertibleSet[str]]#: A set expression describing which tensors may optionally be kept in this accelforge.frontend.arch.TensorHolder. The mapper will explore both keeping and not keeping each of these tensors. If this is not defined, then all tensors may be kept.

no_refetch_from_above: TryEvalTo[InvertibleSet[str]]#: The tensors that are not allowed to be refetched from above. This is given as a set of TensorName objects or a set expression that resolves to them. These tensors must be fetched at most one time from above memories, and may not be refetched across any temporal or spatial loop iterations. Tensors may be fetched in pieces (if they do not cause re-fetches of any piece).

no_resend_to_below: TryEvalTo[InvertibleSet[str]]#: The tensors that are not allowed to be refetched to below. This is given as a set of TensorName objects or a set expression that resolves to them. These tensors must be fetched at most one time from this memory to below memories, and may not be refetched across any temporal or spatial loop iterations. Tensors may be fetched in pieces (if they do not cause re-fetches of any piece).

tensor_order_options: EvalableList[EvalableList[TryEvalTo[InvertibleSet[str]]]]#

Options for the order of tensor storage nodes in the mapping. This is given as a list-of-lists-of-sets. Each list-of-sets is a valid order of tensor storage nodes. Order is given from highest in the mapping to lowest.

For example, an option could be [input | output, weight], which means that there is no relative ordering required between input and output, but weight must be below both.

tile_shape: EvalableList[Comparison]#: The tile shape for each rank variable. This is given as a list of Comparison objects, where each comparison must evaluate to True for a valid mapping.

class accelforge.frontend.arch.components.Toll[source]#

Bases: TensorHolder

A Toll is a TensorHolder that does not store data over time, and therefore does not allow for temporal reuse. Use this as a toll that charges reads and writes every time a piece of data moves through it.

Every write to a Toll is immediately written to the next Memory (which may be above or below depending on where the write came from), and same for reads.

The access counts of a Toll are only included in the “read” action. Each traversal through the Toll is counted as a read. Writes are always zero.

actions: EvalableList[TensorHolderAction]#: The actions that this Toll can perform.

direction: Literal['up', 'down', 'up_and_down']#: The direction in which data flows through this Toll. If “up”, then data flows from below TensorHolder, through this Toll (plus paying associated costs), and then to the next TensorHolder above it. Other data movements are assumed to avoid this Toll.

accelforge.frontend.arch.constraints module#

class accelforge.frontend.arch.constraints.Comparison[source]#

Bases: EvalableModel

A comparison between a rank variable’s bound and a value. A comparison is performed for each rank variable.

The LHS of each comparison is the loop bound of a loop that affects this rank variable. The RHS is the given value.

For example, if the expression resolves to [a, b], the operator is “<=”, and the value is 10, and we have loops “for a0 in [0..A0)” and “for b0 in [0..B0)”, then a mapping is only valid if A0 <= 10 and B0 <= 10.

expression: TryEvalTo[InvertibleSet[str]]#: The expression to compare. This expression should resolve to a set of rank variables. A comparison is performed for each rank variable independently, and the result passes if and only if all comparisons pass. The LHS of each comparison is the loop bound of a loop that affects this rank variable. The RHS is the given value.

operator: str#: The operator to use for the comparison. Supported operators are: - == (equal to) - <= (less than or equal to) - >= (greater than or equal to) - < (less than) - > (greater than) - product== (product of all loop bounds is equal to) - product<= (product of all loop bounds is less than or equal to) - product>= (product of all loop bounds is greater than or equal to) - product< (product of all loop bounds is less than) - product> (product of all loop bounds is greater than)

value: EvalsTo[int]#: The value to compare against.

accelforge.frontend.arch.spatialable module#

class accelforge.frontend.arch.spatialable.Spatial[source]#

Bases: EvalableModel

A one-dimensional spatial fanout in the architecture.

fanout: EvalsTo[int]#: The size of this fanout.

loop_bounds: EvalableList[Comparison]#

Bounds for loops over this dimension. This is a list of Comparison objects, all of which must be satisfied by the loops to which this constraint applies.

Note: Loops may be removed if they are constrained to only one iteration.

may_reuse: TryEvalTo[InvertibleSet[str]]#: The tensors that can be reused spatially across instances of this fanout. This expression will be evaluated for each mapping template.

min_usage: int | float | str#: The minimum usage of spatial instances, as a value from 0 to 1. A mapping is invalid if less than this porportion of this dimension’s fanout is utilized. Mappers that support it (e.g., FFM) may, if no mappings satisfy this constraint, return the highest-usage mappings.

name: str#: The name of the dimension over which this spatial fanout is occurring (e.g., X or Y).

power_gateable: EvalsTo[bool]#: Whether this spatial fanout has power gating. If True, then unused spatial instances will be power gated if not used by a particular Einsum.

reuse: TryEvalTo[InvertibleSet[str]]#

A set of tensors or a set expression representing tensors that must be reused across spatial iterations. Spatial loops may only be placed that reuse ALL tensors given here.

Note: Loops may be removed if they do not reuse a tensor given here and they do not appear in another loop bound constraint.

usage_scale: EvalsTo[int | float | str]#: This factor scales the usage in this dimension. For example, if usage_scale is 2 and 10/20 spatial instances are used, then the usage will be scaled to 20/20.

class accelforge.frontend.arch.spatialable.Spatialable[source]#

Bases: EvalableModel

Something that can be duplicated to create an array of.

get_fanout()[source]#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)[source]#

Return type:: int

spatial: EvalableList[Spatial]#

The spatial fanouts of this Leaf.

Spatial fanouts describe the spatial organization of components in the architecture. A spatial fanout of size N for this node means that there are N instances of this node. Multiple spatial fanouts lead to a multi-dimensional fanout. Spatial constraints apply to the data exchange across these instances. Spatial fanouts specified at this level also apply to lower-level Leaf nodes in the architecture.

accelforge.frontend.arch.structure module#

class accelforge.frontend.arch.structure.ArchNode[source]#

Bases: EvalableModel

A node in the architecture.

find(name, default=_FIND_SENTINEL)[source]#

Finds a node with the given name.

Parameters:

name (str) – The name of the node to find.
default (TypeVar(D)) – The value to return if a node with the given name is not found. Otherwise, raises a ValueError.

Raises:

ValueError – If a node with the given name is not found.

Return type:

Union[ArchNode, TypeVar(D)]

Returns:

ArchNode – The node with the given name.
default – The value to return if the Leaf node with the given name is not found.

find_first_of_type_above(node_type, name, default=_FIND_SENTINEL)[source]#

Returns the first node with type node_type above name.

If name does not exist, raises an error.

If no node of node_type is found, either default is returned (if provided) or raises an error.

Return type:: Union[TypeVar(T), TypeVar(D)]

is_above(node_a, node_b)[source]#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

iterate_hierarchically(_parents=None)[source]#: Iterates over all nodes with names while also yielding the list of all nodes that are hierarchical parents over the current node.

class accelforge.frontend.arch.structure.ArchNodes[source]#

Bases: EvalableList

A list of ArchNodes.

class accelforge.frontend.arch.structure.Array[source]#

Bases: Branch, Spatialable

name: str#

render()[source]#

Renders the architecture as a Pydot graph.

Return type:: str

class accelforge.frontend.arch.structure.Branch[source]#

Bases: ArchNode

__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.

get_nodes_of_type(types)[source]#

Return type:: Iterator[TypeVar(T)]

nodes: ArchNodes[Annotated[Annotated[Compute, Tag(tag=Compute)] | Annotated[Memory, Tag(tag=Memory)] | Annotated[Toll, Tag(tag=Toll)] | Annotated[Container, Tag(tag=Container)] | Annotated[Network, Tag(tag=Network)] | Annotated[Hierarchical, Tag(tag=Hierarchical)] | Annotated[Array, Tag(tag=Array)] | Annotated[Fork, Tag(tag=Fork)], Discriminator(discriminator=_get_tag, custom_error_type=None, custom_error_message=None, custom_error_context=None)]]#

class accelforge.frontend.arch.structure.Fork[source]#

Bases: Hierarchical

A Fork is a Hierarchical that branches off from the main path. The nodes inside the Fork are a separate branch, while the main path continues to the next sibling after the Fork.

forked_power_gateable: bool#: Whether the child branch (the nodes inside this Fork) can be power gated when the main branch is active. If True, these nodes will not leak when the main branch is being used.

non_forked_power_gateable: bool#: Whether the main branch (the siblings after this Fork in the parent) can be power gated when the child branch is active. If True, those nodes will not leak when this Fork’s child branch is being used.

class accelforge.frontend.arch.structure.Hierarchical[source]#

Bases: Branch

render()[source]#

Renders the architecture as a Pydot graph.

Return type:: str

class accelforge.frontend.arch.structure.Leaf[source]#

Bases: ArchNode

A leaf node in the architecture. This is an abstract class that represents any node that is not a Branch.

__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.

name: str#: The name of this Leaf.

Module contents#

class accelforge.frontend.arch.Action[source]#

Bases: EvalableModel

An action that may be performed by a component.

energy: EvalsTo[int | float | None]#: Dynamic energy of this action. Per-action energy is multiplied by the component’s energy_scale and the action’s energy_scale.

energy_scale: EvalsTo[int | float]#: The scale factor for dynamic energy of this action. Multiplies this action’s energy by this value.

extra_attributes_for_component_model: EvalExtras#: Extra attributes to pass to the component model. In addition to all attributes of this action, any extra attributes will be passed to the component model as arguments to the component model’s action. This can be used to define attributes that are known to the component model, but not accelforge, such as clock frequency.

latency: EvalsTo[int | float | None]#: Latency of this action. Per-action latency is multiplied by the component’s latency_scale and the action’s latency_scale.

latency_scale: EvalsTo[int | float]#: The scale factor for dynamic latency of this action. Multiplies this action’s latency by this value.

name: str#: The name of this action.

class accelforge.frontend.arch.Arch[source]#

Bases: Hierarchical

Top-level architecture specification.

All attributes in the architecture can refrence variables in the spec-level variables field as well as symbols from the individual Einsum being processed.

extra_attributes_for_all_component_models: EvalExtras#: Extra attributes to pass to all component models. This can be used to pass global attributes, such as technology node or clock period, to every component model.

find_spatial(name, return_spatialable=False)[source]#

Find a spatial dimension by name. Raises an error if zero or more than one spatial dimension has the given name.

Parameters:

name (str) – The name of the spatial dimension to find.
return_spatialable (bool) – Whether to return the node that the spatial dimension is associated with.

Return type:

Spatial | tuple[Spatialable, Spatial]

Returns:

Spatial – The spatial dimension with the given name if return_spatialable is False.
tuple[Spatialable, Spatial] – The node and spatial dimension with the given name if return_spatialable is True.

Raises:

ValueError – If no spatial dimension with the given name exists, or if more than one spatial dimension with the given name exists.

property per_component_total_area: dict[str, float]#

Returns the total area used by each component in the architecture in m^2.

Returns:: A dictionary of component names to their total area in m^2.
Return type:: dict[str, float]

property per_component_total_leak_power: dict[str, float]#

Returns the total leak power of each component in the architecture in W.

Returns:: A dictionary of component names to their total leak power in W.
Return type:: dict[str, float]

property total_area: float#

Returns the total area of the architecture in m^2.

Returns:: The total area of the architecture in m^2.
Return type:: float

property total_leak_power: float#

Returns the total leak power of the architecture in W.

Returns:: The total leak power of the architecture in W.
Return type:: float

variables: EvalExtras#: Like the spec-level variables field, this field is evaluated first and its contents can be referenced elsewhere in the architecture. Unlike the spec-level variables field, this, like ther rest of the architecture, is evaluated per-Einsum and can reference Einsum-specific symbols.

class accelforge.frontend.arch.ArchNode[source]#

Bases: EvalableModel

A node in the architecture.

find(name, default=_FIND_SENTINEL)[source]#

Finds a node with the given name.

Parameters:

name (str) – The name of the node to find.
default (TypeVar(D)) – The value to return if a node with the given name is not found. Otherwise, raises a ValueError.

Raises:

ValueError – If a node with the given name is not found.

Return type:

Union[ArchNode, TypeVar(D)]

Returns:

ArchNode – The node with the given name.
default – The value to return if the Leaf node with the given name is not found.

find_first_of_type_above(node_type, name, default=_FIND_SENTINEL)[source]#

Returns the first node with type node_type above name.

If name does not exist, raises an error.

If no node of node_type is found, either default is returned (if provided) or raises an error.

Return type:: Union[TypeVar(T), TypeVar(D)]

is_above(node_a, node_b)[source]#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

iterate_hierarchically(_parents=None)[source]#: Iterates over all nodes with names while also yielding the list of all nodes that are hierarchical parents over the current node.

class accelforge.frontend.arch.ArchNodes[source]#

Bases: EvalableList

A list of ArchNodes.

class accelforge.frontend.arch.Array[source]#

Bases: Branch, Spatialable

name: str#

render()[source]#

Renders the architecture as a Pydot graph.

Return type:: str

class accelforge.frontend.arch.Branch[source]#

Bases: ArchNode

__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.

get_nodes_of_type(types)[source]#

Return type:: Iterator[TypeVar(T)]

nodes: ArchNodes[Annotated[Annotated[Compute, Tag(tag=Compute)] | Annotated[Memory, Tag(tag=Memory)] | Annotated[Toll, Tag(tag=Toll)] | Annotated[Container, Tag(tag=Container)] | Annotated[Network, Tag(tag=Network)] | Annotated[Hierarchical, Tag(tag=Hierarchical)] | Annotated[Array, Tag(tag=Array)] | Annotated[Fork, Tag(tag=Fork)], Discriminator(discriminator=_get_tag, custom_error_type=None, custom_error_message=None, custom_error_context=None)]]#

class accelforge.frontend.arch.Comparison[source]#

Bases: EvalableModel

A comparison between a rank variable’s bound and a value. A comparison is performed for each rank variable.

The LHS of each comparison is the loop bound of a loop that affects this rank variable. The RHS is the given value.

expression: TryEvalTo[InvertibleSet[str]]#: The expression to compare. This expression should resolve to a set of rank variables. A comparison is performed for each rank variable independently, and the result passes if and only if all comparisons pass. The LHS of each comparison is the loop bound of a loop that affects this rank variable. The RHS is the given value.

operator: str#: The operator to use for the comparison. Supported operators are: - == (equal to) - <= (less than or equal to) - >= (greater than or equal to) - < (less than) - > (greater than) - product== (product of all loop bounds is equal to) - product<= (product of all loop bounds is less than or equal to) - product>= (product of all loop bounds is greater than or equal to) - product< (product of all loop bounds is less than) - product> (product of all loop bounds is greater than)

value: EvalsTo[int]#: The value to compare against.

class accelforge.frontend.arch.Component[source]#

Bases: Spatialable

A component object in the architecture. This is overridden by different component types, such as Memory and Compute.

__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.

actions: EvalableList[Action]#: The actions that this Component can perform.

area: EvalsTo[int | float | None]#: The area of a single instance of this component in m^2. If set, area calculations will use this value.

area_scale: EvalsTo[int | float]#: The scale factor for the area of this comxponent. This is used to scale the area of this component. For example, if the area is 1 m^2 and the scale factor is 2, then the area is 2 m^2.

calculate_action_energy(component_models=None, in_place=False)[source]#

Uses the component_model attribute, or, if not set, the component_class attribute to find the model and populate the component_model attribute.

Parameters:

component_models (list[ComponentModel] | None) – The models to use for energy calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.

Returns:

A copy of the component with the calculated energy.

Return type:

Self

calculate_action_latency(component_models=None, in_place=False)[source]#

Calculates the latency for each action by this component. Populates the <action>.latency field. Extends the component_modeling_log field with log messages.

Parameters:

component_models (list[ComponentModel] | None) – The models to use for latency calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.

Returns:

A copy of the component with the calculated latency for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)[source]#

Uses the component_model attribute, or, if not set, the component_class attribute to find the model and populate the component_model attribute.

Parameters:

component_models (list[ComponentModel] | None) – The models to use for area calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.

Returns:

A copy of the component with the calculated area.

Return type:

Self

calculate_area_energy_latency_leak(component_models=None, in_place=False, _use_cache=False)[source]#

Parameters:

component_models (list[ComponentModel] | None) – The models to use for energy calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.
_use_cache (bool) – If True, the component model will be cached and reused if the same component class, attributes, and actions are provided. Note that this may return copies of the same object across multiple calls.

Returns:

The component with the calculated energy, area, and leak power.

Return type:

Self

calculate_leak_power(component_models=None, in_place=False)[source]#

Uses the component_model attribute, or, if not set, the component_class attribute to find the model and populate the component_model attribute.

Parameters:

component_models (list[ComponentModel] | None) – The models to use for energy calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.

Returns:

A copy of the component with the calculated energy.

Return type:

Self

component_class: str | None#: The class of this Component. Used if an energy or area model needs to be called for this Component.

component_model: ComponentModel | None#: The model to use for this Component. If not set, the model will be found with hwcomponents.get_models(). If set, the component_class will be ignored.

component_modeling_log: list[str]#: A log of the energy and area calculations for this Component.

enabled: TryEvalTo[bool]#: Whether this component is enabled. If the expression resolves to False, then the component is disabled. This is evaluated per-pmapping-template, so it is a function of the tensors in the current Einsum. For example, you may say len(All) >= 3 and the component will only be enabled with Einsums with three or more tensors.

energy_scale: EvalsTo[int | float]#: The scale factor for dynamic energy of this component. For each action, multiplies this action’s energy. Multiplies the calculated energy of each action.

extra_attributes_for_component_model: _ExtraAttrs#: Extra attributes to pass to the component model. In addition to all attributes of this component, any extra attributes will be passed to the component model. This can be used to define attributes that are known to the component model, but not accelforge, such as the technology node.

get_component_class(trying_to_calculate=None)[source]#

Returns the class of this Component.

Parameters:: trying_toeval (str, optional) – What was trying to be calculated using this component. If provided, the error message will be more specific.
Raises:: EvaluationError – If the component_class is not set.
Return type:: str

latency_scale: EvalsTo[int | float]#: The scale factor for the latency of this component. This is used to scale the latency of this component. For example, if the latency is 1 ns and the scale factor is 2, then the latency is 2 ns. Multiplies the calculated latency of each action.

leak_power: EvalsTo[int | float | None]#: The leak power of a single instance of this component in W. If set, leak power calculations will use this value.

leak_power_scale: EvalsTo[int | float]#: The scale factor for the leak power of this component. This is used to scale the leak power of this component. For example, if the leak power is 1 W and the scale factor is 2, then the leak power is 2 W.

n_parallel_instances: EvalsTo[int | float]#: The number of parallel instances of this component. Increasing parallel instances will proportionally increase area and leakage, while reducing latency (unless latency calculation is overridden).

name: str#: The name of this Component.

populate_component_model(component_models=None, in_place=False, trying_to_calculate=None)[source]#

Parameters:

component_models (list[ComponentModel] | None) – The models to use for energy calculation. If not provided, the models will be found with hwcomponents.get_models().
in_place (bool) – If True, the component will be modified in place. Otherwise, a copy will be returned.
trying_to_calculate (str) – What was trying to be calculated using this component. If provided, the error messages for missing component_class will be more specific.

Returns:

A copy of the component with the populated component_model attribute.

Return type:

TypeVar(T, bound= ArchNode)

total_area: EvalsTo[int | float | None]#: The total area of all instances of this component in m^2. Do not set this value. It is calculated when the architecture’s area is calculated.

total_latency: str | int | float#

An expression representing the total latency of this component in seconds. This is used to calculate the latency of a given Einsum. Special variables available are the following:

min: The minimum value of all arguments to the expression.
max: The maximum value of all arguments to the expression.
sum: The sum of all arguments to the expression.
X_actions: The number of times action X is performed. For example, read_actions is the number of times the read action is performed.
X_latency: The total latency of all actions of type X. For example, read_latency is the total latency of all read actions. It is equal to the per-read latency multiplied by the number of read actions.
action2latency: A dictionary of action names to their latency.

For example, the following expression calculates latency assuming that each read or write action takes 1ns: 1e-9 * (read_actions + write_actions).

total_leak_power: EvalsTo[int | float | None]#: The total leak power of all instances of this component in W. Do not set this value. It is calculated when the architecture’s leak power is calculated. If instances are power gated, actual leak power may be less than this value.

class accelforge.frontend.arch.Compute[source]#

Bases: Component, Leaf

actions: EvalableList[Action]#: The actions that this Compute can perform.

class accelforge.frontend.arch.Container[source]#

Bases: Leaf, Spatialable

Creates a container, used to conveniently define spatial arrays, and doesn’t do anything else.

class accelforge.frontend.arch.Fork[source]#

Bases: Hierarchical

A Fork is a Hierarchical that branches off from the main path. The nodes inside the Fork are a separate branch, while the main path continues to the next sibling after the Fork.

forked_power_gateable: bool#: Whether the child branch (the nodes inside this Fork) can be power gated when the main branch is active. If True, these nodes will not leak when the main branch is being used.

non_forked_power_gateable: bool#: Whether the main branch (the siblings after this Fork in the parent) can be power gated when the child branch is active. If True, those nodes will not leak when this Fork’s child branch is being used.

class accelforge.frontend.arch.Hierarchical[source]#

Bases: Branch

render()[source]#

Renders the architecture as a Pydot graph.

Return type:: str

class accelforge.frontend.arch.Leaf[source]#

Bases: ArchNode

A leaf node in the architecture. This is an abstract class that represents any node that is not a Branch.

__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.

name: str#: The name of this Leaf.

class accelforge.frontend.arch.Memory[source]#

Bases: TensorHolder

A Memory is a TensorHolder that stores data over time, allowing for temporal reuse.

actions: EvalableList[TensorHolderAction]#: The actions that this Memory can perform.

size: EvalsTo[int | float]#: The size of this Memory in bits.

class accelforge.frontend.arch.Spatial[source]#

Bases: EvalableModel

A one-dimensional spatial fanout in the architecture.

fanout: EvalsTo[int]#: The size of this fanout.

loop_bounds: EvalableList[Comparison]#

Bounds for loops over this dimension. This is a list of Comparison objects, all of which must be satisfied by the loops to which this constraint applies.

Note: Loops may be removed if they are constrained to only one iteration.

may_reuse: TryEvalTo[InvertibleSet[str]]#: The tensors that can be reused spatially across instances of this fanout. This expression will be evaluated for each mapping template.

min_usage: int | float | str#: The minimum usage of spatial instances, as a value from 0 to 1. A mapping is invalid if less than this porportion of this dimension’s fanout is utilized. Mappers that support it (e.g., FFM) may, if no mappings satisfy this constraint, return the highest-usage mappings.

name: str#: The name of the dimension over which this spatial fanout is occurring (e.g., X or Y).

power_gateable: EvalsTo[bool]#: Whether this spatial fanout has power gating. If True, then unused spatial instances will be power gated if not used by a particular Einsum.

reuse: TryEvalTo[InvertibleSet[str]]#

A set of tensors or a set expression representing tensors that must be reused across spatial iterations. Spatial loops may only be placed that reuse ALL tensors given here.

Note: Loops may be removed if they do not reuse a tensor given here and they do not appear in another loop bound constraint.

usage_scale: EvalsTo[int | float | str]#: This factor scales the usage in this dimension. For example, if usage_scale is 2 and 10/20 spatial instances are used, then the usage will be scaled to 20/20.

class accelforge.frontend.arch.TensorHolder[source]#

Bases: Component, Leaf

A TensorHolder is a component that holds tensors. These are usually Memories, but can also be Tolls.

__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.

actions: EvalableList[TensorHolderAction]#: The actions that this TensorHolder can perform.

bits_per_action: EvalsTo[int | float | None]#: The number of bits accessed in each of this component’s actions. Overridden by bits_per_action in any action of this component. If set here, acts as a default value for the bits_per_action of all actions of this component.

bits_per_value_scale: EvalsTo[dict]#: A scaling factor for the bits per value of the tensors in this TensorHolder. If this is a dictionary, keys in the dictionary are evaluated as expressions and may reference one or more tensors.

tensors: Tensors#: Fields that control which tensor(s) are kept in this TensorHolder and in what order their nodes may appear in the mapping.

class accelforge.frontend.arch.TensorHolderAction[source]#

Bases: Action

bits_per_action: EvalsTo[int | float]#: The number of bits accessed in this action. For example, setting bits_per_action to 16 means that each call to this action yields 16 bits.

class accelforge.frontend.arch.Tensors[source]#

Bases: EvalableModel

Fields that control which tensor(s) are kept in a TensorHolder and in what order their nodes may appear in the mapping.

back: TryEvalTo[InvertibleSet[str]]#: A set expression describing which tensors must be backed by this accelforge.frontend.arch.TensorHolder. If this is not defined, then no tensors must be backed.

force_memory_hierarchy_order: bool#

This is identical to the force_memory_hierarchy_order field in the FFM class, but only applies to this tensor holder.

keep: TryEvalTo[InvertibleSet[str]]#: A set expression describing which tensors must be kept in this accelforge.frontend.arch.TensorHolder. If this is not defined, then all tensors must be kept. Any tensors that are in back will also be added to keep.

may_keep: TryEvalTo[InvertibleSet[str]]#: A set expression describing which tensors may optionally be kept in this accelforge.frontend.arch.TensorHolder. The mapper will explore both keeping and not keeping each of these tensors. If this is not defined, then all tensors may be kept.

no_refetch_from_above: TryEvalTo[InvertibleSet[str]]#: The tensors that are not allowed to be refetched from above. This is given as a set of TensorName objects or a set expression that resolves to them. These tensors must be fetched at most one time from above memories, and may not be refetched across any temporal or spatial loop iterations. Tensors may be fetched in pieces (if they do not cause re-fetches of any piece).

no_resend_to_below: TryEvalTo[InvertibleSet[str]]#: The tensors that are not allowed to be refetched to below. This is given as a set of TensorName objects or a set expression that resolves to them. These tensors must be fetched at most one time from this memory to below memories, and may not be refetched across any temporal or spatial loop iterations. Tensors may be fetched in pieces (if they do not cause re-fetches of any piece).

tensor_order_options: EvalableList[EvalableList[TryEvalTo[InvertibleSet[str]]]]#

For example, an option could be [input | output, weight], which means that there is no relative ordering required between input and output, but weight must be below both.

tile_shape: EvalableList[Comparison]#: The tile shape for each rank variable. This is given as a list of Comparison objects, where each comparison must evaluate to True for a valid mapping.

class accelforge.frontend.arch.Toll[source]#

Bases: TensorHolder

Every write to a Toll is immediately written to the next Memory (which may be above or below depending on where the write came from), and same for reads.

The access counts of a Toll are only included in the “read” action. Each traversal through the Toll is counted as a read. Writes are always zero.

actions: EvalableList[TensorHolderAction]#: The actions that this Toll can perform.

direction: Literal['up', 'down', 'up_and_down']#: The direction in which data flows through this Toll. If “up”, then data flows from below TensorHolder, through this Toll (plus paying associated costs), and then to the next TensorHolder above it. Other data movements are assumed to avoid this Toll.

accelforge.frontend.arch package#

Submodules#

accelforge.frontend.arch.arch module#

accelforge.frontend.arch.components module#

accelforge.frontend.arch.constraints module#

accelforge.frontend.arch.spatialable module#

accelforge.frontend.arch.structure module#

Module contents#

This Page