accelforge 0.0.1__py3-none-any.whl

notebooks/tutorials/_include.py

@@ -0,0 +1,48 @@
+import re
+
+def grab_from_yaml_file(
+    yaml_file: str,
+    startfrom: str | None = None,
+    same_indent: bool = True,
+    include_lines_before: int = 0,
+) -> str:
+    """
+    Grab a section from a YAML file.
+
+    Args:
+        yaml_file:
+            The path to the YAML file.
+        startfrom:
+            The string to start from. If None, return the entire file.
+        same_indent:
+            Whether to include lines with the same indentation as the startfrom line, or
+            only lines with >= indentation.
+        include_lines_before:
+            The number of lines to include before the startfrom line.
+
+    Returns:
+        The section of the YAML file as a string.
+    """
+    with open(yaml_file, "r") as f:
+        contents = f.readlines()
+    start, end = 0, len(contents)
+    n_whitespace = 0
+
+    if startfrom is not None:
+        for i, line in enumerate(contents):
+            if re.findall(r"\b\s*" + startfrom + r"\b", line):
+                start = i
+                n_whitespace = len(re.findall(r"^\s*", line)[0])
+                break
+        else:
+            raise ValueError(f"{startfrom} not found in {yaml_file}")
+        for i, line in enumerate(contents[start + 1 :]):
+            if not line.strip():
+                continue
+            ws = len(re.findall(r"^\s*", line)[0])
+            if ws < n_whitespace or (not same_indent and ws == n_whitespace):
+                end = start + i + 1
+                break
+
+    contents = [c[n_whitespace:] for c in contents[start - include_lines_before : end]]
+    return "".join(contents)

notebooks/tutorials/component_energy_area.ipynb

@@ -0,0 +1,363 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Modeling Component Area, Energy, Latency, and Leak Power\n",
+    "\n",
+    "This notebook shows how to integrate component models from the `hwcomponents` library to\n",
+    "model area, energy, latency, and leak power.\n",
+    "\n",
+    "Before reading this notebook, you should be familiar with the `hwcomponents` library.\n",
+    "Ensure you've installed it and been through all of the notebooks in the [hwcomponents\n",
+    "documentation](https://accelergy-project.github.io/hwcomponents/).\n",
+    "\n",
+    "We'll be using the `component_example.yaml` file, which is annotated explaining what\n",
+    "each attribute means."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from pathlib import Path\n",
+    "from IPython.display import Markdown\n",
+    "\n",
+    "examples_dir = Path(\"../../examples\")\n",
+    "\n",
+    "display(Markdown(f\"\"\"\n",
+    "```yaml\n",
+    "{open(examples_dir / \"misc\" / \"component_annotated.yaml\").read()}\n",
+    "```\n",
+    "\"\"\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we'll create a global buffer component and model its area, energy, latency, and leak\n",
+    "power."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# < DOC_INCLUDE_MARKER > single_component_energy_area\n",
+    "\n",
+    "# Create the component from the yaml file\n",
+    "import accelforge as af\n",
+    "global_buffer = af.arch.Memory.from_yaml(\n",
+    "    examples_dir / \"misc\" / \"component_annotated.yaml\"\n",
+    ")\n",
+    "\n",
+    "# Calculate the energy and area of the component\n",
+    "global_buffer = global_buffer.calculate_area_energy_latency_leak()\n",
+    "\n",
+    "# Print out the area, leak power, and energy for each action\n",
+    "area = global_buffer.attributes.area\n",
+    "leak_power = global_buffer.attributes.leak_power\n",
+    "print(f\"Area: {area:.2e} m^2\")\n",
+    "print(f\"Leak power: {leak_power:.2e} W\")\n",
+    "for action in global_buffer.actions:\n",
+    "    energy = action.arguments.energy\n",
+    "    latency = action.arguments.latency\n",
+    "    print(f'Action {action.name} energy {energy:.2e} J, latency {latency:.2e}s')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Calculating area, energy, latency, and leak power for a component fills out more\n",
+    "attributes as well! We can inspect what is available by looking at the __doc__ or by\n",
+    "looking at this project's documentation website."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "print(global_buffer.calculate_area_energy_latency_leak.__doc__)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "As we can see in the doc, this function also fills out the `component_modeling_log`\n",
+    "attribute of the component, which contains messages from the component modeling\n",
+    "calculations."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# < DOC_INCLUDE_MARKER > hwcomponents\n",
+    "for message in global_buffer.component_modeling_log:\n",
+    "    print(message)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To get more details on the specific model used, we can also look at the\n",
+    "`component_model` attribute of the component, which has the\n",
+    "`hwcomponents.ComponentModel` object that was used to calculate the energy and area. We\n",
+    "can use `help()` on this object to get more details on the model."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# < DOC_INCLUDE_MARKER > hwcomponents\n",
+    "component_model = global_buffer.component_model\n",
+    "print(help(component_model)) # Get documentation for the model"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can see that the global buffer is an instance of\n",
+    "`hwcomponents_library.SmartBufferSRAM`, and it contains four subcomponents: an SRAM\n",
+    "buffer, an address register, a delta register, and an addder. We can look at each of\n",
+    "these components to see the area breakdown of our buffer."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# < DOC_INCLUDE_MARKER > hwcomponents\n",
+    "\n",
+    "# The model is a hwcomponents_library.SmartBufferSRAM object!\n",
+    "from hwcomponents_library import SmartBufferSRAM\n",
+    "\n",
+    "# Type hint it for our IDE\n",
+    "component_model: SmartBufferSRAM = global_buffer.component_model\n",
+    "\n",
+    "# Inspect the area of each of its subcomponents\n",
+    "print(f'Area: {component_model.area:.2e} m^2')\n",
+    "print(f'\\tSRAM area: {component_model.sram.area:.2e} m^2')\n",
+    "print(f'\\tAdder area: {component_model.adder.area:.2e} m^2')\n",
+    "print(f'\\tAddress register area: {component_model.address_reg.area:.2e} m^2')\n",
+    "print(f'\\tDelta reg area: {component_model.delta_reg.area:.2e} m^2')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now we'll model the components for a larger design using the `eyeriss_like`\n",
+    "architecture."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "display(Markdown(f\"\"\"\n",
+    "```yaml\n",
+    "{open(examples_dir / \"arches\" / \"eyeriss_like.arch.yaml\").read()}\n",
+    "```\n",
+    "\"\"\"))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The top-level specification object has a `calculate_area_energy_latency_leak` method\n",
+    "that can be used to calculate the area, energy, latency, and leak power of all\n",
+    "components in the design. Additionally, when called from the top-level specification,\n",
+    "this method parses expressions in the architecture, letting you express attributes as\n",
+    "functions of other attributes."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# < DOC_INCLUDE_MARKER > spec_energy_area\n",
+    "\n",
+    "# Load the spec and calculate the energy and area of the entire design\n",
+    "spec = af.Spec.from_yaml(examples_dir / \"arches\" / \"eyeriss_like.arch.yaml\")\n",
+    "spec = spec.calculate_component_area_energy_latency_leak()\n",
+    "\n",
+    "# Print out the total area and leakage power of the entire design\n",
+    "print(f'Total area of the design: {spec.arch.total_area:.2e} m^2')\n",
+    "print(f'Area breakdown per component:')\n",
+    "for component, area in spec.arch.per_component_total_area.items():\n",
+    "    print(f'\\t{component}: {area:.2e} m^2')\n",
+    "print(f'Total leakage power of the design: {spec.arch.total_leak_power:.2e} W')\n",
+    "for component, leak_power in spec.arch.per_component_total_leak_power.items():\n",
+    "    print(f'\\t{component}: {leak_power:.2e} W')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Once the area, energy, latency, and leak power of the architecture are calculated, we can\n",
+    "look at any individual component and analyze it like we analyzed the global buffer."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "mac = spec.arch.find(\"MAC\")\n",
+    "print(f'MAC area: {mac.attributes.area:.2e} m^2')\n",
+    "print(f'Total area of all MACs in the architecture: {mac.attributes.total_area:.2e} m^2')\n",
+    "print(f'MAC leak power: {mac.attributes.leak_power:.2e} W')\n",
+    "print(f'Total leak power of all MACs in the architecture: {mac.attributes.total_leak_power:.2e} W')\n",
+    "for action in mac.actions:\n",
+    "    energy = action.arguments.energy\n",
+    "    latency = action.arguments.latency\n",
+    "    print(f'{action.name} energy: {energy:.2e} J, latency {latency:.2e}s')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can also force the design to use a specific model for a component by passing in our\n",
+    "own `ComponentModel` object. Here we'll create a custom MAC model that has lower\n",
+    "leakage power than the default model.\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# Create a hwcomponents model. See the hwcomponents tutorial for ore information on how\n",
+    "# to make these!\n",
+    "import hwcomponents as hwc\n",
+    "\n",
+    "class MyMac(hwc.ComponentModel):\n",
+    "    component_name: str = \"intmac\"\n",
+    "    priority: float = 0.5\n",
+    "\n",
+    "    def __init__(self):\n",
+    "        super().__init__(\n",
+    "            area=5e-8,\n",
+    "            leak_power=1e-12 # Very low leakage power\n",
+    "        )\n",
+    "\n",
+    "    @hwc.action\n",
+    "    def compute(self) -> float:\n",
+    "        self.logger.info(f'*** Getting compute energy ***')\n",
+    "        # 1pJ, 1ns\n",
+    "        return 1e-12, 1e-9\n",
+    "\n",
+    "# Initialize the spec and make the MAC use our custom model\n",
+    "spec = af.Spec.from_yaml(examples_dir / \"arches\" / \"eyeriss_like.arch.yaml\")\n",
+    "mac = spec.arch.find(\"MAC\")\n",
+    "mac.component_model = MyMac()\n",
+    "\n",
+    "# Calculate the energy and area of the MAC and print out the results\n",
+    "mac = mac.calculate_area_energy_latency_leak()\n",
+    "print(f'MAC area: {mac.attributes.area:.2e} m^2')\n",
+    "print(f'MAC leak power: {mac.attributes.leak_power:.2e} W')\n",
+    "for action in mac.actions:\n",
+    "    energy = action.arguments.energy\n",
+    "    latency = action.arguments.latency\n",
+    "    print(f'{action.name} energy: {energy:.2e} J, latency {latency:.2e}s')\n",
+    "\n",
+    "# The energy and area log contain logs from the ComponentModel component.\n",
+    "print(f\"Log messages: \")\n",
+    "for message in mac.component_modeling_log:\n",
+    "    print(f\"\\t{message}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The `hwcomponents` library has plenty of other component models to use! These can be\n",
+    "listed with the `hwcomponents.get_models` function.\n",
+    "\n",
+    "If you're interested in a specific model, use the `help()` function to get more\n",
+    "information on it.\n",
+    "\n",
+    "For more information, see the [hwcomponents\n",
+    "documentation](https://accelergy-project.github.io/hwcomponents/)."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import hwcomponents as hwc\n",
+    "\n",
+    "for model in hwc.get_models()[:5]:\n",
+    "    print(f\"{model} supports {model.component_name}\")\n",
+    "    for action in model.get_action_names():\n",
+    "        print(f'\\t{action}')\n",
+    "\n",
+    "\n",
+    "from hwcomponents_adc import ADC\n",
+    "help(ADC)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.12.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 2
+}

tests/Q_mapping.yaml

@@ -0,0 +1,38 @@
+  # d=4, all others = 2
+  # - name: Q
+  #   tensor_accesses:
+  #   - {name: I, projection: [ b, m, d ]}
+  #   - {name: WQ, projection: [ h, e, d ]}
+  #   - {name: Q, projection: [ b, m, h, e ], output: True}
+
+mapping:
+  nodes:
+  - !Storage
+    tensors: [I, WQ, Q]
+    component: MainMemory
+  - !Temporal
+    rank_variable: b
+    tile_shape: 1
+  - !Temporal
+    rank_variable: h
+    tile_shape: 1
+  - !Temporal
+    rank_variable: e
+    tile_shape: 1
+  - !Spatial
+    rank_variable: d
+    tile_shape: 1
+    name: 0
+    component: LocalBuffer
+  - !Storage
+    tensors: [Q]
+    component: LocalBuffer
+  - !Temporal
+    rank_variable: m
+    tile_shape: 1
+  - !Storage
+    tensors: [I]
+    component: LocalBuffer
+  - !Compute
+    einsum: Q
+    compute: MAC

tests/conv.mapping.yaml

@@ -0,0 +1,27 @@
+mapping:
+  nodes:
+  - !Storage
+    tensors: [I, W, O]
+    component: MainMemory
+  - !Temporal
+    rank_variable: c
+    tile_shape: 1
+  - !Spatial
+    rank_variable: r
+    tile_shape: 1
+    name: 0
+    component: LocalBuffer
+  - !Spatial
+    rank_variable: m
+    tile_shape: 1
+    name: 0
+    component: LocalBuffer
+  - !Storage
+    tensors: [I]
+    component: LocalBuffer
+  - !Temporal
+    rank_variable: p
+    tile_shape: 1
+  - !Compute
+    einsum: conv
+    compute: MAC

tests/conv.workload.yaml

@@ -0,0 +1,13 @@
+workload:
+  shape:
+    p: 0 <= p < 5
+    r: 0 <= r < 3
+    m: 0 <= m < 4
+    c: 0 <= c < 2
+
+  einsums:
+  - name: conv
+    tensor_accesses:
+    - {name: I, projection: { C: c, H: p+r }}
+    - {name: W, projection: [ m, c, r ]}
+    - {name: O, projection: [ m, p ], output: True}

tests/conv_sym.mapping.yaml

@@ -0,0 +1,43 @@
+mapping:
+  nodes:
+  - !Storage
+    tensors: [I, W, O]
+    component: MainMemory
+  - !Temporal
+    rank_variable: c
+    tile_shape: symbol
+  - !Spatial
+    rank_variable: r
+    tile_shape: symbol
+    name: X
+    component: LocalBuffer
+  - !Spatial
+    rank_variable: m
+    tile_shape: symbol
+    name: X
+    component: LocalBuffer
+  - !Storage
+    tensors: [I]
+    component: LocalBuffer
+  - !Temporal
+    rank_variable: m
+    tile_shape: symbol
+  - !Temporal
+    rank_variable: p
+    tile_shape: symbol
+  - !Temporal
+    rank_variable: p
+    tile_shape: symbol
+  - !Temporal
+    rank_variable: p
+    tile_shape: 4
+    assume_perfect_factor: false
+  - !Temporal
+    rank_variable: p
+    tile_shape: symbol
+  - !Temporal
+    rank_variable: p
+    tile_shape: symbol
+  - !Compute
+    einsum: conv
+    compute: MAC

tests/copy.mapping.yaml

@@ -0,0 +1,35 @@
+# I: Moves from local buffer to register
+# O1: Stays in local buffer
+# O2: Moves from local buffer to global buffer
+# O3: Moves from global buffer to main memory
+# O4: Moves from local buffer to register
+
+mapping:
+  nodes:
+  - !Storage
+    tensors: [O3]
+    component: Disk
+  - !Storage
+    tensors: [O3]
+    component: MainMemory
+  - !Temporal
+    rank_variable: a
+    tile_shape: 1
+  - !Storage
+    tensors: []
+    component: GlobalBuffer
+  - !Temporal
+    rank_variable: b
+    tile_shape: 1
+  - !Storage
+    tensors: [I, O1]
+    component: LocalBuffer
+  - !Temporal
+    rank_variable: c
+    tile_shape: 1
+  - !Storage
+    tensors: [O4]
+    component: Register
+  - !Compute
+    einsum: copy
+    compute: MAC

tests/copy.workload.yaml

@@ -0,0 +1,15 @@
+workload:
+  shape:
+    a: 0 <= a < 2
+    b: 0 <= b < 2
+    c: 0 <= c < 2
+
+  einsums:
+  - name: copy
+    is_copy_operation: True
+    tensor_accesses:
+    - {name: I, projection: [ a, b, c ]}
+    - {name: O1, projection: [ a, b, c ], output: True}
+    - {name: O2, projection: [ a, b, c ], output: True}
+    - {name: O3, projection: [ a, b, c ], output: True}
+    - {name: O4, projection: [ a, b, c ], output: True}