Making Models
This document follows the 2_making_models.ipynb tutorial.
Basic Components
Models can be created by subclassing the EnergyAreaModel
class. Models estimate the energy, area, and leakage power of a component. Each model
requires the following:
component_name: The name of the component. This may also be a list of components if multiple aliases are used.priority_0_to_100: The percent accuracy of the model. This is used to break ties if multiple models support a given query.A call to
super().__init__(area, leak_power, subcomponents). This is used to initialize the model and set the area and leakage power.
Models can also have actions. Actions are functions that return an energy of a specific
action. For the TernaryMAC model, we have an action called mac that returns the
energy of a ternary MAC operation. The
actionDynamicEnergy() decorator makes this function visible
as an action. The function should return an energy in Joules.
Models can also be scaled to support a range of different parameters. For example,
the TernaryMAC model can be scaled to support a range of different technology nodes.
This is done by calling the self.scale function in the __init__ method of the
model. The self.scale function takes the following arguments:
parameter_name: The name of the parameter to scale.parameter_value: The value of the parameter to scale.reference_value: The reference value of the parameter.area_scaling_function: The scaling function to use for area. UseNoneif no scaling should be done.energy_scaling_function: The scaling function to use for dynamic energy. UseNoneif no scaling should be done.leak_scaling_function: The scaling function to use for leakage power. UseNoneif no scaling should be done.
Many different scaling functions are defined and available in
hwcomponents.scaling.
from hwcomponents import EnergyAreaModel, actionDynamicEnergy
from hwcomponents.scaling import tech_node_area, tech_node_energy, tech_node_leak
class TernaryMAC(EnergyAreaModel):
"""
A ternary MAC unit, which multiplies two ternary values and accumulates the result.
Parameters
----------
accum_datawidth : int
The width of the accumulator in bits.
tech_node : int
The technology node in meters.
Attributes
----------
accum_datawidth : int
The width of the accumulator in bits.
tech_node : int
The technology node in meters.
"""
component_name: str | list[str] = 'TernaryMAC'
""" Name of the component. Must be a string or list/tuple of strings. """
priority = 0.8
"""
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.
"""
def __init__(self, accum_datawidth: int, tech_node: int):
# Provide an area and leakage power for the component. All units are in
# standard units without any prefixes (Joules, Watts, meters, etc.).
super().__init__(
area=5e-12 * accum_datawidth,
leak_power=1e-3 * accum_datawidth
)
# The following scales the tech_node to the given tech_node node from 40nm.
# The scaling functions for area, energy, and leakage are defined in
# hwcomponents.scaling. The energy scalingw will affect the functions decorated
# with @actionDynamicEnergy.
self.tech_node = self.scale(
"tech_node",
tech_node,
40e-9,
tech_node_area,
tech_node_energy,
tech_node_leak,
)
self.accum_datawidth = accum_datawidth
# Raising an error says that this model can't estimate and other models instead
# should be used instead. Good error messages are essential for users debugging
# their designs.
assert 4 <= accum_datawidth <= 8, \
f'Accumulation datawidth {accum_datawidth} outside supported ' \
f'range [4, 8]!'
# The actionDynamicEnergy decorator makes this function visible as an action. The
# function should return an energy in Joules.
@actionDynamicEnergy
def mac(self, clock_gated: bool = False) -> float:
"""
Returns the energy to perform a ternary MAC operation.
Parameters
----------
clock_gated : bool
Whether the MAC is clock gated during this operation.
Returns
-------
float
The energy to perform a ternary MAC operation in Joules.
"""
self.logger.info(f'TernaryMAC Model is estimating '
f'energy for mac_random.')
if clock_gated:
return 0.0
return 0.002e-12 * (self.accum_datawidth + 0.25)
mac = TernaryMAC(accum_datawidth=8, tech_node=16e-9) # Scale the TernaryMAC to 16nm
print(f'TernaryMAC energy is {mac.mac():.2e}J. Area is {mac.area:.2e}m^2. Leak power is {mac.leak_power:.2e}W')
Scaling by Number of Bits
Some actions may depend on the number of bits being accessesed. For example, you may
want to charge for the energy per bit of a DRAM read. To do this, you can use the
bits_per_action argument of the actionDynamicEnergy()
decorator. This decorator takes a string that is the name of the parameter to scale by.
For example, we can scale the energy of a DRAM read by the number of bits being read. In
this example, the DRAM yields width bits per read, so energy is scaled by
bits_per_action / width.
class LPDDR4(EnergyAreaModel):
"""
LPDDR4 DRAM energy model.
"""
component_name = ["DRAM", "dram"]
priority = 0.8
def __init__(self):
super().__init__(area=100e-3, leak_power=1e-3)
self.width = 1
# If read() is called with a different bits_per_action, the energy will be scaled
# by the number of bits.
@actionDynamicEnergy(bits_per_action="width")
def read(self) -> float:
"""
Returns the energy to read data from the DRAM.
Parameters
----------
bits_per_action : int
The number of bits to read.
Returns
-------
float
The energy to read the data in Joules.
"""
return 8e-12
lpddr4 = LPDDR4()
print(f"Read energy for one bit: {lpddr4.read(bits_per_action=1)}")
print(f"Read energy for fifty bits: {lpddr4.read(bits_per_action=50)}")
Compound Models
We can create compound models by combining multiple component models. Here, we’ll show
the SmartBufferSRAM model from the hwcomponents-library package.This is an SRAM
with an address generator that sequentially reads addresses in the SRAM.
We’ll use the following components:
A SRAM buffer
Two registers: one that that holds the current address, and one that holds the increment value
An adder that adds the increment value to the current address
One new functionality is used here. The subcomponents argument to the
EnergyAreaModel constructor is used to register
subcomponents.
The area, energy, and leak power of subcomponents will NOT be scaled by the component’s
energy_scale, area_scale, or leak_scale; if you want to scale the
subcomponents, multiply their energy_scale, area_scale, or leak_scale by the
desired scale factor.
from hwcomponents_cacti import SRAM
from hwcomponents_library import AladdinAdder, AladdinRegister
from hwcomponents import EnergyAreaModel, actionDynamicEnergy
import math
class SmartBufferSRAM(EnergyAreaModel):
"""
An SRAM with an address generator that sequentially reads addresses in the SRAM.
Parameters
----------
tech_node: The technology node in meters.
width: The width of the read and write ports in bits. This is the number of bits
that are accssed by any one read/write. Total size = width * depth.
depth: The number of entries in the SRAM, each with `width` bits. Total size =
width * depth.
n_rw_ports: The number of read/write ports. Bandwidth will increase with more
ports.
n_banks: The number of banks. Bandwidth will increase with more banks.
Attributes
----------
sram: The SRAM buffer.
address_reg: The register that holds the current address.
delta_reg: The register that holds the increment value.
adder: The adder that adds the increment value to the current address.
"""
component_name = ["smart_buffer_sram", "smartbuffer_sram", "smartbuffersram"]
priority = 0.5
def __init__(
self,
tech_node: float,
width: int,
depth: int,
n_rw_ports: int=1,
n_banks: int=1,
):
self.sram: SRAM = SRAM(
tech_node=tech_node,
width=width,
depth=depth,
n_rw_ports=n_rw_ports,
n_banks=n_banks,
)
self.address_bits = max(math.ceil(math.log2(depth)), 1)
self.width = width
self.address_reg = AladdinRegister(width=self.address_bits, tech_node=tech_node)
self.delta_reg = AladdinRegister(width=self.address_bits, tech_node=tech_node)
self.adder = AladdinAdder(width=self.address_bits, tech_node=tech_node)
# If there are subcomponents, we can omit the leakage power and area in the
# super constructor. If we pass them, their values will be added to the total.
super().__init__(subcomponents=[
self.sram,
self.address_reg,
self.delta_reg,
self.adder,
])
@actionDynamicEnergy(bits_per_action="width")
def read(self) -> float:
"""
Returns the energy consumed by a read operation in Joules.
Parameters
----------
bits_per_action: int
The number of bits to read.
Returns
-------
float
The energy consumed by a read operation in Joules.
"""
# Can omit the return value if there are subcomponents; return value is assumed
# to be sum of subcomponents. Return something to add it to the sum.
self.sram.read(bits_per_action=self.width)
self.address_reg.read()
self.delta_reg.read()
self.adder.add()
@actionDynamicEnergy(bits_per_action="width")
def write(self) -> float:
"""
Returns the energy consumed by a write operation in Joules.
Parameters
----------
bits_per_action: int
The number of bits to write.
Returns
-------
float
The energy consumed by a write operation in Joules.
"""
# Can omit the return value if there are subcomponents; return value is assumed
# to be sum of subcomponents. Return something to add it to the sum.
self.sram.write(bits_per_action=self.width)
self.address_reg.write()
self.delta_reg.read()
self.adder.add()
smartbuffer_sram = SmartBufferSRAM(
tech_node=16e-9,
width=32,
depth=1024,
n_rw_ports=1,
n_banks=1,
)
print(f'Read energy: {smartbuffer_sram.read(bits_per_action=32)} J')
print(f'Write energy: {smartbuffer_sram.write(bits_per_action=32)} J')
print(f'Area: {smartbuffer_sram.area} m^2')
print(f'Leak power: {smartbuffer_sram.leak_power} W')
Installing Models and Making them Globally Visible
An example model is provided in the notebooks/model_example directory, which can be
installed with the following command:
cd notebooks/model_example
pip3 install .
The README.md file in the notebooks/model_example directory contains information
on how to make models installable. Keep the following in mind while you’re changing the
model:
The model name should be prefixed with
hwcomponents_. This allows HWComponents to find the model when it is installed.The
__init__.pyfile should import all Model classes that you’d like to be visible to HWComponents.If you’re iterating on an model, you can use the
pip3 install -e .command to install the model in editable mode. This allows you to make changes to the model without having to reinstall it.