hwcomponents package

Submodules

hwcomponents.find_models module

hwcomponents.find_models.get_models(*paths_or_packages_or_models, include_installed=True, name_must_include='', _return_wrappers=False)[source]

Instantiate a list of model objects for later queries. Searches for models in the given paths and packages.

Parameters:

paths_or_packages_or_models (Union[str, List[str], List[List[str]], ComponentModel]) – A list of paths or packages to search for models.
include_installed (bool) – Whether to include models from installed packages.
name_must_include (str) – If provided, a model will only be returned if its name includes this string. Non-case-sensitive.
_return_wrappers (bool) – Whether to return ComponentModelWrapper objects or ComponentModel objects.

Return type:

Union[List[ComponentModelWrapper], List[ComponentModel]]

Returns:

A list of ComponentModelWrapper objects or ComponentModel objects.

hwcomponents.find_models.get_models_in_module(module, model_ids, _return_wrappers=False)[source]

Finds all ComponentModel subclasses in a module and returns them as ComponentModelWrapper objects. Ignores underscore-prefixed classes.

Parameters:

model_ids (Set) – A set of model IDs to avoid duplicates.
_return_wrappers (bool) – Whether to return ComponentModelWrapper objects or ComponentModel objects.

Return type:

Union[List[ComponentModelWrapper], List[ComponentModel]]

Returns:

A list of ComponentModelWrapper objects.

hwcomponents.find_models.installed_models(_return_wrappers=False)[source]

Lists all Python packages installed that are prefixed with “hwcomponents_”. Finds ComponentModel subclasses in these packages and returns them as ComponentModel or ComponentModelWrapper objects.

Parameters:: _return_wrappers (bool) – Whether to return ComponentModelWrapper objects or ComponentModel objects.
Return type:: Union[List[ComponentModelWrapper], List[ComponentModel]]
Returns:: A list of ComponentModel or ComponentModelWrapper objects.

hwcomponents.hwcomponents module

hwcomponents.hwcomponents.list_components(printfunc=print)[source]

Lists all available components.

Parameters:: printfunc (Callable[[str], None]) – The function to use to print the components.
Returns:: None

hwcomponents.model module

class hwcomponents.model.ActionCost[source]

Bases: object

The cost of an action, returned by @action functions.

Parameters:

energy (float) – The energy of the action in Joules.
latency (float) – The latency of the action in seconds.
throughput (float) – The throughput of the action in actions/second.

__init__(energy, latency, throughput)[source]

class hwcomponents.model.ComponentModel[source]

Bases: ListLoggable, ABC

ComponentModel base class. ComponentModel class must have “name” attribute, “priority” attribute, and “get_area” method. ComponentModels may have any number of methods that are decorated with @action.

Parameters:

component_name (str | list[str] | None) – The name of the component. Must be a string or list/tuple of strings. Can be omitted if the component name is the same as the class name.
priority (float) – The priority of the model. Higher priority models are used first. Must be a number between 0 and 1. Defaults to 0.5.
leak_power (float | None) – The leakage power of the component in Watts. Must be set if subcomponents is not set.
area (float | None) – The area of the component in m^2. Must be set if subcomponents is not set.
subcomponents (list[ComponentModel] | None) – A list of subcomponents. If set, the area and leak power of the subcomponents will be added to the area and leak power of the component. All calls to @action functions will be added to the cost of the component if they occur during one of the component’s actions.

Variables:

component_name (The name of the component. Must be a string or list/tuple of) – strings. Can be omitted if the component name is the same as the class name.
priority (The priority of the model. Higher priority models are used first.) – Must be a number between 0 and 1. Defaults to 0.5.
energy_scale – A scale factor for the energy of this component. The energy of all calls to actions will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT ENERGY.
area_scale – A scale factor for the area of this component. All accesses to area will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT AREA.
throughput_scale – A scale factor for the throughput of this component. The throughput of all calls to @action will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT THROUGHPUT.
latency_scale – A scale factor for the latency of this component. The latency of all calls to @action will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT LATENCY.
leak_power_scale (A scale factor for the leakage power of this component. All) – accesses to leak_power will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT LEAK POWER.
subcomponents (A list of subcomponents. If set, the area and leak power of the) – subcomponents are added to the area and leak power of the component, and all calls to @action functions are added to the cost of the component if they occur during one of the component’s actions. The area, energy, leak power, and throughput of subcomponents WILL NOT BE scaled by the component’s energy_scale, area_scale, throughput_scale, or leak_power_scale; if you want to scale the subcomponents, use scale_area, scale_energy, scale_latency, scale_throughput, scale_leak_power, or scale with include_subcomponents=True or call scaling functions on the subcomponents directly.

abstractmethod __init__(leak_power=None, area=None, subcomponents=None)[source]

property area: Number

Returns the area in m^2 of the component.

Return type:: The area in m^2 of the component.

property area_scale: float: A scale factor for the area of this component. All accesses to area will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT AREA.

assert_int(name, value)[source]

Checks that the value is an integer, and if so, returns it as an integer. Otherwise, raises a ValueError.

Parameters:

name (str) – The name of the attribute to check. Used for error messages.
value (int | float | Any) – The value to check.

Return type:

int

Returns:

int: The value as an integer.

assert_match(value_a, value_b, name_a, name_b)[source]

Checks that the two values are equal, and if so, returns the matched value. If one value is None, returns the other value. Raise an error if the two values are not equal, or if both are None.

Parameters:

value_a (int | float | Any | None) – The first value to check.
value_b (int | float | Any | None) – The second value to check.
name_a (str) – The name of the first value. Used for error messages.
name_b (str) – The name of the second value. Used for error messages.

Return type:

int

Returns:

int: The matched value.

component_name: str | List[str] | None = None: Name of the component. Must be a string or list/tuple of strings. Can be omitted if the component name is the same as the class name.

property energy_scale: float: A scale factor for the energy of this component. The energy of all calls to actions will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT ENERGY.

classmethod get_action_names()[source]

Returns the names of the actions supported by the model.

Returns:: The names of the actions supported by the model.
Return type:: List[str]

get_log_messages()[source]

Returns the log messages for the component.

Return type:

List[str]

Returns:

List[str]: The log messages for the component.

property latency_scale: float: A scale factor for the latency of this component. The latency of all calls to @action will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT LATENCY.

property leak_power: Number

Returns the leakage power of the component in Watts.

Return type:: The leakage power in Watts.

property leak_power_scale: float: A scale factor for the leakage power of this component. All accesses to leak_power will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT LEAK POWER.

pop_log_messages()[source]

Pops the log messages for the component.

Return type:

List[str]

Returns:

List[str]: The log messages for the component.

priority: Number = 0.5: Priority determines which model is used when multiple models are available for a given component. Higher priority models are used first. Must be a number between 0 and 1. Defaults to 0.5. Ties in priority are broken by how closely each model matches the query; see get_model() for the full order.

required_arguments(action_name=None)[source]

Returns the required arguments for the given action. If no action is given, returns the required arguments for the __init__ method.

Parameters:

action_name (str | None) – The name of the action to get the required arguments for. If None, returns the required arguments for the __init__ method.

Return type:

List[str]

Returns:

list[str]: The required arguments for the given action.

resolve_multiple_ways_to_calculate_value(name, *args)[source]

Parses multiple possible ways to set an attribute, raising errors if the values are not consistent.

Each possible argument is a tuple containing a function and a dictionary of keyword arguments. A function fails if any keyword arguments are None, if the function raises an error, or if the function returns None.

The outputs of all non-failing functions are compared, and an error is raised if they are not equal.

Parameters:

name (str) – The name of the attribute to set.
*args (tuple[str, Callable[[Any], Any], dict[str, Any]]) – The possible ways to set the attribute. Each tuple contains a name, a function that takes the current value and returns the new value, and a dictionary of keyword arguments to pass to the function.

Return type:

Any

Returns:

The value of the attribute.

scale(key, target, default, area_scale_function=None, energy_scale_function=None, latency_scale_function=None, leak_power_scale_function=None, throughput_scale_function=None, include_subcomponents=True)[source]

Scales this model’s area, energy, latency, leak power, and throughput to the given target.

Parameters:

key (str) – The name of the parameter to scale. Used for logging.
target (float) – The target value of the parameter. The value is scaled to this from the default.
default (float) – The default value of the parameter. The value is scaled to the target from this.
area_scale_function (Optional[Callable[[float, float], float]]) – The function to use to scale the area. None if no scaling should be done.
energy_scale_function (Optional[Callable[[float, float], float]]) – The function to use to scale the energy. None if no scaling should be done.
latency_scale_function (Optional[Callable[[float, float], float]]) – The function to use to scale the latency. None if no scaling should be done.
leak_power_scale_function (Optional[Callable[[float, float], float]]) – The function to use to scale the leak power. None if no scaling should be done.
throughput_scale_function (Union[Callable[[float, float], float], tuple, None]) – The function (or tuple of composed functions) to use to scale the throughput. None if no scaling should be done.
include_subcomponents (bool) – Whether to also scale the subcomponents by the same factors. Defaults to True. When True, subcomponents are scaled as well.

Return type:

float

scale_area(scale, include_subcomponents=True)[source]

Multiplies this component’s area scale factor by scale. If include_subcomponents is True, then subcomponent area is scaled as well.

Parameters:

scale (float) – The factor by which to scale the area.
include_subcomponents (bool) – Whether to scale subcomponent area by the same factor. Finds all subcomponents recursively.

scale_energy(scale, include_subcomponents=True)[source]

Multiplies this component’s energy scale factor by scale. If include_subcomponents is True, then subcomponent energy is scaled as well.

Parameters:

scale (float) – The factor by which to scale the energy.
include_subcomponents (bool) – Whether to scale subcomponent energy by the same factor. Finds all subcomponents recursively.

scale_latency(scale, include_subcomponents=True)[source]

Multiplies this component’s latency scale factor by scale. If include_subcomponents is True, then subcomponent latency is scaled as well.

Parameters:

scale (float) – The factor by which to scale the latency.
include_subcomponents (bool) – Whether to scale subcomponent latency by the same factor. Finds all subcomponents recursively.

scale_leak_power(scale, include_subcomponents=True)[source]

Multiplies this component’s leak power scale factor by scale. If include_subcomponents is True, then subcomponent leak power is scaled as well.

Parameters:

scale (float) – The factor by which to scale the leak power.
include_subcomponents (bool) – Whether to scale subcomponent leak power by the same factor. Finds all subcomponents recursively.

scale_tech_node(target, default)[source]

Scales the tech node of the component to the given target.

Parameters:

target (float) – The target tech node.
default (float) – The default tech node.

Return type:

float

Returns:

The scaled tech node.

scale_throughput(scale, include_subcomponents=True)[source]

Multiplies this component’s throughput scale factor by scale. If include_subcomponents is True, then subcomponent throughput is scaled as well.

Parameters:

scale (float) – The factor by which to scale the throughput.
include_subcomponents (bool) – Whether to scale subcomponent throughput by the same factor. Finds all subcomponents recursively.

property throughput_scale: float: A scale factor for the throughput of this component. The throughput of all calls to @action will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT THROUGHPUT.

try_call_arbitrary_action(action_name, _return_estimation_object=False, **kwargs)[source]

Tries to call the given action with the given arguments.

Parameters:

action_name (str) – The name of the action to call.
**kwargs (dict) – The arguments with which to call the action.

Return type:

TypeVar(T, bound= ComponentModel)

classmethod try_init_arbitrary_args(_return_estimation_object=False, **kwargs)[source]

Tries to initialize the model with the given arguments.

Parameters:

**kwargs (dict) – The arguments with which to initialize the model.
_return_estimation_object (bool) – Whether to return the Estimation object instead of the model.

Return type:

TypeVar(T, bound= ComponentModel)

Returns:

The initialized model. If the model cannot be initialized with the given arguments, an exception is raised.

hwcomponents.model.action(func=None, bits_per_action=None)[source]

Decorator that adds an action to a model. If the component has no subcomponents, then the action is expected to return an ActionCost(energy, throughput, latency) where energy is in Joules, throughput is in actions/second, and latency is in seconds. If the component has subcomponents, then None return values are assumed to be zero cost, and subcomponent actions that occur during the component’s action will be added to the component’s cost.

Costs compose in the following ways for subcomponents:

Energy: Summed
Latency: Summed
Throughput: Minned

Parameters:

func (Callable[..., ActionCost]) – The function to decorate.
bits_per_action (str | Number) – The attribute of the model that contains the number of bits per action. If this is set and a bits_per_action is passed to the function, the energy will be scaled by the number of bits and the throughput will be scaled by its reciprocal. Latency is per-action and does NOT scale with bits_per_action. For example, if bits_per_action is set to “width”, the function is called with bits_per_action=10, and the model has a width attribute of 5, then the energy will be scaled by 2 and the throughput will be halved.

Return type:

Callable[..., ActionCost]

Returns:

The decorated function.

hwcomponents.select_models module

hwcomponents.select_models.get_action_cost(component_name, component_attributes, action_name, action_arguments, models=None, _return_estimation_object=False, _relaxed_component_name_selection=False)[source]

Finds the action cost using the best-matching model. A model is a candidate if its component name matches, all required attributes in component_attributes are provided, and it has a matching action with all required arguments in action_arguments provided. See get_model() for how the best model is chosen.

Parameters:

component_name (str)
component_attributes (Dict[str, Any])
action_name (str)
action_arguments (Dict[str, Any])
models (List[ComponentModelWrapper])
_return_estimation_object (bool) – the action cost value.
_relaxed_component_name_selection (bool) – selection. Relaxed selection ignores underscores in the component name.

Return type:

ActionCost | Estimation

Returns:

ActionCost: The cost of this action.

hwcomponents.select_models.get_area(component_name, component_attributes, models=None, _return_estimation_object=False, _relaxed_component_name_selection=False)[source]

Finds the area using the best-matching model. A model is a candidate if its component name matches and all required attributes in component_attributes are provided. See get_model() for how the best model is chosen.

Parameters:

component_name (str)
component_attributes (Dict[str, Any])
models (List[ComponentModelWrapper])
_return_estimation_object (bool) – the area value.
_relaxed_component_name_selection (bool) – selection. Relaxed selection ignores underscores in the component name.

Return type:

float | Estimation

Returns:

The area in m^2.

hwcomponents.select_models.get_leak_power(component_name, component_attributes, models=None, _return_estimation_object=False, _relaxed_component_name_selection=False)[source]

Finds the leak power using the best-matching model. A model is a candidate if its component name matches and all required attributes in component_attributes are provided. See get_model() for how the best candidate is chosen.

Parameters:

component_name (str)
component_attributes (Dict[str, Any])
models (List[ComponentModelWrapper])
_relaxed_component_name_selection (bool) – selection. Relaxed selection ignores underscores in the component name.

Return type:

float | Estimation

Returns:

The leak power in Watts.

hwcomponents.select_models.get_model(component_name, component_attributes, required_actions=(), models=None, _return_estimation_object=False, _relaxed_component_name_selection=False)[source]

Finds the best model for the given component. A model is a candidate if its component name matches, all required attributes in component_attributes are provided, and it has actions for all of required_actions.

The best-matching candidate is chosen by the following in descending order of importance:

priority, higher first (defaults to 0.5).
If an action is required, the number of provided action arguments that the action accepts, more first.
Number of provided attributes that the init function accepts, more first.
If an action is required, number of the action’s defaulted arguments not provided by the query, fewer first.
Number of the init function’s defaulted arguments not provided by the query, fewer first.
The fully-qualified class name (module and qualified name), lower-alphabetically first.

Parameters:

component_name (str)
component_attributes (Dict[str, Any])
required_actions (List[str])
models (List[ComponentModelWrapper])
_return_estimation_object (bool) – the model wrapper.
_relaxed_component_name_selection (bool) – selection. Relaxed selection ignores underscores in the component name.

Return type:

ComponentModelWrapper

Returns:

The best model wrapper.

Module contents

class hwcomponents.ActionCost[source]

Bases: object

The cost of an action, returned by @action functions.

Parameters:

energy (float) – The energy of the action in Joules.
latency (float) – The latency of the action in seconds.
throughput (float) – The throughput of the action in actions/second.

__init__(energy, latency, throughput)[source]

class hwcomponents.ComponentModel[source]

Bases: ListLoggable, ABC

ComponentModel base class. ComponentModel class must have “name” attribute, “priority” attribute, and “get_area” method. ComponentModels may have any number of methods that are decorated with @action.

Parameters:

component_name (str | list[str] | None) – The name of the component. Must be a string or list/tuple of strings. Can be omitted if the component name is the same as the class name.
priority (float) – The priority of the model. Higher priority models are used first. Must be a number between 0 and 1. Defaults to 0.5.
leak_power (float | None) – The leakage power of the component in Watts. Must be set if subcomponents is not set.
area (float | None) – The area of the component in m^2. Must be set if subcomponents is not set.
subcomponents (list[ComponentModel] | None) – A list of subcomponents. If set, the area and leak power of the subcomponents will be added to the area and leak power of the component. All calls to @action functions will be added to the cost of the component if they occur during one of the component’s actions.

Variables:

component_name (The name of the component. Must be a string or list/tuple of) – strings. Can be omitted if the component name is the same as the class name.
priority (The priority of the model. Higher priority models are used first.) – Must be a number between 0 and 1. Defaults to 0.5.
energy_scale – A scale factor for the energy of this component. The energy of all calls to actions will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT ENERGY.
area_scale – A scale factor for the area of this component. All accesses to area will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT AREA.
throughput_scale – A scale factor for the throughput of this component. The throughput of all calls to @action will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT THROUGHPUT.
latency_scale – A scale factor for the latency of this component. The latency of all calls to @action will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT LATENCY.
leak_power_scale (A scale factor for the leakage power of this component. All) – accesses to leak_power will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT LEAK POWER.
subcomponents (A list of subcomponents. If set, the area and leak power of the) – subcomponents are added to the area and leak power of the component, and all calls to @action functions are added to the cost of the component if they occur during one of the component’s actions. The area, energy, leak power, and throughput of subcomponents WILL NOT BE scaled by the component’s energy_scale, area_scale, throughput_scale, or leak_power_scale; if you want to scale the subcomponents, use scale_area, scale_energy, scale_latency, scale_throughput, scale_leak_power, or scale with include_subcomponents=True or call scaling functions on the subcomponents directly.

abstractmethod __init__(leak_power=None, area=None, subcomponents=None)[source]

property area: Number

Returns the area in m^2 of the component.

Return type:: The area in m^2 of the component.

property area_scale: float: A scale factor for the area of this component. All accesses to area will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT AREA.

assert_int(name, value)[source]

Checks that the value is an integer, and if so, returns it as an integer. Otherwise, raises a ValueError.

Parameters:

name (str) – The name of the attribute to check. Used for error messages.
value (int | float | Any) – The value to check.

Return type:

int

Returns:

int: The value as an integer.

assert_match(value_a, value_b, name_a, name_b)[source]

Checks that the two values are equal, and if so, returns the matched value. If one value is None, returns the other value. Raise an error if the two values are not equal, or if both are None.

Parameters:

value_a (int | float | Any | None) – The first value to check.
value_b (int | float | Any | None) – The second value to check.
name_a (str) – The name of the first value. Used for error messages.
name_b (str) – The name of the second value. Used for error messages.

Return type:

int

Returns:

int: The matched value.

component_name: str | List[str] | None = None: Name of the component. Must be a string or list/tuple of strings. Can be omitted if the component name is the same as the class name.

property energy_scale: float: A scale factor for the energy of this component. The energy of all calls to actions will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT ENERGY.

classmethod get_action_names()[source]

Returns the names of the actions supported by the model.

Returns:: The names of the actions supported by the model.
Return type:: List[str]

get_log_messages()[source]

Returns the log messages for the component.

Return type:

List[str]

Returns:

List[str]: The log messages for the component.

property latency_scale: float: A scale factor for the latency of this component. The latency of all calls to @action will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT LATENCY.

property leak_power: Number

Returns the leakage power of the component in Watts.

Return type:: The leakage power in Watts.

property leak_power_scale: float: A scale factor for the leakage power of this component. All accesses to leak_power will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT LEAK POWER.

pop_log_messages()[source]

Pops the log messages for the component.

Return type:

List[str]

Returns:

List[str]: The log messages for the component.

priority: Number = 0.5: Priority determines which model is used when multiple models are available for a given component. Higher priority models are used first. Must be a number between 0 and 1. Defaults to 0.5. Ties in priority are broken by how closely each model matches the query; see get_model() for the full order.

required_arguments(action_name=None)[source]

Returns the required arguments for the given action. If no action is given, returns the required arguments for the __init__ method.

Parameters:

action_name (str | None) – The name of the action to get the required arguments for. If None, returns the required arguments for the __init__ method.

Return type:

List[str]

Returns:

list[str]: The required arguments for the given action.

resolve_multiple_ways_to_calculate_value(name, *args)[source]

Parses multiple possible ways to set an attribute, raising errors if the values are not consistent.

Each possible argument is a tuple containing a function and a dictionary of keyword arguments. A function fails if any keyword arguments are None, if the function raises an error, or if the function returns None.

The outputs of all non-failing functions are compared, and an error is raised if they are not equal.

Parameters:

name (str) – The name of the attribute to set.
*args (tuple[str, Callable[[Any], Any], dict[str, Any]]) – The possible ways to set the attribute. Each tuple contains a name, a function that takes the current value and returns the new value, and a dictionary of keyword arguments to pass to the function.

Return type:

Any

Returns:

The value of the attribute.

scale(key, target, default, area_scale_function=None, energy_scale_function=None, latency_scale_function=None, leak_power_scale_function=None, throughput_scale_function=None, include_subcomponents=True)[source]

Scales this model’s area, energy, latency, leak power, and throughput to the given target.

Parameters:

key (str) – The name of the parameter to scale. Used for logging.
target (float) – The target value of the parameter. The value is scaled to this from the default.
default (float) – The default value of the parameter. The value is scaled to the target from this.
area_scale_function (Optional[Callable[[float, float], float]]) – The function to use to scale the area. None if no scaling should be done.
energy_scale_function (Optional[Callable[[float, float], float]]) – The function to use to scale the energy. None if no scaling should be done.
latency_scale_function (Optional[Callable[[float, float], float]]) – The function to use to scale the latency. None if no scaling should be done.
leak_power_scale_function (Optional[Callable[[float, float], float]]) – The function to use to scale the leak power. None if no scaling should be done.
throughput_scale_function (Union[Callable[[float, float], float], tuple, None]) – The function (or tuple of composed functions) to use to scale the throughput. None if no scaling should be done.
include_subcomponents (bool) – Whether to also scale the subcomponents by the same factors. Defaults to True. When True, subcomponents are scaled as well.

Return type:

float

scale_area(scale, include_subcomponents=True)[source]

Multiplies this component’s area scale factor by scale. If include_subcomponents is True, then subcomponent area is scaled as well.

Parameters:

scale (float) – The factor by which to scale the area.
include_subcomponents (bool) – Whether to scale subcomponent area by the same factor. Finds all subcomponents recursively.

scale_energy(scale, include_subcomponents=True)[source]

Multiplies this component’s energy scale factor by scale. If include_subcomponents is True, then subcomponent energy is scaled as well.

Parameters:

scale (float) – The factor by which to scale the energy.
include_subcomponents (bool) – Whether to scale subcomponent energy by the same factor. Finds all subcomponents recursively.

scale_latency(scale, include_subcomponents=True)[source]

Multiplies this component’s latency scale factor by scale. If include_subcomponents is True, then subcomponent latency is scaled as well.

Parameters:

scale (float) – The factor by which to scale the latency.
include_subcomponents (bool) – Whether to scale subcomponent latency by the same factor. Finds all subcomponents recursively.

scale_leak_power(scale, include_subcomponents=True)[source]

Multiplies this component’s leak power scale factor by scale. If include_subcomponents is True, then subcomponent leak power is scaled as well.

Parameters:

scale (float) – The factor by which to scale the leak power.
include_subcomponents (bool) – Whether to scale subcomponent leak power by the same factor. Finds all subcomponents recursively.

scale_tech_node(target, default)[source]

Scales the tech node of the component to the given target.

Parameters:

target (float) – The target tech node.
default (float) – The default tech node.

Return type:

float

Returns:

The scaled tech node.

scale_throughput(scale, include_subcomponents=True)[source]

Multiplies this component’s throughput scale factor by scale. If include_subcomponents is True, then subcomponent throughput is scaled as well.

Parameters:

scale (float) – The factor by which to scale the throughput.
include_subcomponents (bool) – Whether to scale subcomponent throughput by the same factor. Finds all subcomponents recursively.

subcomponents: list[ComponentModel]

property throughput_scale: float: A scale factor for the throughput of this component. The throughput of all calls to @action will be scaled by this factor. WILL NOT AFFECT SUBCOMPONENT THROUGHPUT.

try_call_arbitrary_action(action_name, _return_estimation_object=False, **kwargs)[source]

Tries to call the given action with the given arguments.

Parameters:

action_name (str) – The name of the action to call.
**kwargs (dict) – The arguments with which to call the action.

Return type:

TypeVar(T, bound= ComponentModel)

classmethod try_init_arbitrary_args(_return_estimation_object=False, **kwargs)[source]

Tries to initialize the model with the given arguments.

Parameters:

**kwargs (dict) – The arguments with which to initialize the model.
_return_estimation_object (bool) – Whether to return the Estimation object instead of the model.

Return type:

TypeVar(T, bound= ComponentModel)

Returns:

The initialized model. If the model cannot be initialized with the given arguments, an exception is raised.

hwcomponents.action(func=None, bits_per_action=None)[source]

Decorator that adds an action to a model. If the component has no subcomponents, then the action is expected to return an ActionCost(energy, throughput, latency) where energy is in Joules, throughput is in actions/second, and latency is in seconds. If the component has subcomponents, then None return values are assumed to be zero cost, and subcomponent actions that occur during the component’s action will be added to the component’s cost.

Costs compose in the following ways for subcomponents:

Energy: Summed
Latency: Summed
Throughput: Minned

Parameters:

func (Callable[..., ActionCost]) – The function to decorate.
bits_per_action (str | Number) – The attribute of the model that contains the number of bits per action. If this is set and a bits_per_action is passed to the function, the energy will be scaled by the number of bits and the throughput will be scaled by its reciprocal. Latency is per-action and does NOT scale with bits_per_action. For example, if bits_per_action is set to “width”, the function is called with bits_per_action=10, and the model has a width attribute of 5, then the energy will be scaled by 2 and the throughput will be halved.

Return type:

Callable[..., ActionCost]

Returns:

The decorated function.

hwcomponents.get_action_cost(component_name, component_attributes, action_name, action_arguments, models=None, _return_estimation_object=False, _relaxed_component_name_selection=False)[source]

Finds the action cost using the best-matching model. A model is a candidate if its component name matches, all required attributes in component_attributes are provided, and it has a matching action with all required arguments in action_arguments provided. See get_model() for how the best model is chosen.

Parameters:

component_name (str)
component_attributes (Dict[str, Any])
action_name (str)
action_arguments (Dict[str, Any])
models (List[ComponentModelWrapper])
_return_estimation_object (bool) – the action cost value.
_relaxed_component_name_selection (bool) – selection. Relaxed selection ignores underscores in the component name.

Return type:

ActionCost | Estimation

Returns:

ActionCost: The cost of this action.

hwcomponents.get_area(component_name, component_attributes, models=None, _return_estimation_object=False, _relaxed_component_name_selection=False)[source]

Finds the area using the best-matching model. A model is a candidate if its component name matches and all required attributes in component_attributes are provided. See get_model() for how the best model is chosen.

Parameters:

component_name (str)
component_attributes (Dict[str, Any])
models (List[ComponentModelWrapper])
_return_estimation_object (bool) – the area value.
_relaxed_component_name_selection (bool) – selection. Relaxed selection ignores underscores in the component name.

Return type:

float | Estimation

Returns:

The area in m^2.

hwcomponents.get_leak_power(component_name, component_attributes, models=None, _return_estimation_object=False, _relaxed_component_name_selection=False)[source]

Finds the leak power using the best-matching model. A model is a candidate if its component name matches and all required attributes in component_attributes are provided. See get_model() for how the best candidate is chosen.

Parameters:

component_name (str)
component_attributes (Dict[str, Any])
models (List[ComponentModelWrapper])
_relaxed_component_name_selection (bool) – selection. Relaxed selection ignores underscores in the component name.

Return type:

float | Estimation

Returns:

The leak power in Watts.

hwcomponents.get_model(component_name, component_attributes, required_actions=(), models=None, _return_estimation_object=False, _relaxed_component_name_selection=False)[source]

Finds the best model for the given component. A model is a candidate if its component name matches, all required attributes in component_attributes are provided, and it has actions for all of required_actions.

The best-matching candidate is chosen by the following in descending order of importance:

priority, higher first (defaults to 0.5).
If an action is required, the number of provided action arguments that the action accepts, more first.
Number of provided attributes that the init function accepts, more first.
If an action is required, number of the action’s defaulted arguments not provided by the query, fewer first.
Number of the init function’s defaulted arguments not provided by the query, fewer first.
The fully-qualified class name (module and qualified name), lower-alphabetically first.

Parameters:

component_name (str)
component_attributes (Dict[str, Any])
required_actions (List[str])
models (List[ComponentModelWrapper])
_return_estimation_object (bool) – the model wrapper.
_relaxed_component_name_selection (bool) – selection. Relaxed selection ignores underscores in the component name.

Return type:

ComponentModelWrapper

Returns:

The best model wrapper.

hwcomponents.get_models(*paths_or_packages_or_models, include_installed=True, name_must_include='', _return_wrappers=False)[source]

Instantiate a list of model objects for later queries. Searches for models in the given paths and packages.

Parameters:

paths_or_packages_or_models (Union[str, List[str], List[List[str]], ComponentModel]) – A list of paths or packages to search for models.
include_installed (bool) – Whether to include models from installed packages.
name_must_include (str) – If provided, a model will only be returned if its name includes this string. Non-case-sensitive.
_return_wrappers (bool) – Whether to return ComponentModelWrapper objects or ComponentModel objects.

Return type:

Union[List[ComponentModelWrapper], List[ComponentModel]]

Returns:

A list of ComponentModelWrapper objects or ComponentModel objects.

hwcomponents package

Subpackages

Submodules

hwcomponents.find_models module

hwcomponents.hwcomponents module

hwcomponents.model module

hwcomponents.select_models module

Module contents