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.

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

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

Parameters:

  • name (str) – The name of the spatial dimension to find.

  • return_spatialable (bool) – Whether to return the node that the spatial dimension is associated with.

Return type:

Spatial | tuple[Spatialable, Spatial]

Returns:

  • Spatial – The spatial dimension with the given name if return_spatialable is False.

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

Raises:

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

property per_component_total_area: dict[str, float]#

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

Returns:

A dictionary of component names to their total area in m^2.

Return type:

dict[str, float]

property per_component_total_leak_power: dict[str, float]#

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

Returns:

A dictionary of component names to their total leak power in W.

Return type:

dict[str, float]

property total_area: float#

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

Returns:

The total area of the architecture in m^2.

Return type:

float

property total_leak_power: float#

Returns the total leak power of the architecture in W.

Returns:

The total leak power of the architecture in W.

Return type:

float

variables: EvalExtras#

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

class accelforge.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 Jinja2 parser.

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) – The field where the error occurred.

  • message (str) – 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.

clear_irrelevant_reservations(relevant_tensors)[source]#
property loops: list[Loop]#

Returns all Loop nodes in the Mapping.

remove_reservations()[source]#
render(with_reservations=True, with_tile_shape=True)[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(einsum_name)[source]#
split_reservations()[source]#
split_tensor_holders_with_multiple_tensors()[source]#
class accelforge.Metrics[source]#

Bases: Flag

Metrics used to optimize mappings or reported by model.

ACTIONS = 32#

Action counts.

DETAILED_MEMORY_USAGE = 64#

Memory usage broken down by tensor and Einsum.

DYNAMIC_ENERGY = 4#

The amount of dynamic energy consumed by the workload.

ENERGY = 2#

The amount of energy consumed by the workload.

LATENCY = 1#

The amount of time taken to execute the workload.

LEAK_ENERGY = 8#

The amount of leak energy consumed by the workload.

RESOURCE_USAGE = 16#

The amount of resources used by the workload.

When used as a mapper objective, this objective is multivariate, and must consider every resource available to the hardware.

__new__(value)#
classmethod all_metrics()[source]#
includes_dynamic_energy()[source]#

Returns True if the metrics include dynamic energy, either alone or as part of total energy. False otherwise.

Return type:

bool

includes_leak_energy()[source]#

Returns True if the metrics include leak energy, either alone or as part of total energy. False otherwise.

Return type:

bool

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 (str | 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) – Whether to compute and populate area entries.

  • energy (bool) – Whether to compute and populate energy entries.

  • latency (bool) – Whether to compute and populate latency entries.

  • leak (bool) – Whether to compute and populate leak power entries.

Return type:

Spec

config: Config#

Configuration settings.

evaluate_mapping()[source]#

Evaluate the mapping in the spec.

Return type:

Mappings

map_workload_to_arch(einsum_names=None, one_pbar_only=False, print_progress=True, 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.

  • one_pbar_only (bool) – Whether to only print only a single progress bar. If this is True, then only a progress bar will be created for making tile shapes, which is generally the longest-running part of the mapping process.

  • print_progress (bool) – Whether to print progress of the mapping process, including progress bars.

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

__init__(**data)[source]#

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.

accesses_for_tensor(tensor)[source]#

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

Parameters:

tensor (str) – 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_value 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 (str) – 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 (str) – 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 (str) – 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_compute_intensity(einsum_name)[source]#

Returns the compute intensity of the given Einsum, defined as the number of computes divided by the total number of tensor elements.

Parameters:

einsum_name (str) – The name of the Einsum.

Returns:

The compute intensity in #computes / #tensor elements.

Return type:

float

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[str, set[str]]

get_tensor_shape(tensor)[source]#
Return type:

dict[str, int]

get_tensor_size(tensor)[source]#

Returns the number of elements in the given tensor.

Parameters:

tensor (str) – The name of the tensor.

Returns:

The number of elements in the tensor.

Return type:

int

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.

num_computes(einsum_name=None)[source]#

Returns the number of computes for the given Einsum name, or total computes across all Einsums if einsum_name is None.

Parameters:

einsum_name (str | None) – The name of the Einsum. If None, returns the total number of computes across all Einsums.

Returns:

The number of computes.

Return type:

int

persistent_tensors: str | None#

Set expression for identifying persistent tensors. Evaluated per-Einsum to mark matching tensors as persistent. Example: “weight” or “~(Outputs | Intermediates)”.

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) – Whether to print a message when the number of parallel jobs is set.

Return type:

None

On this page

This Page