Latency modeling

Author: tanner-andrulis

README.md

@@ -1,7 +1,7 @@
 # HWComponents
 The HWComponents (Hardware Components) package, part of the
 [CiMLoop](https://github.com/mit-emze/cimloop) project, provides an interface for the
-estimation of energy, area, and leakage power of hardware components in hardware
+estimation of area, energy, latency, and leak power of hardware components in hardware
 architectures. Key features in HWComponents include:
 
 [Information about the package is available on the hwcomponents website](https://accelergy-project.github.io/hwcomponents/).
@@ -11,7 +11,7 @@ architectures. Key features in HWComponents include:
 If you use this package in your work, please cite the CiMLoop project:
 
 ```bibtex
-@INPROCEEDINGS{10590023,
+@INPROCEEDINGS{cimloop,
   author={Andrulis, Tanner and Emer, Joel S. and Sze, Vivienne},
   booktitle={2024 IEEE International Symposium on Performance Analysis of Systems and Software (ISPASS)},
   title={CiMLoop: A Flexible, Accurate, and Fast Compute-In-Memory Modeling Tool},
@@ -22,15 +22,4 @@ If you use this package in your work, please cite the CiMLoop project:
   keywords={Performance evaluation;Accuracy;Computational modeling;Computer architecture;Artificial neural networks;In-memory computing;Data models;Compute-In-Memory;Processing-In-Memory;Analog;Deep Neural Networks;Systems;Hardware;Modeling;Open-Source},
   doi={10.1109/ISPASS61541.2024.00012}
 }
-@INPROCEEDINGS{8942149,
-  author={Wu, Yannan Nellie and Emer, Joel S. and Sze, Vivienne},
-  booktitle={2019 IEEE/ACM International Conference on Computer-Aided Design (ICCAD)},
-  title={Accelergy: An Architecture-Level Energy Estimation Methodology for Accelerator Designs},
-  year={2019},
-  volume={},
-  number={},
-  pages={1-8},
-  keywords={Program processors;Electric breakdown;Neural networks;Estimation;Hardware;Energy efficiency;Compounds},
-  doi={10.1109/ICCAD45719.2019.8942149}
-}
 ```

docs/source/index.rst

@@ -3,10 +3,10 @@ CiMLoop HWComponents
 
 The HWComponents (Hardware Components) package, part of the `CiMLoop
 <https://github.com/mit-emze/cimloop>`_ project, provides an interface for the
-estimation of energy, area, and leakage power of hardware components in hardware
-architectures. Key features in HWComponents include:
+estimation of area, energy, latency, and leak power of hardware components in
+hardware architectures. Key features in HWComponents include:
 
-- A simple Python API for writing energy, area, and leakage power models. New
+- A simple Python API for writing area, energy, latency, and leak power models. New
   models can be written in minutes.
 - Automatic scaling of parameters to different configurations, including scaling to
   different technology nodes.
@@ -15,9 +15,6 @@ architectures. Key features in HWComponents include:
 - Automatic gathering of components from available Python packages. This includes
   support for different models in virtual environments.
 
-Components are also compatible with
-`Accelergy <https://github.com/accelergy-project/accelergy>`_.
-
 
 Installation
 ------------
@@ -83,7 +80,7 @@ If you use this package in your work, please cite the CiMLoop project:
 
 .. code-block:: bibtex
 
-    @INPROCEEDINGS{10590023,
+    @INPROCEEDINGS{cimloop,
     author={Andrulis, Tanner and Emer, Joel S. and Sze, Vivienne},
     booktitle={2024 IEEE International Symposium on Performance Analysis of Systems and Software (ISPASS)},
     title={CiMLoop: A Flexible, Accurate, and Fast Compute-In-Memory Modeling Tool},
@@ -94,14 +91,3 @@ If you use this package in your work, please cite the CiMLoop project:
     keywords={Performance evaluation;Accuracy;Computational modeling;Computer architecture;Artificial neural networks;In-memory computing;Data models;Compute-In-Memory;Processing-In-Memory;Analog;Deep Neural Networks;Systems;Hardware;Modeling;Open-Source},
     doi={10.1109/ISPASS61541.2024.00012}
     }
-    @INPROCEEDINGS{8942149,
-    author={Wu, Yannan Nellie and Emer, Joel S. and Sze, Vivienne},
-    booktitle={2019 IEEE/ACM International Conference on Computer-Aided Design (ICCAD)},
-    title={Accelergy: An Architecture-Level Energy Estimation Methodology for Accelerator Designs},
-    year={2019},
-    volume={},
-    number={},
-    pages={1-8},
-    keywords={Program processors;Electric breakdown;Neural networks;Estimation;Hardware;Energy efficiency;Compounds},
-    doi={10.1109/ICCAD45719.2019.8942149}
-    }

docs/source/notes/finding_and_using_models.rst

@@ -5,7 +5,7 @@ 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 :py:func:`~hwcomponents.find_models.get_models` function. This
-function returns a list of :py:class:`~hwcomponents.model.EnergyAreaModel` subclasses.
+function returns a list of :py:class:`~hwcomponents.model.ComponentModel` subclasses.
 
 You may also use the ``hwcomponents --list`` command from the shell.
 
@@ -40,7 +40,8 @@ invoke a model. There are three ways to find a component model:
    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 energy, area, or leakage power of a component directly.
+   but you can ask for the area, energy, latency, or leak power of an action of a
+   component directly.
 
 .. include-notebook:: ../../notebooks/1_finding_and_using_models.ipynb
    :name: ways_to_find_components

docs/source/notes/making_models.rst

@@ -6,22 +6,21 @@ This document follows the ``2_making_models.ipynb`` tutorial.
 Basic Components
 ----------------
 
-Models can be created by subclassing the :py:class:`~hwcomponents.model.EnergyAreaModel`
+Models can be created by subclassing the :py:class:`~hwcomponents.model.ComponentModel`
 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.
+- ``priority``: 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
-:py:func:`~hwcomponents.model.actionDynamicEnergy` decorator makes this function visible
-as an action. The function should return an energy in Joules.
+Models can also have actions. Actions are functions that return a tuple of ``(energy,
+latency)`` for a specific action. For the TernaryMAC model, we have an action called
+``mac`` that returns the energy and latency of a ternary MAC operation. The
+:py:func:`~hwcomponents.model.action` decorator makes this function visible as an
+action. The function should return ``(energy_in_Joules, latency_in_seconds)``.
 
 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.
@@ -35,9 +34,14 @@ model. The ``self.scale`` function takes the following arguments:
   scaling should be done.
 - ``energy_scaling_function``: The scaling function to use for dynamic energy. Use
   ``None`` if no scaling should be done.
+- ``latency_scaling_function``: The scaling function to use for latency. Use ``None`` if
+  no scaling should be done.
 - ``leak_scaling_function``: The scaling function to use for leakage power. Use ``None``
   if no scaling should be done.
 
+**Note: Area, Energy, Latency, and Leak Power are always in alphabetical order in the
+function arguments.**
+
 Many different scaling functions are defined and available in
 :py:mod:`hwcomponents.scaling`.
 
@@ -49,12 +53,12 @@ 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 :py:func:`~hwcomponents.model.actionDynamicEnergy`
+want to charge for the energy and latency per bit of a DRAM read. To do this, you can
+use the ``bits_per_action`` argument of the :py:func:`~hwcomponents.model.action`
 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``.
+For example, we can scale the energy and latency of a DRAM read by the number of bits
+being read. In this example, the DRAM yields ``width`` bits per read, so energy and
+latency are scaled by ``bits_per_action / width``.
 
 .. include-notebook:: ../../notebooks/2_making_models.ipynb
    :name: scaling_by_number_of_bits
@@ -75,18 +79,24 @@ We'll use the following components:
 - An adder that adds the increment value to the current address
 
 One new functionality is used here. The ``subcomponents`` argument to the
-:py:class:`~hwcomponents.model.EnergyAreaModel` constructor is used to register
+:py:class:`~hwcomponents.model.ComponentModel` 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.
+The area, energy, latency, and leak power of subcomponents will NOT be scaled by the
+component's ``area_scale``, ``energy_scale``, ``latency_scale``, and ``leak_scale``; if
+you want to scale the subcomponents, multiply the subcomponents' ``area_scale``,
+``energy_scale``, ``latency_scale``, and ``leak_scale`` by the desired scale factor.
 
 .. include-notebook:: ../../notebooks/2_making_models.ipynb
    :name: smartbuffer_sram
    :language: python
 
+The latency of subcomponents is generally summed. However, if the subcomponents are
+pipelined for a given action, then the ``pipelined_subcomponents`` argument to the
+:py:func:`~hwcomponents.model.action` decorator should be set to True. This will cause
+the latency of the action to be the max of the latency returned and all subcomponent
+latencies.
+
 Installing Models and Making them Globally Visible
 --------------------------------------------------
 

hwcomponents/__init__.py

@@ -1,10 +1,10 @@
-from hwcomponents.model import EnergyAreaModel, actionDynamicEnergy
+from hwcomponents.model import ComponentModel, action
 from hwcomponents.find_models import get_models
-from hwcomponents.select_models import get_energy, get_area
 import hwcomponents.scaling as scaling
 from hwcomponents.select_models import (
     get_area,
     get_energy,
-    get_model,
+    get_latency,
     get_leak_power,
+    get_model,
 )