Finding and Using Models

This document follows the 1_finding_and_using_models.ipynb tutorial.

hwcomponents supports many different component models. We can list available component models with the get_models() function. This function returns a list of ComponentModel subclasses.

You may also use the hwcomponents --list command from the shell.

import hwcomponents as hwc

# Find and list all installed component models
print(f"Listing component models")
all_installed_models = hwc.get_models()
print(f"Number of available component models: {len(all_installed_models)}")
for model in all_installed_models[:5]:
    print(f"{model.__name__} supports {model.component_name}")

If we know what type of component we would like to model, we can use the name_must_include argument to get_models() to find all models that match a given class name.

For example, we can use the hwcomponents_cacti package to model an SRAM. Once we’ve found the model, we can use the help function to see its documentation and supported actions.


# Find an SRAM model
print(f"\nListing SRAM models")
sram_models = hwc.get_models(name_must_include="sram")
print(f"Number of SRAM models: {len(sram_models)}")
for model in sram_models[:5]:
    print(f"{model.__name__} supports {model.component_name}")

# Grab the CACI SRAM model & use the "help" function to see its documentation
models = [s for s in sram_models if "hwcomponents_cacti" in s.__module__]
assert (
    len(models) == 1
), f"Excected 1 CACTI SRAM model, got {len(models)}. Is hwcomponents_cacti installed?"
sram = models[0]
help(sram)

Once we know the model we’d like to use, we can import the model directly and instantiate components.


# Now that we have a component model, we can use it to create components.
from hwcomponents_cacti.hwcomponents_cacti import SRAM

# Create an SRAM component using the CACTI model
sram = SRAM(
    tech_node=16e-9,
    width=1024,
    depth=256,
    size=1024 * 256,
)
r = sram.read(bits_per_action=8)
w = sram.write(bits_per_action=8)
print(f"SRAM read: energy {r.energy:.2e} J, throughput {r.throughput:.2e} actions/s")
print(f"SRAM write: energy {w.energy:.2e} J, throughput {w.throughput:.2e} actions/s")
print(f"SRAM area: {sram.area} m^2")
print(f"SRAM leak power: {sram.leak_power} W")

If you’re unsure of which component model you’d like to use, there are other ways to invoke a model. There are three ways to find a component model:

  1. Import the model from a module and use it directly.

  2. Ask hwcomponents to select the best model for a given component. hwcomponents will select the best model for a given component name and attributes, and raise an error if no model can be instantiated with the given attributes.

  3. Ask for specific properties from hwcomponents. This is similar to the second method, but you can ask for the area, energy, latency, or leak power of an action of a component directly.


# Method 1: Import the model from a module and use it directly.
from hwcomponents_cacti import SRAM

sram = SRAM(
    tech_node=40e-9,  # 40nm
    width=64,
    depth=1024,
    size=64 * 1024,
)
cost = sram.read()
print(
    f"SRAM read energy {cost.energy:.2e} J, throughput {cost.throughput:.2e} actions/s"
)
print(f"SRAM area is {sram.area:.2e}m^2. Leak power is {sram.leak_power:.2e}W")


# Method 2: Ask hwcomponents to select the best model for a given component.
model = hwc.get_model(
    component_name="SRAM",  # These are NOT case sensitive.
    component_attributes={
        "tech_node": 40e-9,
        "width": 64,
        "depth": 1024,
        "size": 64 * 1024,
    },
    required_actions=["read"],
)
cost = model.read()
print(f"Read energy {cost.energy:.2e} J, throughput {cost.throughput:.2e} actions/s")
print(f"Area is {model.area:.2e}m^2. Leak power is {model.leak_power:.2e}W")

# Method 3: Ask for the action cost directly from hwcomponents.
attributes = {
    "tech_node": 40e-9,
    "width": 64,
    "depth": 1024,
    "size": 64 * 1024,
}

cost = hwc.get_action_cost(
    component_name="SRAM",
    component_attributes=attributes,
    action_name="read",
    action_arguments={},
)
area = hwc.get_area(
    component_name="SRAM",
    component_attributes=attributes,
)
leak_power = hwc.get_leak_power(
    component_name="SRAM",
    component_attributes=attributes,
)
print(f"Read energy {cost.energy:.2e} J, throughput {cost.throughput:.2e} actions/s")
print(f"Area is {area:.2e}m^2. Leak power is {leak_power:.2e}W")

How the Best Model is Chosen

When several models support a query, hwcomponents tries them in order and uses the first one that returns successfully. If a model raises an error, the next one is tried. The order is determined by the following, in this order:

  1. priority, higher first. Defaults to 0.5.

  2. The number of provided action arguments that the action accepts, more first (only when an action is queried).

  3. The number of provided attributes that the init function accepts, more first.

  4. The number of the action’s defaulted arguments not provided by the query, fewer first (only when an action is queried).

  5. The number of the init function’s defaulted arguments not provided by the query, fewer first.

  6. The fully-qualified class name (module and qualified name), lower-alphabetically first.

In short, the highest-priority model wins, and ties are broken in favor of the model that most closely matches the query. See get_model() for the API.