accelforge.mapper.FFM package

Submodules

accelforge.mapper.FFM.data module

Results from mapping exploration.

class accelforge.mapper.FFM.data.ActionDataFrame

Bases: DataFrame

A hierarchical column dataframe with action counts.

class accelforge.mapper.FFM.data.ResultDataFrame

Bases: DataFrame

property actions: ResultDataFrame

Returns a ResultDataFrame with all action-related columns.

property actions_df: ActionDataFrame

Return an ActionDataFrame.

property energy: ResultDataFrame

Returns a ResultDataFrame with all energy-related columns.

class accelforge.mapper.FFM.data.VerboseActionDataFrame

Bases: DataFrame

A hierarchical column dataframe with verbose action counts.

accelforge.mapper.FFM.main module

accelforge.mapper.FFM.main.join_pmappings(pmappings, require_all_einsums=True, _pmapping_row_filter_function=None)

Joins pmappings into a full mappings for the entire workload. Pmappings can be generated using make_pmappings.

Parameters:

• pmappings (MultiEinsumPmappings) – The pmappings to join.

• require_all_einsums (bool) – If True, all einsums in the workload must have pmappings. If False, only einsums that have pmappings will be included in the final mappings.

• _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:

A Mappings object containing all valid, optimal mappings for the workload.

Return type:

Mappings

accelforge.mapper.FFM.main.make_pmappings(spec, einsum_names=None, can_combine_multiple_runs=False, cache_dir=None, print_number_of_pmappings=True)

Creates pmappings for a spec. Pmappings must be joined together using join_pmappings to create a full mapping.

Parameters:

• spec (Spec) – The Spec to generate pmappings for.

• einsum_names (list[str] | None) – The einsum names to generate pmappings for. If None, all einsums will be included.

• can_combine_multiple_runs (bool) – If True, allows combining multiple make_pmappings runs (e.g. pmappings = make_pmappings(*args_a) | make_pmappings(*args_b)). Set to False for faster execution.

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

• Returns – A MultiEinsumPmappings object.

Return type:

MultiEinsumPmappings

accelforge.mapper.FFM.main.map_workload_to_arch(spec, einsum_names=None, can_combine_multiple_runs=False, cache_dir=None, print_number_of_pmappings=True, _pmapping_row_filter_function=None)

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

Parameters:

• spec (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 (bool) – If True, allows combining multiple make_pmappings runs (e.g. pmappings = make_pmappings(*args_a) | make_pmappings(*args_b)). Set to False for faster execution.

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

Return type:

Mappings

accelforge.mapper.FFM.mappings module

class accelforge.mapper.FFM.mappings.Mappings

Bases: object

A collection of mappings and their evaluation results, generated by join_pmappings().

Variables:

• spec – The specification used to generate the mappings.

• einsum_names – The names of the Einsums in these mappings.

• data – A DataFrame containing the mappings and their evaluation results. Column names in the dataframe are are string separated by “<SEP>”, such as “Total<SEP>energy”.

• total_mappings – The total number of mappings that have been explored in order to get the mappings in the dataframe, equal to the full mapspace size.

• valid_mappings – The number of valid mappings that have been explored in order to get the mappings in the dataframe, equal to the valid mapspace size.

• flattened_arches – A dictionary of (EinsumName, Compute Name) to lists of architecture nodes. These contain the evaluated and flattened architecture node for that particular Einsum and compute combination.

• evaluated_specs – A dictionary of Einsum names to evaluated specifications. These contain the evaluated specification for that particular Einsum.

__init__(spec, einsum_names, data, total_mappings, valid_mappings, flattened_arches, evaluated_specs)

access(*keys, col_idx=None)

Returns a new Mappings object with only the columns that contain the given keys. Column names are strings separated by “<SEP>”, and this method will return columns with one <SEP>-separated string matching the given key. Then, for all remaining columns, the key will be removed.

For example, if the columns are “Compute<SEP>Energy”, and “DRAM<SEP>Energy”, and “DRAM<SEP>Latency”, then access(“Energy”) will return a Mappings object with columns “Compute” and “DRAM”, and access(“DRAM”) will return a Mappings object with columns “Compute” and “Latency”.

If multiple keys are given, then the procedure is repeated for each key.

col_idx:

The index of the key in the column name. This can be used if the given key is found at multiple indexes in different columns.

Parameters:

keys (str) – The keys to access from the columns.

Returns:

A new Mappings object with only the given keys.

Return type:

Mappings

property columns: list[str]

The columns of the dataframe.

drop(*keys)

Returns a new Mappings object with the given keys dropped from all columns. Column names are strings separated by “<SEP>”, and this method will will drop columns with one <SEP>-separated string matching the given key. Then, for all remaining columns, the key will be removed.

For example, if the columns are “Compute<SEP>Energy”, and “DRAM<SEP>Energy”, and “DRAM<SEP>Latency”, then drop(“Energy”) will drop “Compute<SEP>Energy” and “DRAM<SEP>Energy”, and drop(“DRAM”) will drop “DRAM<SEP>Energy” and “DRAM<SEP>Latency”.

If multiple keys are given, then the procedure is repeated for each key.

Parameters:

keys (str) – The keys to drop from the columns.

Returns:

A new Mappings object with the given keys dropped from all columns.

Return type:

Mappings

drop_zeros()

Returns a new Mappings object with all columns that have only zeros dropped.

Return type:

Mappings

energy(per_einsum=False, per_component=False, per_tensor=False, per_action=False, value_if_one_mapping=True)

Returns the energy consumed. A dictionary is returned with keys that are tuples of (Einsum name, Component name, Tensor name, Action name), with any of these being omitted if the corresponding parameter is not set to True. If neither of the per_ parameters are set to True, a float or a list of floats is returned.

NOTE: Leak power is not per-tensor. If per_tensor is True, then the tensor name for leak will be None.

Parameters:

• per_einsum (bool) – If True, then the energy will reported per-Einsum.

• per_component (bool) – If True, then the energy will reported per-component.

• per_tensor (bool) – If True, then the energy will reported per-tensor.

• per_action (bool) – If True, then the energy will reported per-action.

• value_if_one_mapping (bool) – If True and there is only one mapping, then values in the returned dictionary will be a single value, rather than a list of values. Otherwise, they will always be a list of values.

Returns:

A dictionary with the energy consumed for each Einsum, Component, Tensor, and Action. Keys are tuples of (Einsum name, Component name, Tensor name, Action name), with any of these being omitted if the corresponding parameter is not set to True. If none of the per_ parameters are set to True, a float or a list of floats is returned.

Return type:

dict[tuple[str, …], float | list[float]] | float | list[float]

latency(per_einsum=False, per_component=False, value_if_one_mapping=True)

Returns the latency consumed. A dictionary is returned with keys that are tuples of (Einsum name, Component name), with either being omitted if the corresponding parameter is not set to True. If neither of the per_ parameters are set to True, a float or a list of floats is returned.

NOTE: If per-Einsum is False and per-component is True, then the latency of each component will be summed across all Einsums. THE TOTAL LATENCY MAY BE GREATER THAN THE MAX OF THE PER-COMPONENT LATENCIES. This is because different components can be the bottleneck for different Einsums.

Parameters:

• per_einsum (bool) – If True, then the latency will reported per-Einsum.

• per_component (bool) – If True, then the latency will reported per-component.

• value_if_one_mapping (bool) – If True and there is only one mapping, then values in the returned dictionary will be a single value, rather than a list of values. Otherwise, they will always be a list of values.

Returns:

A dictionary with the latency for each Einsum+Component pair. Keys are tuples of (Einsum name, Component name), with either being omitted if the corresponding parameter is not set to True. If neither of the per_ parameters are set to True, a float or a list of floats is returned.

Return type:

dict[tuple[str, …], float | list[float]] | float | list[float]

num_computes(einsum_name=None)

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

Return type:

int

per_compute(per_einsum=False)

Returns the per-compute evaluation results by dividing all statistics by the number of computes.

Parameters:

per_einsum (bool) – If True, then for each Einsum, statistics will be divided only by the number of computes for that Einsum. This makes it clear to see per-compute stats for each Einsum, but note that total energy/compute will not be a direct sum of the per-compute stats then (and the same for latency and other statistics).

Returns:

A new Mappings object with the per-compute evaluation results.

Return type:

Mappings

per_tensor_size(return_n_elements=False)

Returns a dictionary of: {Tensor name: Number of bits} for each tensor in the spec. If return_n_elements is true, then the number of elements is returned instead of the number of bits.

Parameters:

return_n_elements (bool) – If True, then the number of elements is returned instead of the number of bits.

Returns:

A dictionary of: {Tensor name: Number of bits} for each tensor in the spec.

Return type:

dict[TensorName, int]

render(index=None)

Renders the mapping as a Pydot graph. Returns an SVG string. This is only supported if there is a single mapping; if there are multiple mappings, then either index into this Mappings object first, or pass in an index.

Parameters:

index (int | None) – The index of the mapping to render. If None and there are multiple mappings, then an error is raised.

Returns:

An SVG string of the mapping.

Return type:

str

Raises:

ValueError – If there are multiple mappings and no index is provided.

sum(keep_key_index=None)

Return type:

Mappings

to_dict(value_if_one_mapping=True)

Returns the data in this Mappings object as a dictionary. Each column in the this Mappings’ data becomes a key in the dictionary. Values in the dictionary may be a single value if there is only one mapping, or a list of values if there are multiple mappings.

Parameters:

value_if_one_mapping (bool) – If True and there is only one mapping, then values in the returned dictionary will be a single value, rather than a list of values. Otherwise, they will always be a list of values.

Returns:

A dictionary with the same keys as the columns of the dataframe, and values that are either a single value or a list of values.

Return type:

dict[str, list[float]]

accelforge.mapper.FFM.pmappings module

class accelforge.mapper.FFM.pmappings.MultiEinsumPmappings

Bases: object

A collection of pmappings for each Einsum in a workload, generated by make_pmappings().

Parameters:

• einsum2pmappings (dict[str, list[PmappingGroup]]) – A dictionary of Einsum names to lists of PmappingGroups. PmappingGroups contain the Pareto-optimal pmappings for the Einsum.

• pmapping_objects (dict[str, dict[UUID, Mapping]]) – A dictionary of Einsum names to dictionaries of UUIDs to Mappings. The entries in the PmappingGroup objects reference these pmapping objects.

• einsum2jobs (dict[str, list[Job]]) – A dictionary of Einsum names to lists of Jobs that generated the pmappings.

• can_combine_multiple_runs (bool) – Whether the pmappings can be combined from multiple runs. If this is True, then multiple make_pmappings calls can be summed together to get a single MultiEinsumPmappings object. If this is True, the mapper may run more slowly.

• einsums_with_pmappings_generated (set[str]) – Einsums for which pmappings were generated (or attempted to be generated).

• flattened_arches (dict[str, list[Leaf]]) – A dictionary of (EinsumName, Compute Name) to lists of architecture nodes. These contain the evaluated and flattened architecture node for that particular Einsum and compute combination.

• evaluated_specs (dict[str, Spec]) – A dictionary of Einsum names to evaluated specifications. These contain the evaluated specification for that particular Einsum.

__init__(spec, einsum2pmappings, pmapping_objects, einsum2jobs, can_combine_multiple_runs, einsums_with_pmappings_generated, flattened_arches, evaluated_specs)

drop_einsums(*einsums_with_pmappings_generated)

Removes all pmappings for the given Einsums.

Parameters:

einsums_with_pmappings_generated (str) – The Einsums for which to remove pmappings.

n_evaluated_pmappings(per_einsum=False)

Returns the number of pmappings that were evaluated for each Einsum. This is greater than the number of Pareto-optimal pmappings because some mappings are found to be suboptimal after they have been evaluated.

Parameters:

per_einsum (bool) – If True, returns a dictionary of evaluated pmappings for each Einsum.

Returns:

The number of evaluated pmappings in the mapspace.

Return type:

int | dict[EinsumName, int]

n_pareto_optimal_pmappings(per_einsum=False)

Returns the number of Pareto-optimal pmappings for each Einsum. This is the number of mappings that will be returned by the make_pmappings function.

Parameters:

per_einsum (bool) – If True, returns a dictionary of Pareto-optimal pmappings for each Einsum.

Returns:

The number of Pareto-optimal pmappings in the mapspace.

Return type:

int | dict[EinsumName, int]

n_pmapping_string()

Returns a string representation of the number of pmappings in the mapspace. Printing this can help diagnose if the mapper is not finding any pmappings or mappings.

Returns:

A string representation of the number of pmappings in the mapspace.

Return type:

str

n_total_pmappings(per_einsum=False)

Returns the number of total pmappings in the mapspace.

Parameters:

per_einsum (bool) – If True, returns a dictionary of total pmappings for each Einsum.

Returns:

The number of total pmappings in the mapspace.

Return type:

int | dict[EinsumName, int]

n_valid_pmappings(per_einsum=False)

Returns the number of valid pmappings for each Einsum. A valid pmapping is one that satisfies all constraints and resource usage limits.

Parameters:

per_einsum (bool) – If True, returns a dictionary of valid pmappings for each Einsum.

Returns:

The number of valid pmappings in the mapspace.

Return type:

int | dict[EinsumName, int]

pmapping_keep_rates(per_einsum=False)

Returns the keep rates for each cause of pmapping removal. For example, if only 25% of the pmappings have a valid spatial fanout, then the keep rate for the spatial fanout cause will be 0.25.

Parameters:

per_einsum (bool) – If True, returns a dictionary of keep rates for each Einsum.

Returns:

A dictionary of keep rates for each cause of pmapping removal.

Return type:

dict[EinsumName, dict[str, float]] | dict[str, float]

Module contents

class accelforge.mapper.FFM.Mappings

Bases: object

A collection of mappings and their evaluation results, generated by join_pmappings().

Variables:

• spec – The specification used to generate the mappings.

• einsum_names – The names of the Einsums in these mappings.

• data – A DataFrame containing the mappings and their evaluation results. Column names in the dataframe are are string separated by “<SEP>”, such as “Total<SEP>energy”.

• total_mappings – The total number of mappings that have been explored in order to get the mappings in the dataframe, equal to the full mapspace size.

• valid_mappings – The number of valid mappings that have been explored in order to get the mappings in the dataframe, equal to the valid mapspace size.

• flattened_arches – A dictionary of (EinsumName, Compute Name) to lists of architecture nodes. These contain the evaluated and flattened architecture node for that particular Einsum and compute combination.

• evaluated_specs – A dictionary of Einsum names to evaluated specifications. These contain the evaluated specification for that particular Einsum.

__init__(spec, einsum_names, data, total_mappings, valid_mappings, flattened_arches, evaluated_specs)

access(*keys, col_idx=None)

Returns a new Mappings object with only the columns that contain the given keys. Column names are strings separated by “<SEP>”, and this method will return columns with one <SEP>-separated string matching the given key. Then, for all remaining columns, the key will be removed.

For example, if the columns are “Compute<SEP>Energy”, and “DRAM<SEP>Energy”, and “DRAM<SEP>Latency”, then access(“Energy”) will return a Mappings object with columns “Compute” and “DRAM”, and access(“DRAM”) will return a Mappings object with columns “Compute” and “Latency”.

If multiple keys are given, then the procedure is repeated for each key.

col_idx:

The index of the key in the column name. This can be used if the given key is found at multiple indexes in different columns.

Parameters:

keys (str) – The keys to access from the columns.

Returns:

A new Mappings object with only the given keys.

Return type:

Mappings

property columns: list[str]

The columns of the dataframe.

drop(*keys)

Returns a new Mappings object with the given keys dropped from all columns. Column names are strings separated by “<SEP>”, and this method will will drop columns with one <SEP>-separated string matching the given key. Then, for all remaining columns, the key will be removed.

For example, if the columns are “Compute<SEP>Energy”, and “DRAM<SEP>Energy”, and “DRAM<SEP>Latency”, then drop(“Energy”) will drop “Compute<SEP>Energy” and “DRAM<SEP>Energy”, and drop(“DRAM”) will drop “DRAM<SEP>Energy” and “DRAM<SEP>Latency”.

If multiple keys are given, then the procedure is repeated for each key.

Parameters:

keys (str) – The keys to drop from the columns.

Returns:

A new Mappings object with the given keys dropped from all columns.

Return type:

Mappings

drop_zeros()

Returns a new Mappings object with all columns that have only zeros dropped.

Return type:

Mappings

energy(per_einsum=False, per_component=False, per_tensor=False, per_action=False, value_if_one_mapping=True)

Returns the energy consumed. A dictionary is returned with keys that are tuples of (Einsum name, Component name, Tensor name, Action name), with any of these being omitted if the corresponding parameter is not set to True. If neither of the per_ parameters are set to True, a float or a list of floats is returned.

NOTE: Leak power is not per-tensor. If per_tensor is True, then the tensor name for leak will be None.

Parameters:

• per_einsum (bool) – If True, then the energy will reported per-Einsum.

• per_component (bool) – If True, then the energy will reported per-component.

• per_tensor (bool) – If True, then the energy will reported per-tensor.

• per_action (bool) – If True, then the energy will reported per-action.

• value_if_one_mapping (bool) – If True and there is only one mapping, then values in the returned dictionary will be a single value, rather than a list of values. Otherwise, they will always be a list of values.

Returns:

A dictionary with the energy consumed for each Einsum, Component, Tensor, and Action. Keys are tuples of (Einsum name, Component name, Tensor name, Action name), with any of these being omitted if the corresponding parameter is not set to True. If none of the per_ parameters are set to True, a float or a list of floats is returned.

Return type:

dict[tuple[str, …], float | list[float]] | float | list[float]

latency(per_einsum=False, per_component=False, value_if_one_mapping=True)

Returns the latency consumed. A dictionary is returned with keys that are tuples of (Einsum name, Component name), with either being omitted if the corresponding parameter is not set to True. If neither of the per_ parameters are set to True, a float or a list of floats is returned.

NOTE: If per-Einsum is False and per-component is True, then the latency of each component will be summed across all Einsums. THE TOTAL LATENCY MAY BE GREATER THAN THE MAX OF THE PER-COMPONENT LATENCIES. This is because different components can be the bottleneck for different Einsums.

Parameters:

• per_einsum (bool) – If True, then the latency will reported per-Einsum.

• per_component (bool) – If True, then the latency will reported per-component.

• value_if_one_mapping (bool) – If True and there is only one mapping, then values in the returned dictionary will be a single value, rather than a list of values. Otherwise, they will always be a list of values.

Returns:

A dictionary with the latency for each Einsum+Component pair. Keys are tuples of (Einsum name, Component name), with either being omitted if the corresponding parameter is not set to True. If neither of the per_ parameters are set to True, a float or a list of floats is returned.

Return type:

dict[tuple[str, …], float | list[float]] | float | list[float]

num_computes(einsum_name=None)

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

Return type:

int

per_compute(per_einsum=False)

Returns the per-compute evaluation results by dividing all statistics by the number of computes.

Parameters:

per_einsum (bool) – If True, then for each Einsum, statistics will be divided only by the number of computes for that Einsum. This makes it clear to see per-compute stats for each Einsum, but note that total energy/compute will not be a direct sum of the per-compute stats then (and the same for latency and other statistics).

Returns:

A new Mappings object with the per-compute evaluation results.

Return type:

Mappings

per_tensor_size(return_n_elements=False)

Returns a dictionary of: {Tensor name: Number of bits} for each tensor in the spec. If return_n_elements is true, then the number of elements is returned instead of the number of bits.

Parameters:

return_n_elements (bool) – If True, then the number of elements is returned instead of the number of bits.

Returns:

A dictionary of: {Tensor name: Number of bits} for each tensor in the spec.

Return type:

dict[TensorName, int]

render(index=None)

Renders the mapping as a Pydot graph. Returns an SVG string. This is only supported if there is a single mapping; if there are multiple mappings, then either index into this Mappings object first, or pass in an index.

Parameters:

index (int | None) – The index of the mapping to render. If None and there are multiple mappings, then an error is raised.

Returns:

An SVG string of the mapping.

Return type:

str

Raises:

ValueError – If there are multiple mappings and no index is provided.

sum(keep_key_index=None)

Return type:

Mappings

to_dict(value_if_one_mapping=True)

Returns the data in this Mappings object as a dictionary. Each column in the this Mappings’ data becomes a key in the dictionary. Values in the dictionary may be a single value if there is only one mapping, or a list of values if there are multiple mappings.

Parameters:

value_if_one_mapping (bool) – If True and there is only one mapping, then values in the returned dictionary will be a single value, rather than a list of values. Otherwise, they will always be a list of values.

Returns:

A dictionary with the same keys as the columns of the dataframe, and values that are either a single value or a list of values.

Return type:

dict[str, list[float]]

class accelforge.mapper.FFM.Metrics

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

class accelforge.mapper.FFM.MultiEinsumPmappings

Bases: object

A collection of pmappings for each Einsum in a workload, generated by make_pmappings().

Parameters:

• einsum2pmappings (dict[str, list[PmappingGroup]]) – A dictionary of Einsum names to lists of PmappingGroups. PmappingGroups contain the Pareto-optimal pmappings for the Einsum.

• pmapping_objects (dict[str, dict[UUID, Mapping]]) – A dictionary of Einsum names to dictionaries of UUIDs to Mappings. The entries in the PmappingGroup objects reference these pmapping objects.

• einsum2jobs (dict[str, list[Job]]) – A dictionary of Einsum names to lists of Jobs that generated the pmappings.

• can_combine_multiple_runs (bool) – Whether the pmappings can be combined from multiple runs. If this is True, then multiple make_pmappings calls can be summed together to get a single MultiEinsumPmappings object. If this is True, the mapper may run more slowly.

• einsums_with_pmappings_generated (set[str]) – Einsums for which pmappings were generated (or attempted to be generated).

• flattened_arches (dict[str, list[Leaf]]) – A dictionary of (EinsumName, Compute Name) to lists of architecture nodes. These contain the evaluated and flattened architecture node for that particular Einsum and compute combination.

• evaluated_specs (dict[str, Spec]) – A dictionary of Einsum names to evaluated specifications. These contain the evaluated specification for that particular Einsum.

__init__(spec, einsum2pmappings, pmapping_objects, einsum2jobs, can_combine_multiple_runs, einsums_with_pmappings_generated, flattened_arches, evaluated_specs)

drop_einsums(*einsums_with_pmappings_generated)

Removes all pmappings for the given Einsums.

Parameters:

einsums_with_pmappings_generated (str) – The Einsums for which to remove pmappings.

n_evaluated_pmappings(per_einsum=False)

Returns the number of pmappings that were evaluated for each Einsum. This is greater than the number of Pareto-optimal pmappings because some mappings are found to be suboptimal after they have been evaluated.

Parameters:

per_einsum (bool) – If True, returns a dictionary of evaluated pmappings for each Einsum.

Returns:

The number of evaluated pmappings in the mapspace.

Return type:

int | dict[EinsumName, int]

n_pareto_optimal_pmappings(per_einsum=False)

Returns the number of Pareto-optimal pmappings for each Einsum. This is the number of mappings that will be returned by the make_pmappings function.

Parameters:

per_einsum (bool) – If True, returns a dictionary of Pareto-optimal pmappings for each Einsum.

Returns:

The number of Pareto-optimal pmappings in the mapspace.

Return type:

int | dict[EinsumName, int]

n_pmapping_string()

Returns a string representation of the number of pmappings in the mapspace. Printing this can help diagnose if the mapper is not finding any pmappings or mappings.

Returns:

A string representation of the number of pmappings in the mapspace.

Return type:

str

n_total_pmappings(per_einsum=False)

Returns the number of total pmappings in the mapspace.

Parameters:

per_einsum (bool) – If True, returns a dictionary of total pmappings for each Einsum.

Returns:

The number of total pmappings in the mapspace.

Return type:

int | dict[EinsumName, int]

n_valid_pmappings(per_einsum=False)

Returns the number of valid pmappings for each Einsum. A valid pmapping is one that satisfies all constraints and resource usage limits.

Parameters:

per_einsum (bool) – If True, returns a dictionary of valid pmappings for each Einsum.

Returns:

The number of valid pmappings in the mapspace.

Return type:

int | dict[EinsumName, int]

pmapping_keep_rates(per_einsum=False)

Returns the keep rates for each cause of pmapping removal. For example, if only 25% of the pmappings have a valid spatial fanout, then the keep rate for the spatial fanout cause will be 0.25.

Parameters:

per_einsum (bool) – If True, returns a dictionary of keep rates for each Einsum.

Returns:

A dictionary of keep rates for each cause of pmapping removal.

Return type:

dict[EinsumName, dict[str, float]] | dict[str, float]

class accelforge.mapper.FFM.PmappingGroup

Bases: object

__init__(compatibility, mappings)

static combine_combineable(pmapping_groups, live_tensors, allow_different_compatibilies=False, combine_reservations=True, pbar_postfix='')

Return type:

list[PmappingGroup]

compatibility_str()

static concat(pmapping_groups, allow_different_compatibilies=False)

Return type:

PmappingGroup

copy()

Return type:

PmappingGroup

static filter_by_tensors(pmapping_groups, tensors)

Return type:

list[PmappingGroup]

get_shared_loop_index(live_tensors)

Return type:

int

static group(pmapping_groups, live_tensors)

Return type:

dict[tuple[Compatibility, ...], list[tuple[PmappingGroup, list[int]]]]

static left_consolidate(pmapping_groups, live_tensors, pbar=None, parallelize=True)

Return type:

list[PmappingGroup]

merge_next(right, live_tensors, live_tensors_with_right, aliased_tensors, compatibility_joined, ignored_resources, drop_valid_reservations=True, delay=False, _pmapping_row_filter_function=None)

Return type:

PmappingGroup

static remove_dead_tensors(pmapping_groups, live_tensors)

rename_compatibility(new_c)

Return type:

Compatibility

static right_consolidate(pmapping_groups, live_tensors, shared_tensors=None, pbar=None, parallelize=True)

Return type:

list[PmappingGroup]

property tensor_names: set[str]

accelforge.mapper.FFM.join_pmappings(pmappings, require_all_einsums=True, _pmapping_row_filter_function=None)

Joins pmappings into a full mappings for the entire workload. Pmappings can be generated using make_pmappings.

Parameters:

• pmappings (MultiEinsumPmappings) – The pmappings to join.

• require_all_einsums (bool) – If True, all einsums in the workload must have pmappings. If False, only einsums that have pmappings will be included in the final mappings.

• _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:

A Mappings object containing all valid, optimal mappings for the workload.

Return type:

Mappings

accelforge.mapper.FFM.make_pmappings(spec, einsum_names=None, can_combine_multiple_runs=False, cache_dir=None, print_number_of_pmappings=True)

Creates pmappings for a spec. Pmappings must be joined together using join_pmappings to create a full mapping.

Parameters:

• spec (Spec) – The Spec to generate pmappings for.

• einsum_names (list[str] | None) – The einsum names to generate pmappings for. If None, all einsums will be included.

• can_combine_multiple_runs (bool) – If True, allows combining multiple make_pmappings runs (e.g. pmappings = make_pmappings(*args_a) | make_pmappings(*args_b)). Set to False for faster execution.

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

• Returns – A MultiEinsumPmappings object.

Return type:

MultiEinsumPmappings

accelforge.mapper.FFM.map_workload_to_arch(spec, einsum_names=None, can_combine_multiple_runs=False, cache_dir=None, print_number_of_pmappings=True, _pmapping_row_filter_function=None)

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

Parameters:

• spec (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 (bool) – If True, allows combining multiple make_pmappings runs (e.g. pmappings = make_pmappings(*args_a) | make_pmappings(*args_b)). Set to False for faster execution.

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

Return type:

Mappings