API Reference#

Subpackages#

Module contents#

class accelforge.Arch[source]#

Bases: Hierarchical

Top-level architecture specification.

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

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

property per_component_total_area: dict[str, float]#

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

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

property per_component_total_leak_power: dict[str, float]#

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

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

property total_area: float#

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

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

property total_leak_power: float#

Returns the total leak power of the architecture in W.

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

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

class accelforge.Config[source]#

Bases: EvalableModel

component_models: EvalableList[str | ComponentModel]#: A list of hwcomponents models to use for the energy and area calculations. These can either be paths to Python files that contain the models, or hwcomponents ComponentModel objects.

expression_custom_functions: EvalableList[str | Callable]#: A list of functions to use while parsing expressions. These can either be functions or paths to Python files that contain the functions. If a path is provided, then all functions in the file will be added to the evaluator.

classmethod from_yaml(f)[source]#

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 – A list of yaml files to load.
jinja_parse_data – Optional[Dict[str, Any]] A dictionary of Jinja2 data to use when parsing the yaml files.
top_key – Optional[str] The top key to use when parsing the yaml files.
kwargs – Extra keyword arguments to be passed to the constructor.

Return type:

Config

Returns:

A dict containing the combined dictionaries.

use_installed_component_models: bool | None#: If True, then the hwcomponents library will find all installed models. If False, then only the models specified in component_models will be used.

exception accelforge.EvaluationError[source]#

Bases: Exception

Exception raised when parsing fails.

This exception is raised when there’s an error parsing specifications, architectures, workloads, or mappings.

Parameters:

*args – Standard exception arguments.
source_field (Any, optional) – The field where the error occurred.
message (str, optional) – Error message describing what went wrong.
**kwargs – Additional keyword arguments.

__init__(*args, source_field=None, message=None, **kwargs)[source]#

add_field(field)[source]#

Add a field to the error context. The output error message will include the field path as a period-separated string like “spec.arch.nodes.0.name”.

Parameters:: field (Any) – The field to add to the error context.

class accelforge.LiteralString[source]#

Bases: str

A string literal that should not be evaluated.

class accelforge.Mapping[source]#

Bases: Nested

A Mapping of a workload onto a hardware architecture.

property loops: list[Loop]#: Returns all Loop nodes in the Mapping.

remove_reservations()[source]#

render()[source]#

Return type:: _SVGJupyterRender

render_pydot(with_reservations=True, with_tile_shape=True)[source]#

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

Return type:: Dot

split_loop_with_multiple_rank_variables()[source]#

split_tensor_holders_with_multiple_tensors()[source]#

class accelforge.Metrics[source]#

Bases: Flag

Metrics used to optimize mappings.

ACTIONS = 8#: Action counts.

ENERGY = 2#: Energy. Minimize the amount of energy consumed by the workload.

LATENCY = 1#: Latency. Minimize the amount of time taken to execute the workload.

RESOURCE_USAGE = 4#: Resource usage. Minimize the amount of resources used by the workload. This objective is multivariate, and must consider every resource available to the hardware.

__new__(value)#

classmethod all_metrics()[source]#

class accelforge.Renames[source]#

Bases: EvalableModel

einsums: list[EinsumRename]#: Renames for a workload. The Einsum list is a list of EinsumRename objects, and renames will be applied to Einsums whose names match the EinsumRename.name. If an EinsumRename is named “default”, then its renames are applied to every Einsum unless overridden. Overriding is specific to a single name, so every rename in the default must be overridden independently.

get_renames_for_einsum(einsum_name)[source]#

Return type:: EinsumRename

class accelforge.Spec[source]#

Bases: EvalableModel

The top-level spec of all of the inputs to this package.

arch: Arch#: The hardware architecture being used.

calculate_component_area_energy_latency_leak(einsum_name=None, area=True, energy=True, latency=True, leak=True)[source]#

Populates per-component area, energy, latency, and/or leak power. For each component, populates the area, total_area, leak_power and total_leak_power. Additionally, for each action of each component, populates the <action>.energy and <action>.latency fields. Extends the component_modeling_log field with log messages. Also populates the component_model attribute for each component if not already set.

Some architectures’ attributes may depend on the workload. In that case, an Einsum name can be provided to populate those symbols with the Einsum’s symbols from the workload.

Parameters:

einsum_name (EinsumName | None = None) – Optional Einsum name to populate symbols with the Einsum’s symbols from the workload. If None, and there are Einsums in the workload, the first Einsum is used. If None and there are no Einsums in the workload, then no symbols are populated from the workload.
area (bool, optional) – Whether to compute and populate area entries.
energy (bool, optional) – Whether to compute and populate energy entries.
latency (bool, optional) – Whether to compute and populate latency entries.
leak (bool, optional) – Whether to compute and populate leak power entries.

Return type:

Spec

config: Config#: Configuration settings.

map_workload_to_arch(einsum_names=None, print_number_of_pmappings=True, _pmapping_row_filter_function=None)[source]#

Maps the workload to the architecture using the AccelForge Fast and Fusiest Mapper (FFM).

Parameters:

spec – The Spec to map.
einsum_names (list[str] | None) – The einsum names to map. If None, all einsums will be mapped.
can_combine_multiple_runs (Whether we would like to be able to combine multiple) – make_pmappings runs. Having this as True allows you to do things like pmappings = make_pmappings(*args_a) | make_pmappings(*args_b) but slows down execution.
cache_dir – The directory to cache pmappings in. If None, no caching will be done.
print_number_of_pmappings (bool) – Whether to print the number of pmappings for each einsum.
_pmapping_row_filter_function (Optional[Callable[[Series], bool]]) – A function that takes in a row of the pmapping dataframe and returns True if the row should be included in the final mappings, and False otherwise. If None, all rows will be included.

Returns:

The mappings of the workload to the architecture.

Return type:

Mappings

mapper: FFM#: Configures the mapper used to map the workload onto the architecture.

mapping: Mapping#: How the workload is programmed onto the architecture. Do not specify this if you’d like the mapper to generate a mapping for you.

model: Model#: Configures the model used to evaluate mappings.

renames: Renames#: Aliases for tensors in the workload so that they can be called by canonical names when writing architecture constraints. For example, workload tensors may be renamed to “input”, “output”, and “weight”.

variables: Variables#: Variables that can be referenced in other places in the spec.

workload: Workload#: The program to be run on the arch.

class accelforge.Variables[source]#

Bases: EvalExtras

Variables that can be used in parsing. All variables defined here can be referenced elsewhere in any of the Spec’s evaluated expressions.

class accelforge.Workload[source]#

Bases: EvalableModel

The workload specification as a cascade of Einsums, with each Einsum being a computation step in the workload.

accesses_for_tensor(tensor)[source]#

Returns all TensorAccess objects that access the given tensor across all Einsums.

Parameters:: tensor (TensorName) – The tensor to check.
Returns:: The TensorAccess objects that access the given tensor across all Einsums. Order is the same as the order in this workload’s Einsums list.
Return type:: list[TensorAccess]

bits_per_value: EvalableDict[str, int | str]#: Bits per value for each tensor. The workload-level bits_per_value is overridden if bits_per_action is specified for any given tensor access. This is a dictionary of set expressions to bits per value for the tensors given by those expressions. For example, we may write “Inputs: 8” to set the bits per value to 8 for all input tensors, unless overridden.

property einsum_names: list[str]#: Returns the names of the Einsums in the workload.

einsums: EvalableList[Einsum]#: The Einsums in the workload.

einsums_with_tensor(tensor)[source]#

Returns the Einsums in the workload that access the given tensor.

Parameters:: tensor (TensorName) – The tensor to check.
Returns:: The Einsums in the workload that access the given tensor. Order is the same as the order in this workload’s Einsums list.
Return type:: list[Einsum]

einsums_with_tensor_as_input(tensor)[source]#

Returns the Einsums in the workload that use the given tensor as an input.

Parameters:: tensor (TensorName) – The tensor to check.
Returns:: The Einsums in the workload that use the given tensor as an input. Order is the same as the order in this workload’s Einsums list.
Return type:: list[Einsum]

einsums_with_tensor_as_output(tensor)[source]#

Returns the Einsums in the workload that have the given tensor as an output.

Parameters:: tensor (TensorName) – The tensor to check.
Returns:: The Einsums in the workload that have the given tensor as an output. Order is the same as the order in this workload’s Einsums list.
Return type:: list[Einsum]

empty_renames()[source]#

Return type:: dict[str, InvertibleSet[str]]

get_iteration_space_shape_isl_string(einsum_name)[source]#

Returns the ISL string representing the iteration space of the given Einsum.

Parameters:: einsum_name (str) – The name of the Einsum for which to get the iteration space shape.
Returns:: The ISL string representing the iteration space shape of the given Einsum.
Return type:: str

get_tensor_copies()[source]#

Returns a dictionary specifying which tensors are copies of which other tensors. For example, if einsum A copies tensor X into tensors Y and Z, then we’d have in the return value X: {Y, Z}, Y: {X, Z}, and Z: {X, Y}. This is transitive.

Returns:: A dictionary specifying which tensors are copies of which other tensors. The keys are the tensors that are copies, and the values are sets of tensors that are copies of the key.
Return type:: dict[TensorName, set[TensorName]]

iteration_space_shape: EvalableDict[str, str]#: Bounds of valid rank variable values. This is a dictionary of rank variable names to bounds of valid rank variable values. The bounds are specified as a string in the ISL format. For example, “0 <= a < 10” means that the rank variable a must be between 0 and 10, including 0 but not 10. Bounds are included for all Einsums that include that rank variable.

n_instances: int#: Number of times to repeat the workload. Multiplied by Einsum.n_instances to get the total number of Einsum instances. Energy, latency, and other summable metrics are multiplied by this value. Persistent reservations are also multiplied by this value, but non-persistent reservations are not, as they are assumed to be freed between each instance.

rank_sizes: EvalableDict[str, EvalsTo[int]]#: Rank sizes. This is a dictionary of rank names to sizes. Sizes are integers, and the rank’s bounds are 0 <= rank < size. Accesses outside of these bounds are skipped.

property rank_variables: set[str]#: Returns the names of all rank variables in the workload.

render()[source]#

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

Return type:: str

property tensor_names: set[str]#: Returns the names of all tensors in the workload.

property tensor_names_used_in_multiple_einsums: set[str]#: Returns the names of the tensors that are used in multiple Einsums.

accelforge.set_n_parallel_jobs(n_jobs, print_message=False)[source]#

Set the number of parallel jobs to use.

Parameters:

n_jobs (int) – The number of parallel jobs to use.
print_message (bool, optional) – Whether to print a message when the number of parallel jobs is set.

Return type:

None

API Reference#

Subpackages#

Module contents#

This Page