accelforge.frontend package#

Subpackages#

Submodules#

accelforge.frontend.config module#

class accelforge.frontend.config.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.

accelforge.frontend.model module#

class accelforge.frontend.model.Model[source]#

Bases: EvalableModel

Configuration for the model.

metrics: Metrics#

Metrics to evaluate.

If using spec to call mapper, leave this configuration as is. The mapper will make necessary configurations.

accelforge.frontend.renames module#

class accelforge.frontend.renames.EinsumRename[source]#

Bases: EvalableModel

Renames for a single Einsum.

__init__(*args, **kwargs)[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.

name: str#: The name of the Einsum. Set this to “default” to apply the renames to all Einsums, unless overridden. Overriding is specific to a single name, so every rename in the default must be overridden independently.

rank_variables: EvalableList[Rename]#: Renames for the rank variables of this Einsum. This may be given either as a dictionary {new_name: source_set_expression} expressions, or as a list of dictionaries, each one having the structure {name: new_name, source: source_set_expression, expected_count: 1}, where expected count is optional for each and may be set to any integer.

tensor_accesses: EvalableList[Rename]#: Renames for the tensor accesses of this Einsum. This may be given either as a dictionary {new_name: source_set_expression} expressions, or as a list of dictionaries, each one having the structure {name: new_name, source: source_set_expression, expected_count: 1}, where expected count is optional for each and may be set to any integer.

class accelforge.frontend.renames.Rename[source]#

Bases: EvalableModel

A rename of something into something else.

expected_count: EvalsTo[int | None]#: The expected count of the source set expression. If this is set, then the source expression must resolve to the expected count or an error will be raised. Otherwise, any count (including zero for an empty set) is allowed.

name: str#: The name of the thing to be renamed. This is a string representing the new name.

source: TryEvalTo[InvertibleSet[str]]#: The source of the rename. This is a set expression that can be evaluated, yielding a set that can be referenced by the new name.

class accelforge.frontend.renames.RenameList[source]#

Bases: EvalableList[Rename]

A list of renames.

class accelforge.frontend.renames.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

accelforge.frontend.renames.rename_list_factory(rename_list)[source]#

Return type:: RenameList

accelforge.frontend.spec module#

class accelforge.frontend.spec.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.

accelforge.frontend.spec.Specification#: alias of Spec

accelforge.frontend.variables module#

class accelforge.frontend.variables.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.

accelforge.frontend.workload module#

All the objects used for a Workload description in AccelForge.

class accelforge.frontend.workload.Einsum[source]#

Bases: EvalableModel

Represents an Einsum, which is a single computation step in the workload. The Einsum includes a set of rank variables, which are used to index into tensors. Rank variables iterate through an iteration space.

For example, if the Einsum is A[m, n] += B[k, n] * C[k, n] and we define the iteration space as “0 <= m < 10, 0 <= n < 10, 0 <= k < 10”, then the Einsum will iterate through all possible values of (m, n, k) in the iteration space, indexing into tensors for each and updating A[m, n] with B[k, n] * C[k, n].

__init__(*args, **kwargs)[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.

copy_source_tensor()[source]#

If this Einsum is a copy operation, returns the name of the tensor that is the source of the copy. Otherwise, returns None.

Return type:: str | None

static empty_renames()[source]#

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

property indexing_expressions: set[str]#: Returns a list of all the expressions that index into the tensors of this Einsum.

property input_tensor_names: set[str]#: Returns the names of the input tensors of this Einsum.

is_copy_operation: bool#: Whether the Einsum is a copy operation. Copy operations take the input tensor and directly place them at the location of the output tensor(s) without any computation. If the destination tensor is at the same location, then this is a no-op.

iteration_space_shape: Shape[str]#: Bounds of valid rank variable values. This is a list of expressions, each one an ISL expression. Additionally, global iteration_space_shape expressions are appended to the list if their rank variables are present in the Einsum’s rank_variables. For example, if the global scope has “m: 0 <= m < 10” and the Einsum has “m” in its rank_variables, then “0 <= m < 10” will be appended to the iteration_space_shape.

n_instances: int#: Number of times to repeat the Einsum. Multiplied by Workload.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.

name: str#: The name of the Einsum.

property output_tensor_names: set[str]#: Returns the names of the output tensors of this Einsum.

rank_sizes: EvalableDict[str, int]#: Sizes of ranks. 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_variable2ranks: dict[str, set[str]]#: Returns a dictionary of rank variables to the ranks that are indexed into by that rank variable.

property rank_variables: set[str]#: Returns all rank variables used in this Einsum.

property ranks: set[str]#: Returns all ranks used in this Einsum.

renames: RenameList[Rename]#: Renames of the Einsum. Renames here can be used to rename rank variables or tensors. When this Einsum is executed on an architecture, the architecture can use renamed tensors and rank variables to access the tensors and rank variables.

property tensor2directly_indexing_rank_variables: dict[str, set[str]]#: Returns a dictionary of tensor names to the rank variables that directly index into that tensor. Direct indexing means that the rank variable is used as a direct index into the tensor, without any expression (e.g., “M=m”, NOT “M=m+n”).

property tensor2expression_indexing_rank_variables: dict[str, set[str]]#: Returns a dictionary of tensor names to the rank variables that indirectly index into that tensor through an expression (e.g., “M=m+n”) instead of a direct index (e.g., “M=m”).

property tensor2irrelevant_rank_variables: dict[str, set[str]]#: Returns a dictionary of tensor names to the rank variables that are irrelevant to that tensor. Irrelevant rank variables are rank variables that are not used to index into the tensor.

property tensor2rank_variables: dict[str, set[str]]#: Returns a dictionary of tensor names to the rank variables that project into that tensor.

tensor_accesses: EvalableList[TensorAccess]#: The tensors accessed by this Einsum, and how they are accessed.

property tensor_names: set[str]#: Returns the names of all tensors of this Einsum.

class accelforge.frontend.workload.ImpliedProjection[source]#

Bases: dict

Holds a projection that has been implied by a list of rank variables. The implied rank names are uppercased versions of the rank variables; for example, [a, b, c] -> {A: a, B: b, C: c}.

class accelforge.frontend.workload.Shape[source]#

Bases: EvalableList

Specifies valid values for the rank variables. This is a list of strings, each one an ISL expression. The total space is considered to be the logal AND of all the expressions in the list.

property rank_variables: set[str]#: Returns all rank variables used in this shape.

class accelforge.frontend.workload.TensorAccess[source]#

Bases: EvalableModel

Information about how an Einsum accesses a tensor.

backing_storage_size_scale: float#: If != 1, then the backing storage size will be scaled by this factor.

bits_per_value: int | str | None#: Bits per value for this tensor.

property directly_indexing_rank_variables: set[str]#: Returns the rank variables that directly index into this tensor without any expression (e.g., “M=m”, NOT “M=m+n”).

property expression_indexing_rank_variables: set[str]#: Returns the rank variables that indirectly index into this tensor through an expression (e.g., “M=m+n”) instead of a direct index (e.g., “M=m”).

name: str#: The name of the tensor.

output: bool#: Whether the tensor is an output. False means the tensor is an input.

persistent: bool#: If True, then a copy of this tensor must remain in backing storage for the full duration of the workload’s execution.

projection: dict[str, str] | list[str]#

How the rank variables of the Einsum project into the tensor. If this is a list, then it is assumed that each of the elements of the list is a single rank variable and they index into the tensor in ranks that equal the uppercase of the rank variable. For example:

name: X, projection: [a, b, c] means X[A=a, B=b, C=c]

If this is a dictionary, it is a mapping from rank names to rank variable expressions. This can be used to either project into a non-matching rank name or to project into a tensor using an expression. For example:

name: X, projection: {A: a, B2: b, C: a+b} means X[A=a, B2=b, C=a+b]

property rank2rank_variables: dict[str, set[str]]#: Returns a dictionary of rank names to the rank variables that project into that rank.

property rank_variable2ranks: dict[str, set[str]]#: Returns a dictionary of rank variables to the ranks into which that rank variable projects.

property rank_variables: set[str]#: Returns all rank variables used in this access.

property ranks: tuple[str, ...]#: Returns the ranks of this access’s tensor.

class accelforge.frontend.workload.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.frontend.workload.isl_expression_has_variable(expression, variable)[source]#

Returns True if the given ISL expression has the given rank variable.

Parameters:

expression (str) – The ISL expression to check.
variable (str) – The rank variable to check for.

Returns:

True if the given ISL expression has the given rank variable.

Return type:

bool

Module contents#

Timeloop Spec. Each piece below (minus processors) corresponds to a top key in the Timeloop spec.

class accelforge.frontend.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]#

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.

accelforge.frontend package#

Subpackages#

Submodules#

accelforge.frontend.config module#

accelforge.frontend.model module#

accelforge.frontend.renames module#

accelforge.frontend.spec module#

accelforge.frontend.variables module#

accelforge.frontend.workload module#

Module contents#

This Page