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 = 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(name, default=_FIND_SENTINEL)#

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)#

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)]

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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_nodes_of_type(types)#

Return type:: Iterator[TypeVar(T)]

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

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]

render()#

Renders the architecture as a Pydot graph.

Return type:: str

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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 = 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] = 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] = 1#: The scale factor for dynamic energy of this action. Multiplies this action’s energy by this value.

extra_attributes_for_component_model: EvalExtras = 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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

latency: EvalsTo[int | float | None] = None#: Deprecated; use throughput instead. Setting this emits a deprecation warning and auto-converts to throughput = 1 / latency.

latency_scale: EvalsTo[int | float] = 1#: Deprecated; use throughput_scale instead. Setting this to a non-default value emits a deprecation warning and auto-converts to throughput_scale = 1 / latency_scale.

property n_calls: int | float#: The number of times this action is performed in the current Einsum. When accessed through the total_latency expression, returns the number of calls of this action in the current Einsum.

name: str#: The name of this action.

throughput: EvalsTo[int | float | None] = None#: Throughput of this action in actions/second. Per-action throughput is multiplied by the component’s throughput_scale and the action’s throughput_scale.

throughput_scale: EvalsTo[int | float] = 1#: The scale factor for throughput of this action. Multiplies this action’s throughput by this value.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

actions_scale: EvalsTo[int | float] = 1#: Scales the number of actions performed by this component. Multiplies the action count for each action of this component, which proportionally increases this component’s energy and latency.

area: EvalsTo[int | float | None] = 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] = 1#: 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_costs 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_throughput(component_models=None, in_place=False)[source]#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput 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_component_costs(component_models=None, in_place=False, _use_cache=False)[source]#

Calculates the area, energy, leak power, and throughput 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>.throughput, 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 = None#: The class of this Component. Used if an energy or area model needs to be called for this Component.

component_model: ComponentModel | None = 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] = True#: 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] = 1#: 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 = _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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

latency_scale: EvalsTo[int | float] = 1#: Deprecated; use throughput_scale instead. Setting this to a non-default value emits a deprecation warning and auto-converts to throughput_scale = 1 / latency_scale.

leak_power: EvalsTo[int | float | None] = 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] = 1#: 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] = 1#: 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)

throughput_scale: EvalsTo[int | float] = 1#: The scale factor for the throughput of this component. Multiplies the calculated throughput of each action. For example, if the throughput attribute is 1M actions/second and the scale factor is 2, then the final throughput is 2M actions/second.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

total_area: EvalsTo[int | float | None] = 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 = 'sum(a.n_calls / a.throughput for a in actions)'#

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.
actions: The list of Action objects for this component. Action attributes include n_calls as well as all generally-available action attributes.

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 takes the max bound across separate ports: max(a.n_calls / a.throughput for a in actions).

total_leak_power: EvalsTo[int | float | None] = 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.

calculate_action_energy(component_models=None, in_place=False)#

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_throughput(component_models=None, in_place=False)#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)#

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_component_costs(component_models=None, in_place=False, _use_cache=False)#

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)#

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

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_component_class(trying_to_calculate=None)#

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

populate_component_model(component_models=None, in_place=False, trying_to_calculate=None)#

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)

skip_initial_output_write: bool = True#: If False, the initial value of output tensors will be fetched from above and used to initalize outputs. If True, this initial fetch and fill is skipped.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

calculate_action_energy(component_models=None, in_place=False)#

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_throughput(component_models=None, in_place=False)#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)#

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_component_costs(component_models=None, in_place=False, _use_cache=False)#

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)#

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

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_component_class(trying_to_calculate=None)#

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

populate_component_model(component_models=None, in_place=False, trying_to_calculate=None)#

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)

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

skip_initial_output_write: bool = True#: If False, the initial value of output tensors will be fetched from above and used to initalize outputs. If True, this initial fetch and fill is skipped.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

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

bits_per_action: EvalsTo[int | float | None] = 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: EvalsTo[dict] = {}#: Sets the bits per value for tensors in this TensorHolder. Keys are evaluated as expressions and may reference one or more tensors. Tensors not listed use the workload’s bits_per_value.

calculate_action_energy(component_models=None, in_place=False)#

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_throughput(component_models=None, in_place=False)#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)#

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_component_costs(component_models=None, in_place=False, _use_cache=False)#

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)#

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

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_component_class(trying_to_calculate=None)#

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

populate_component_model(component_models=None, in_place=False, trying_to_calculate=None)#

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)

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

topology: TopologySpec = <TopologySpec.MESH: 'mesh'>#: The topology of the network.

total_latency: str | int | float#

Models latency as either: - Latency-bound, which means that the latency of the route with the most number of

hops dominate the overall communication latency.

Bandwidth-bound, which means that the traffic over the most congested link dominates the overall communication latency.

Keywords: - max_hops returns the number of hops in the longest route. - max_link_traffic returns the amount of traffic (in bits) over the most congested

link.

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] = 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. Overridden by values_per_action or by values in each action.

bits_per_value: EvalsTo[dict] = {}#: Sets the bits per value for tensors in this TensorHolder. Keys are evaluated as expressions and may reference one or more tensors. Tensors not listed use the workload’s bits_per_value.

calculate_action_energy(component_models=None, in_place=False)#

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_throughput(component_models=None, in_place=False)#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)#

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_component_costs(component_models=None, in_place=False, _use_cache=False)#

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)#

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

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_component_class(trying_to_calculate=None)#

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

populate_component_model(component_models=None, in_place=False, trying_to_calculate=None)#

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)

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

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

values_per_action: EvalsTo[dict] = {}#: Sets the number of tensor values that are accessed by each action of this TensorHolder. Keys are evaluated as expressions and may reference one or more tensors. Overrides bits_per_action, and sets bits_per_action to values_per_action[tensor] * bits_per_value[tensor]. Overridden by values_per_action in any action of this component.

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

Bases: Action

bits_per_action: EvalsTo[int | float] = '1 if bits_per_action is None else bits_per_action'#: 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. Overridden by values_per_action in this action or by the parent component’s values per action.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

property n_calls: int | float#: The number of times this action is performed in the current Einsum. When accessed through the total_latency expression, returns the number of calls of this action in the current Einsum.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

values_per_action: EvalsTo[dict] = {}#: Sets the number of tensor values that are accessed by each call of this action. Keys are evaluated as expressions and may reference one or more tensors. Overrides bits_per_action, and sets bits_per_action to values_per_action[tensor] * bits_per_value[tensor].

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]] = 'Nothing'#: 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 = True#

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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

keep: TryEvalTo[InvertibleSet[str]] = '<Defaults to Nothing>'#: 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]] = '<Nothing if keep is defined, else All>'#: 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]] = '~All'#: 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]] = '~All'#: 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.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

calculate_action_energy(component_models=None, in_place=False)#

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_throughput(component_models=None, in_place=False)#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)#

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_component_costs(component_models=None, in_place=False, _use_cache=False)#

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)#

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

direction: TryEvalTo[dict]#

The direction in which data flows through this Toll. Can be:

A string: "up", "down", or "up_and_down" — applies to all tensors.
A dict mapping tensor expressions to direction strings, e.g. {input: "down", output: "up"} — sets direction per tensor.

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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_component_class(trying_to_calculate=None)#

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

populate_component_model(component_models=None, in_place=False, trying_to_calculate=None)#

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)

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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

Bases: StrEnum

ALL_TO_ALL = 'all_to_all'#

MESH = 'mesh'#

__new__(value)#

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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

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)

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

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]] = '<Same as reuse if reuse is defined, else All>'#

A set of a tensors or set expression representing tensors that the hardware may reuse across spatial iterations. If a tensor is not in this set, then hardware must unicast its values to all spatial instances that use it. If this is not defined and reuse is also not defined, all tensors may be reused. If reuse is defined, then may_reuse defaults to the same value as reuse.

Note that this behaves differently from reuse in that may_reuse has no effect on whether a particular spatial loop is valid, only on how data is moved to/from spatial instances. On the other hand, reuse constrains which loops are valid.

min_usage: EvalsTo[int | float] = 0.0#: 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. These constraints are disabled for copy Einsums.

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

power_gateable: EvalsTo[bool] = False#: 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]] = '<Defaults to Nothing>'#

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 that this behaves differently from may_reuse in that may_reuse has no effect on whether a particular spatial loop is valid, only on how data is moved to/from spatial instances. On the other hand, reuse constrains which loops are valid.

Note that loops may be removed from the mapping if they do not reuse a tensor given here and they do not appear in another loop bound constraint.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

usage_scale: EvalsTo[int | float | str] = 1#: 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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

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.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

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.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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

Bases: EvalableList

A list of ArchNodes.

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

Bases: Branch, Spatialable

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

get_nodes_of_type(types)#

Return type:: Iterator[TypeVar(T)]

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

name: str#

render()[source]#

Renders the architecture as a Pydot graph.

Return type:: str

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_nodes_of_type(types)[source]#

Return type:: Iterator[TypeVar(T)]

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

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)]] = ArchNodes([])#

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

forked_power_gateable: bool = False#: 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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_nodes_of_type(types)#

Return type:: Iterator[TypeVar(T)]

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

non_forked_power_gateable: bool = False#: 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.

render()#

Renders the architecture as a Pydot graph.

Return type:: str

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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

Bases: Branch

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_nodes_of_type(types)#

Return type:: Iterator[TypeVar(T)]

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

render()[source]#

Renders the architecture as a Pydot graph.

Return type:: str

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

name: str#: The name of this Leaf.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

Module contents#

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

Bases: EvalableModel

An action that may be performed by a component.

energy: EvalsTo[int | float | None] = 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] = 1#: The scale factor for dynamic energy of this action. Multiplies this action’s energy by this value.

extra_attributes_for_component_model: EvalExtras = 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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

latency: EvalsTo[int | float | None] = None#: Deprecated; use throughput instead. Setting this emits a deprecation warning and auto-converts to throughput = 1 / latency.

latency_scale: EvalsTo[int | float] = 1#: Deprecated; use throughput_scale instead. Setting this to a non-default value emits a deprecation warning and auto-converts to throughput_scale = 1 / latency_scale.

property n_calls: int | float#: The number of times this action is performed in the current Einsum. When accessed through the total_latency expression, returns the number of calls of this action in the current Einsum.

name: str#: The name of this action.

throughput: EvalsTo[int | float | None] = None#: Throughput of this action in actions/second. Per-action throughput is multiplied by the component’s throughput_scale and the action’s throughput_scale.

throughput_scale: EvalsTo[int | float] = 1#: The scale factor for throughput of this action. Multiplies this action’s throughput by this value.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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 = 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(name, default=_FIND_SENTINEL)#

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)#

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)]

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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_nodes_of_type(types)#

Return type:: Iterator[TypeVar(T)]

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

nodes: ArchNodes[Annotated[Annotated['Compute', Tag('Compute')] | Annotated['Memory', Tag('Memory')] | Annotated['Toll', Tag('Toll')] | Annotated['Container', Tag('Container')] | Annotated['Network', Tag('Network')] | Annotated['Hierarchical', Tag('Hierarchical')] | Annotated['Array', Tag('Array')] | Annotated['Fork', Tag('Fork')], Discriminator(_get_tag)]] = ArchNodes([])#

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]

render()#

Renders the architecture as a Pydot graph.

Return type:: str

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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 = 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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

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.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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

Bases: EvalableList

A list of ArchNodes.

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

Bases: Branch, Spatialable

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

get_nodes_of_type(types)#

Return type:: Iterator[TypeVar(T)]

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

name: str#

nodes: ArchNodes[Annotated[Annotated['Compute', Tag('Compute')] | Annotated['Memory', Tag('Memory')] | Annotated['Toll', Tag('Toll')] | Annotated['Container', Tag('Container')] | Annotated['Network', Tag('Network')] | Annotated['Hierarchical', Tag('Hierarchical')] | Annotated['Array', Tag('Array')] | Annotated['Fork', Tag('Fork')], Discriminator(_get_tag)]] = ArchNodes([])#

render()[source]#

Renders the architecture as a Pydot graph.

Return type:: str

spatial: EvalableList[Spatial] = []#

The spatial fanouts of this Leaf.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_nodes_of_type(types)[source]#

Return type:: Iterator[TypeVar(T)]

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

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)]] = ArchNodes([])#

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

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)

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

actions_scale: EvalsTo[int | float] = 1#: Scales the number of actions performed by this component. Multiplies the action count for each action of this component, which proportionally increases this component’s energy and latency.

area: EvalsTo[int | float | None] = 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] = 1#: 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_throughput(component_models=None, in_place=False)[source]#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput 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_component_costs(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 = None#: The class of this Component. Used if an energy or area model needs to be called for this Component.

component_model: ComponentModel | None = 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] = True#: 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] = 1#: 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 = _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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

latency_scale: EvalsTo[int | float] = 1#: Deprecated; use throughput_scale instead. Setting this to a non-default value emits a deprecation warning and auto-converts to throughput_scale = 1 / latency_scale.

leak_power: EvalsTo[int | float | None] = 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] = 1#: 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] = 1#: 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)

spatial: EvalableList[Spatial] = []#

The spatial fanouts of this Leaf.

throughput_scale: EvalsTo[int | float] = 1#: The scale factor for the throughput of this component. Multiplies the calculated throughput of each action. For example, if the throughput attribute is 1M actions/second and the scale factor is 2, then the final throughput is 2M actions/second.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

total_area: EvalsTo[int | float | None] = 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 = 'sum(a.n_calls / a.throughput for a in actions)'#

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.
actions: The list of Action objects for this component. Action attributes include n_calls as well as all generally-available action attributes.

For example, the following expression takes the max bound across separate ports: max(a.n_calls / a.throughput for a in actions).

total_leak_power: EvalsTo[int | float | None] = 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.

actions_scale: EvalsTo[int | float] = 1#: Scales the number of actions performed by this component. Multiplies the action count for each action of this component, which proportionally increases this component’s energy and latency.

area: EvalsTo[int | float | None] = 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] = 1#: 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)#

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_throughput(component_models=None, in_place=False)#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)#

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_component_costs(component_models=None, in_place=False, _use_cache=False)#

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)#

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 = None#: The class of this Component. Used if an energy or area model needs to be called for this Component.

component_model: ComponentModel | None = 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] = True#: 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] = 1#: 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 = _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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_component_class(trying_to_calculate=None)#

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

latency_scale: EvalsTo[int | float] = 1#: Deprecated; use throughput_scale instead. Setting this to a non-default value emits a deprecation warning and auto-converts to throughput_scale = 1 / latency_scale.

leak_power: EvalsTo[int | float | None] = 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] = 1#: 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] = 1#: 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)#

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)

skip_initial_output_write: bool = True#: If False, the initial value of output tensors will be fetched from above and used to initalize outputs. If True, this initial fetch and fill is skipped.

spatial: EvalableList[Spatial] = []#

The spatial fanouts of this Leaf.

throughput_scale: EvalsTo[int | float] = 1#: The scale factor for the throughput of this component. Multiplies the calculated throughput of each action. For example, if the throughput attribute is 1M actions/second and the scale factor is 2, then the final throughput is 2M actions/second.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

total_area: EvalsTo[int | float | None] = 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 = 'sum(a.n_calls / a.throughput for a in actions)'#

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.
actions: The list of Action objects for this component. Action attributes include n_calls as well as all generally-available action attributes.

For example, the following expression takes the max bound across separate ports: max(a.n_calls / a.throughput for a in actions).

total_leak_power: EvalsTo[int | float | None] = 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.Container[source]#

Bases: Leaf, Spatialable

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

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

forked_power_gateable: bool = False#: 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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_nodes_of_type(types)#

Return type:: Iterator[TypeVar(T)]

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

nodes: ArchNodes[Annotated[Annotated['Compute', Tag('Compute')] | Annotated['Memory', Tag('Memory')] | Annotated['Toll', Tag('Toll')] | Annotated['Container', Tag('Container')] | Annotated['Network', Tag('Network')] | Annotated['Hierarchical', Tag('Hierarchical')] | Annotated['Array', Tag('Array')] | Annotated['Fork', Tag('Fork')], Discriminator(_get_tag)]] = ArchNodes([])#

non_forked_power_gateable: bool = False#: 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.

render()#

Renders the architecture as a Pydot graph.

Return type:: str

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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

Bases: Branch

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_nodes_of_type(types)#

Return type:: Iterator[TypeVar(T)]

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

render()[source]#

Renders the architecture as a Pydot graph.

Return type:: str

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

name: str#: The name of this Leaf.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

actions_scale: EvalsTo[int | float] = 1#: Scales the number of actions performed by this component. Multiplies the action count for each action of this component, which proportionally increases this component’s energy and latency.

area: EvalsTo[int | float | None] = 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] = 1#: 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.

bits_per_action: EvalsTo[int | float | None] = 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. Overridden by values_per_action or by values in each action.

bits_per_value: EvalsTo[dict] = {}#: Sets the bits per value for tensors in this TensorHolder. Keys are evaluated as expressions and may reference one or more tensors. Tensors not listed use the workload’s bits_per_value.

calculate_action_energy(component_models=None, in_place=False)#

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_throughput(component_models=None, in_place=False)#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)#

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_component_costs(component_models=None, in_place=False, _use_cache=False)#

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)#

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 = None#: The class of this Component. Used if an energy or area model needs to be called for this Component.

component_model: ComponentModel | None = 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] = True#: 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] = 1#: 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 = _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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_component_class(trying_to_calculate=None)#

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

latency_scale: EvalsTo[int | float] = 1#: Deprecated; use throughput_scale instead. Setting this to a non-default value emits a deprecation warning and auto-converts to throughput_scale = 1 / latency_scale.

leak_power: EvalsTo[int | float | None] = 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] = 1#: 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] = 1#: 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)#

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)

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

skip_initial_output_write: bool = True#: If False, the initial value of output tensors will be fetched from above and used to initalize outputs. If True, this initial fetch and fill is skipped.

spatial: EvalableList[Spatial] = []#

The spatial fanouts of this Leaf.

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

throughput_scale: EvalsTo[int | float] = 1#: The scale factor for the throughput of this component. Multiplies the calculated throughput of each action. For example, if the throughput attribute is 1M actions/second and the scale factor is 2, then the final throughput is 2M actions/second.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

total_area: EvalsTo[int | float | None] = 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 = 'sum(a.n_calls / a.throughput for a in actions)'#

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.
actions: The list of Action objects for this component. Action attributes include n_calls as well as all generally-available action attributes.

For example, the following expression takes the max bound across separate ports: max(a.n_calls / a.throughput for a in actions).

total_leak_power: EvalsTo[int | float | None] = 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.

values_per_action: EvalsTo[dict] = {}#: Sets the number of tensor values that are accessed by each action of this TensorHolder. Keys are evaluated as expressions and may reference one or more tensors. Overrides bits_per_action, and sets bits_per_action to values_per_action[tensor] * bits_per_value[tensor]. Overridden by values_per_action in any action of this component.

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

Bases: EvalableModel

A one-dimensional spatial fanout in the architecture.

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

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

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]] = '<Same as reuse if reuse is defined, else All>'#

min_usage: EvalsTo[int | float] = 0.0#: 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. These constraints are disabled for copy Einsums.

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

power_gateable: EvalsTo[bool] = False#: 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]] = '<Defaults to Nothing>'#

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 that loops may be removed from the mapping if they do not reuse a tensor given here and they do not appear in another loop bound constraint.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

usage_scale: EvalsTo[int | float | str] = 1#: 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.

actions_scale: EvalsTo[int | float] = 1#: Scales the number of actions performed by this component. Multiplies the action count for each action of this component, which proportionally increases this component’s energy and latency.

area: EvalsTo[int | float | None] = 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] = 1#: 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.

bits_per_action: EvalsTo[int | float | None] = 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. Overridden by values_per_action or by values in each action.

bits_per_value: EvalsTo[dict] = {}#: Sets the bits per value for tensors in this TensorHolder. Keys are evaluated as expressions and may reference one or more tensors. Tensors not listed use the workload’s bits_per_value.

calculate_action_energy(component_models=None, in_place=False)#

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_throughput(component_models=None, in_place=False)#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)#

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_component_costs(component_models=None, in_place=False, _use_cache=False)#

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)#

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 = None#: The class of this Component. Used if an energy or area model needs to be called for this Component.

component_model: ComponentModel | None = 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] = True#: 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] = 1#: 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 = _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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_component_class(trying_to_calculate=None)#

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

latency_scale: EvalsTo[int | float] = 1#: Deprecated; use throughput_scale instead. Setting this to a non-default value emits a deprecation warning and auto-converts to throughput_scale = 1 / latency_scale.

leak_power: EvalsTo[int | float | None] = 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] = 1#: 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] = 1#: 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)#

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)

spatial: EvalableList[Spatial] = []#

The spatial fanouts of this Leaf.

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

throughput_scale: EvalsTo[int | float] = 1#: The scale factor for the throughput of this component. Multiplies the calculated throughput of each action. For example, if the throughput attribute is 1M actions/second and the scale factor is 2, then the final throughput is 2M actions/second.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

total_area: EvalsTo[int | float | None] = 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 = 'sum(a.n_calls / a.throughput for a in actions)'#

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.
actions: The list of Action objects for this component. Action attributes include n_calls as well as all generally-available action attributes.

For example, the following expression takes the max bound across separate ports: max(a.n_calls / a.throughput for a in actions).

total_leak_power: EvalsTo[int | float | None] = 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.

values_per_action: EvalsTo[dict] = {}#: Sets the number of tensor values that are accessed by each action of this TensorHolder. Keys are evaluated as expressions and may reference one or more tensors. Overrides bits_per_action, and sets bits_per_action to values_per_action[tensor] * bits_per_value[tensor]. Overridden by values_per_action in any action of this component.

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

Bases: Action

bits_per_action: EvalsTo[int | float] = '1 if bits_per_action is None else bits_per_action'#: 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. Overridden by values_per_action in this action or by the parent component’s values per action.

energy: EvalsTo[int | float | None] = 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] = 1#: The scale factor for dynamic energy of this action. Multiplies this action’s energy by this value.

extra_attributes_for_component_model: EvalExtras = 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.

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

latency: EvalsTo[int | float | None] = None#: Deprecated; use throughput instead. Setting this emits a deprecation warning and auto-converts to throughput = 1 / latency.

latency_scale: EvalsTo[int | float] = 1#: Deprecated; use throughput_scale instead. Setting this to a non-default value emits a deprecation warning and auto-converts to throughput_scale = 1 / latency_scale.

property n_calls: int | float#: The number of times this action is performed in the current Einsum. When accessed through the total_latency expression, returns the number of calls of this action in the current Einsum.

name: str#: The name of this action.

throughput: EvalsTo[int | float | None] = None#: Throughput of this action in actions/second. Per-action throughput is multiplied by the component’s throughput_scale and the action’s throughput_scale.

throughput_scale: EvalsTo[int | float] = 1#: The scale factor for throughput of this action. Multiplies this action’s throughput by this value.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

values_per_action: EvalsTo[dict] = {}#: Sets the number of tensor values that are accessed by each call of this action. Keys are evaluated as expressions and may reference one or more tensors. Overrides bits_per_action, and sets bits_per_action to values_per_action[tensor] * bits_per_value[tensor].

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]] = 'Nothing'#: 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 = True#

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

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

keep: TryEvalTo[InvertibleSet[str]] = '<Defaults to Nothing>'#: 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]] = '<Nothing if keep is defined, else All>'#: 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]] = '~All'#: 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]] = '~All'#: 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.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

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.

actions_scale: EvalsTo[int | float] = 1#: Scales the number of actions performed by this component. Multiplies the action count for each action of this component, which proportionally increases this component’s energy and latency.

area: EvalsTo[int | float | None] = 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] = 1#: 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.

bits_per_action: EvalsTo[int | float | None] = 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. Overridden by values_per_action or by values in each action.

bits_per_value: EvalsTo[dict] = {}#: Sets the bits per value for tensors in this TensorHolder. Keys are evaluated as expressions and may reference one or more tensors. Tensors not listed use the workload’s bits_per_value.

calculate_action_energy(component_models=None, in_place=False)#

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_throughput(component_models=None, in_place=False)#

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

Parameters:

component_models (list[ComponentModel] | None) – The models to use for throughput 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 throughput for each action.

Return type:

Self

calculate_area(component_models=None, in_place=False)#

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_component_costs(component_models=None, in_place=False, _use_cache=False)#

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)#

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 = None#: The class of this Component. Used if an energy or area model needs to be called for this Component.

component_model: ComponentModel | None = 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.

direction: TryEvalTo[dict]#

The direction in which data flows through this Toll. Can be:

A string: "up", "down", or "up_and_down" — applies to all tensors.
A dict mapping tensor expressions to direction strings, e.g. {input: "down", output: "up"} — sets direction per tensor.

enabled: TryEvalTo[bool] = True#: 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] = 1#: 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 = _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.

find(name, default=_FIND_SENTINEL)#

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)#

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)]

classmethod from_yaml(*files, jinja_parse_data=None, top_key=None, **kwargs)#

Loads a dictionary from one more more yaml files.

Each yaml file should contain a dictionary. Dictionaries are combined in the order they are given.

Keyword arguments are also added to the dictionary.

Parameters:

files (str | list[str] | Path | list[Path]) – A list of yaml files to load.
jinja_parse_data (dict[str, Any] | None) – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key (str | None) – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the Jinja2 parser.

Return type:

TypeVar(T)

Returns:

A dict containing the combined dictionaries.

get_component_class(trying_to_calculate=None)#

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

get_fanout()#

The spatial fanout of this node.

Return type:: int

get_fanout_along(dim_name, default=1)#

Return type:: int

is_above(node_a, node_b)#

Returns whether node_a is above node_b in a hierarchy.

Return type:: bool

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

latency_scale: EvalsTo[int | float] = 1#: Deprecated; use throughput_scale instead. Setting this to a non-default value emits a deprecation warning and auto-converts to throughput_scale = 1 / latency_scale.

leak_power: EvalsTo[int | float | None] = 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] = 1#: 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] = 1#: 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)#

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)

spatial: EvalableList[Spatial] = []#

The spatial fanouts of this Leaf.

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

throughput_scale: EvalsTo[int | float] = 1#: The scale factor for the throughput of this component. Multiplies the calculated throughput of each action. For example, if the throughput attribute is 1M actions/second and the scale factor is 2, then the final throughput is 2M actions/second.

to_yaml(f=None)#

Dump the model to a YAML string.

Parameters:

f (str | None) – The file to write the YAML to. If not given, then returns as a string.
exclude (IncEx | None) – The fields to exclude from the YAML.

Returns:

The YAML string.

Return type:

str

total_area: EvalsTo[int | float | None] = 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 = 'sum(a.n_calls / a.throughput for a in actions)'#

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.
actions: The list of Action objects for this component. Action attributes include n_calls as well as all generally-available action attributes.

For example, the following expression takes the max bound across separate ports: max(a.n_calls / a.throughput for a in actions).

total_leak_power: EvalsTo[int | float | None] = 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.

values_per_action: EvalsTo[dict] = {}#: Sets the number of tensor values that are accessed by each action of this TensorHolder. Keys are evaluated as expressions and may reference one or more tensors. Overrides bits_per_action, and sets bits_per_action to values_per_action[tensor] * bits_per_value[tensor]. Overridden by values_per_action in any action of this component.