accelforge 0.0.1__py3-none-any.whl

docs/source/conf.py

@@ -0,0 +1,79 @@
+import os
+import sys
+sys.path.insert(0, os.path.abspath('_ext'))
+sys.path.insert(0, os.path.abspath('../..'))  # Make your repo importable
+
+import locale
+locale.setlocale(locale.LC_ALL, 'C.UTF-8')
+
+# -- Project information -----------------------------------------------------
+project = 'accelforge'
+author = 'Tanner Andrulis, Michael Gilbert'
+release = '0.1.0'
+
+# -- HTML output -------------------------------------------------------------
+html_theme = 'sphinx_rtd_theme'
+# html_theme = 'furo'
+# html_theme = 'pydata_sphinx_theme'
+# pip3 install sphinx-furo-theme
+
+extensions = [
+    'sphinx.ext.autodoc',            # Pull docstrings
+    'sphinx.ext.napoleon',           # NumPy / Google style docstrings
+    'sphinx.ext.autosummary',        # Generate autodoc summaries
+    'sphinx.ext.viewcode',           # Add links to source code
+    'sphinx_autodoc_typehints',      # Include type hints
+    'sphinx.ext.intersphinx',        # Link to other projects' documentation
+    'include_docstring',             # Include docstrings
+    'include_notebook',              # Include notebooks
+    'include_attrs',                 # Include attributes & their docstrings
+    'include_functions',             # Include functions & their docstrings
+    'inherited_attributes',          # Inherit docstrings from parent classes
+    'include_yaml',                  # Include subsets of YAML files
+    'sphinx_copybutton',             # Add copy button to code blocks
+]
+
+autodoc_default_options = {
+    'members': True,
+    'undoc-members': False,
+    'exclude-members': 'model_config,model_fields,__pydantic_fields__,model_post_init',
+}
+
+# ---------- Autodoc settings ----------
+# Show type hints inline in signatures
+autodoc_typehints = "signature"
+autodoc_typehints_format = "short"
+
+# Preserve default values
+autodoc_preserve_defaults = True
+
+# Force multi-line for long constructor signatures (Sphinx 7+)
+autodoc_class_signature = "separated"
+
+# ---------- HTML CSS to wrap signatures ----------
+# Create docs/source/_static/custom.css with:
+# .signature {
+#     white-space: pre-wrap !important;
+#     word-break: break-word;
+# }
+# html_static_path = ["_static"]
+# html_css_files = ["custom.css"]
+# html_js_files = ["custom.js"]
+
+# ---------- Optional: Napoleon settings ----------
+# If using Google/NumPy style docstrings
+napoleon_use_param = True
+napoleon_use_rtype = True
+napoleon_use_ivar = True
+
+nitpicky = True
+
+intersphinx_mapping = {
+    'python': ('https://docs.python.org/3', None),
+    'numpy': ('https://numpy.org/doc/stable/', None),
+    'pandas': ('https://pandas.pydata.org/docs/', None),
+    # 'matplotlib': ('https://matplotlib.org/stable/contents.html', None),
+    'scipy': ('https://docs.scipy.org/doc/scipy/reference/', None),
+    'scikit-learn': ('https://scikit-learn.org/stable/documentation.html', None),
+    'hwcomponents': ('https://accelergy-project.github.io/hwcomponents/', None),
+}

examples/arches/compute_in_memory/_include.yaml

@@ -0,0 +1,74 @@
+cim_component_attributes: &cim_component_attributes
+  # These are for NeuroSim
+  rows:                 array_wordlines
+  cols:                 array_bitlines
+  cols_active_at_once:  array_parallel_outputs
+  cell_config:          cell_config
+  average_input_value:  average_input_value
+  average_cell_value:   average_weight_value
+  voltage:              voltage
+  temporal_dac_bits:    temporal_dac_resolution
+  read_pulse_width:     read_pulse_width
+
+  # These are for the ADC plug-in. Set defaults for them
+  # so that if the user does not specify, we won't get
+  # an error.
+  resolution:       adc_resolution
+  n_adcs:           n_adc_per_bank
+  width:            encoded_output_bits
+
+# These will be applied to the weight drivers
+weight_drivers_attributes: &weight_drivers_attributes
+  <<: *cim_component_attributes
+  rows:                 array_wordlines
+  cols:                 array_bitlines
+  cols_active_at_once:  array_parallel_outputs
+  cell_config:          cell_config
+  average_input_value:  average_input_value
+  average_cell_value:   average_weight_value
+  cycle_seconds:        cycle_period
+  voltage:              voltage
+  temporal_dac_bits:    temporal_dac_resolution
+  sequential:           True
+  read_pulse_width:     0 # Irrelevant for weight programming
+
+variables_global: &variables_global
+  weight_bits: weight.bits_per_value
+  input_bits:  input.bits_per_value
+  output_bits: output.bits_per_value
+  array_parallel_inputs:  get_array_fanout_reuse_output(spec)
+  array_parallel_outputs: get_array_fanout_reuse_input(spec)
+  array_parallel_weights: get_array_fanout_total(spec)
+  array_wordlines: array_parallel_inputs * cim_unit_width_cells
+  array_bitlines: array_parallel_outputs * cim_unit_depth_cells
+  dac_resolution: max(voltage_dac_resolution, temporal_dac_resolution)
+  cols_active_at_once:  array_parallel_outputs
+
+  # Calculate the number of slices needed to store the input and weight bits and
+  # the number of bits in each slice
+  in_b: encoded_input_bits # Shorthands so the following lines aren't super long
+  w_b: encoded_weight_bits
+  max_input_bits_per_slice: min(dac_resolution, in_b)
+  max_weight_bits_per_slice: min(cim_unit_width_cells * bits_per_cell, w_b)
+
+  average_input_bits_per_slice: encoded_input_bits / n_input_slices
+  average_weight_bits_per_slice: encoded_weight_bits / n_weight_slices
+
+  # This is for the bitwise-multiplication of the input and weight slices
+  n_virtual_macs: max_input_bits_per_slice * max_weight_bits_per_slice * encoded_output_bits
+
+  # Calculate statistics for input and weight values and bits after encoding
+  ehtas: encoded_hist_to_avg_slice # Shorthands so the following lines aren't super long
+  in_enc_fn: input_encoding_func
+  w_enc_fn: weight_encoding_func
+  average_input_value:     ehtas(in_enc_fn(inputs_hist), in_b, max_input_bits_per_slice)
+  average_weight_value:    ehtas(w_enc_fn(weights_hist), w_b, max_weight_bits_per_slice)
+  input_bit_distribution:  ehtas(in_enc_fn(inputs_hist), in_b, 1, return_per_slice=True)
+  weight_bit_distribution: ehtas(w_enc_fn(weights_hist), w_b, 1, return_per_slice=True)
+
+  min_weight_slices: ceil(min_supported_weight_bits / bits_per_cell / cim_unit_width_cells)
+  min_input_slices: ceil(min_supported_input_bits / max_input_bits_per_slice)
+
+  n_input_slices:       max(ceil(in_b / max_input_bits_per_slice), min_input_slices)
+  n_weight_slices:      max(ceil(w_b / max_weight_bits_per_slice), min_weight_slices)
+  n_sliced_psums:       n_input_slices * n_weight_slices

examples/arches/compute_in_memory/_include_functions.py

@@ -0,0 +1,229 @@
+import accelforge as af
+
+
+def get_array_fanout_reuse_input(spec: af.Spec) -> int:
+    n_rows = 1
+    for leaf in spec.arch.get_nodes_of_type(af.arch.Leaf):
+        if "array_reuse_input" in leaf.spatial:
+            fanout = leaf.spatial["array_reuse_input"]["fanout"]
+            assert isinstance(fanout, (int, float)), f"fanout {leaf.name}.spatial.array_reuse_input.fanout is not a number"
+            n_rows *= fanout
+    return n_rows
+
+
+def get_array_fanout_reuse_output(spec: af.Spec) -> int:
+    n_cols = 1
+    for leaf in spec.arch.get_nodes_of_type(af.arch.Leaf):
+        if "array_reuse_output" in leaf.spatial:
+            fanout = leaf.spatial["array_reuse_output"]["fanout"]
+            assert isinstance(fanout, (int, float)), f"fanout {leaf.name}.spatial.array_reuse_output.fanout is not a number"
+            n_cols *= fanout
+    return n_cols
+
+
+def get_array_fanout_total(spec: af.Spec) -> int:
+    return get_array_fanout_reuse_input(spec) * get_array_fanout_reuse_output(spec)
+
+
+# Sign magnitude
+# 1. Scale X to [-1, 1]: x = NORM_1_TO_NEG1(x, INPUTS_VALUE_DISTRIBUTION)
+# 2. Convert to signed: x = abs(x) * (2 ** (INPUT_BITS - 1) - 1)
+# 2. x = round(x * (2 ** INPUT_BITS - 1))
+
+from math import log2
+from typing import List, NamedTuple, Union
+
+class ProbableBits(NamedTuple):
+    bits: list
+    probability: float
+
+# ==============================================================================
+# Encoding functions
+# ==============================================================================
+
+
+def magnitude_encode_hist(weights) -> List[ProbableBits]:
+    """
+    A signed value is encoded as a positive or negative magnitude of that value.
+    Signed hardware is requireed.
+    """
+    nbits = get_num_bits(weights)
+    encoded = []
+    halfwidth = len(weights) / 2
+    for i, w in enumerate(weights):
+        normed = norm(i, len(weights), -halfwidth + 0.5, halfwidth + 0.5)
+        encoded.append(ProbableBits(to_bits_unsigned(abs(normed), nbits)[1:], w))
+    return norm_encoded_hist(encoded)
+
+def two_part_magnitude_encode_hist(weights):
+    """
+    Two (devices, timesteps, components, etc.) encode each signed value. If the
+    value is positive, the first device encodes the magnitude of the value. If the
+    value is negative, the second device encodes the magnitude of the value. The
+    other device encodes 0.
+    """
+    m = magnitude_encode_hist(weights)
+    m2 = []
+    for e in m:
+        m2.append(ProbableBits(e.bits, e.probability / 2))
+        m2.append(ProbableBits([0] * len(e.bits), e.probability / 2))
+    return m2
+
+def offset_encode_hist(weights):
+    """
+    A signed value is encoded as the the value minus the negative minimum value.
+    This maps a range of [-min, max] to [0, max - min]. The bias must be added
+    back after computation.
+    """
+    nbits = get_num_bits(weights)
+    encoded = []
+    for i, w in enumerate(weights):
+        normed = norm(i, len(weights), 0, len(weights))
+        encoded.append(ProbableBits(to_bits_unsigned(normed, nbits), w))
+    return norm_encoded_hist(encoded)
+
+
+def offset_encode_if_signed_hist(weights):
+    """
+    Offset encode a value only if it is signed. Otherwise, don't apply any bias and just
+    use the positive values.
+    """
+    if is_hist_signed(weights):
+        return offset_encode_hist(weights)
+    return magnitude_encode_hist(weights)
+
+
+def two_part_magnitude_encode_if_signed_hist(weights):
+    """
+    Two part magnitude encode a value only if it is signed. Otherwise, use only posiive
+    values.
+    """
+    if is_hist_signed(weights):
+        return two_part_magnitude_encode_hist(weights)
+    return magnitude_encode_hist(weights)
+
+
+def xnor_encode_hist(weights):
+    """
+    XNOR encoding based on Jia JSSCC 2020.
+    """
+    nbits = get_num_bits(weights)
+    encoded = []
+    halfwidth = len(weights) / 2
+    for i, w in enumerate(weights):
+        normed = norm(i, len(weights), -halfwidth + 0.5, halfwidth + 0.5)
+        bits = []
+        for j in list(range(nbits - 1, -1, -1)) + [-1, -1]:
+            bits.append(int(normed > 0))
+            normed -= 2**j * (2 * bits[-1] - 1)
+        assert normed == 0, f"normed={normed} is not 0"
+        encoded.append(ProbableBits(bits, w))
+    return norm_encoded_hist(encoded)
+
+
+def zero_gated_xnor_encode_hist(weights):
+    """
+    XNOR encoding with zero gating based on Jia JSSCC 2020.
+    """
+    encoded = xnor_encode_hist(weights)
+    zero_idx = len(encoded) // 2
+    encoded[zero_idx] = ProbableBits(
+        [0] * len(encoded[zero_idx].bits), encoded[zero_idx].probability
+    )
+    return encoded
+
+# ==============================================================================
+# Helper functions
+# ==============================================================================
+
+def assert_hist_pow2_minus1(hist):
+    x = 1
+    while x <= len(hist):
+        x *= 2
+    assert x - 1 == len(
+        hist
+    ), f"Histogram length {len(hist)} is not a power of 2 minus 1."
+
+
+def norm_encoded_hist(encoded_hist: List[ProbableBits]):
+    sum_probs = sum([e.probability for e in encoded_hist])
+    return [ProbableBits(e.bits, e.probability / sum_probs) for e in encoded_hist]
+
+
+def get_num_bits(hist):
+    n_bits = 0
+    while 2**n_bits < len(hist) + 1:
+        n_bits += 1
+    assert (
+        2**n_bits == len(hist) + 1
+    ), f"Number of histogram bins + 1 must be a power of 2, got {len(hist)}."
+    return n_bits
+
+
+def is_hist_signed(hist):
+    return sum(hist[: len(hist) // 2]) != 0
+
+
+def hist_to_magnitude(hist):
+    assert_hist_pow2_minus1(hist)
+    new_hist = [0] * (len(hist) // 2)
+    hist_center = len(hist) // 2
+    for i in range(len(new_hist)):
+        new_hist[i] = hist[hist_center + i] + hist[hist_center - i]
+    assert_hist_pow2_minus1(new_hist)
+    return new_hist
+
+
+def to_bits_unsigned(x, nbits):
+    x = round(x)
+    assert 0 <= x < 2**nbits, f"x={x} is not in range [0, 2^{nbits})"
+    return [int(i) for i in bin(x)[2 : nbits + 2].zfill(nbits)]
+
+
+def norm(x, nbins, rmin, rmax):
+    return x / nbins * (rmax - rmin) + rmin
+
+
+def encoded_hist_to_avg_slice(
+    encoded_hist: List[ProbableBits],
+    total_bits: int,
+    bits_per_slice: Union[list, int],
+    partial_slices_use_full_range: bool = False,
+    return_per_slice: bool = False,
+):
+    if isinstance(bits_per_slice, int):
+        bits_per_slice = [bits_per_slice] * (total_bits // bits_per_slice)
+        if sum(bits_per_slice) != total_bits:
+            bits_per_slice.append(total_bits - sum(bits_per_slice))
+
+    assert total_bits == sum(bits_per_slice), (
+        f"Sum of bits per slice {sum(bits_per_slice)} != total_bits " f"{total_bits}"
+    )
+
+    bit2slice = []
+    max_val = max(2 ** max(bits_per_slice) - 1, 1)
+    for i, b in enumerate(bits_per_slice):
+        m = max(2**b - 1, 1) if partial_slices_use_full_range else max_val
+        bit2slice += [(i, max((2 ** (b - j - 1)), 1) / m) for j in range(b)]
+
+    avg_slice_values = [0] * len(bits_per_slice)
+    for e in encoded_hist:
+        for i in range(total_bits):
+            slice_idx, scale = bit2slice[i]
+            if i >= len(e.bits):
+                bit_value = sum(e.bits) / len(e.bits)
+            else:
+                bit_value = e.bits[i]
+            avg_slice_values[slice_idx] += bit_value * e.probability * scale
+
+    if return_per_slice:
+        return avg_slice_values
+
+    return sum(avg_slice_values) / len(avg_slice_values)
+
+
+if __name__ == "__main__":
+    input_dist = [16 - abs(16 - i) for i in range(31)]
+    print(f"input_dist: {input_dist}")
+    for e in xnor_encode_hist(input_dist):
+        print(e)

examples/arches/compute_in_memory/_load_spec.py

@@ -0,0 +1,57 @@
+import accelforge as af
+import os
+
+THIS_SCRIPT_DIR = os.path.dirname(os.path.abspath(__file__))
+VARIABLES_GLOBAL_PATH = os.path.join(THIS_SCRIPT_DIR, "_include.yaml")
+
+
+def get_spec(
+    arch_name: str,
+    compare_with_arch_name: str | None = None,
+    add_dummy_main_memory: bool = False,
+) -> af.Spec:
+    """
+    Gets the spec for the given architecture. If `compare_with_arch_name` is given, the
+    variables_iso will be grabbed from `compare_with_arch_name` in order to match
+    attributes for fair comparison.
+
+    Parameters
+    ----------
+    arch_name: str
+        The name of the architecture to get the spec for.
+    compare_with_arch_name: str | None
+        The name of the architecture to compare with. If not given, variables will be
+        taken from the given `arch_name`.
+
+    Returns
+    -------
+    spec: af.Spec
+        The spec for the given architecture.
+    """
+    if compare_with_arch_name is None:
+        compare_with_name = arch_name
+    else:
+        compare_with_name = compare_with_arch_name
+
+    arch_name = os.path.join(THIS_SCRIPT_DIR, f"{arch_name}.yaml")
+    compare_with_name = os.path.join(THIS_SCRIPT_DIR, f"{compare_with_name}.yaml")
+    variables = af.Variables.from_yaml(arch_name, top_key="variables")
+    arch = af.Arch.from_yaml(arch_name, top_key="arch")
+    workload = af.Workload.from_yaml(arch_name, top_key="workload")
+    spec = af.Spec(arch=arch, variables=variables, workload=workload)
+
+    spec.config.expression_custom_functions.append(
+        os.path.join(THIS_SCRIPT_DIR, "_include_functions.py")
+    )
+    spec.config.component_models.append(
+        os.path.join(THIS_SCRIPT_DIR, "components/*.py")
+    )
+    if add_dummy_main_memory:
+        main_memory = af.arch.Memory(
+            name="MainMemory",
+            component_class="Dummy",
+            size=float("inf"),
+            tensors={"keep": "~weight"}
+        )
+        spec.arch.nodes.insert(0, main_memory)
+    return spec

examples/arches/compute_in_memory/components/c2c_multiplier.py

@@ -0,0 +1,181 @@
+from hwcomponents.scaling import linear
+from hwcomponents_neurosim import NOTGate
+from hwcomponents import ComponentModel, action
+from misc import Capacitor
+
+
+class C2CMultiplier(ComponentModel):
+    """
+    The C2C multiplier looks like the following:
+
+    - For operand A as an analog voltage
+    - Operand B is a binary digital value with bits B0, B1, B2... from least to most
+      significant
+
+    The circuit looks like:
+
+         2C      2C         2C         2C         2C         2C
+      G──||───┰──||──────┰──||──────┰──||──────┰──||──────┰──||──── -> OUT
+              = C        = C        = C        = C        = C
+              │          │          │          │          │
+               ╲─── B0    ╲─── B1    ╲─── B2    ╲─── B3    ╲─── B4
+             │  G       │  G       │  G       │  G       │  G
+      A──────┴──────────┴──────────┴──────────┴──────────┴─────────
+
+    Energy is consumed when: 1. A increases, and all the B capacitors are charged 2. Any
+    B bit goes 0->1, and the corresponding capacitor is charged
+
+    USAGE: In your architecture, initialize a both a C2CMultiplier and a
+    C2CMultiplierPortB. Have the "a" port process the analog operand and have the "b"
+    port process the digital operand.
+
+    The C2CMultiplier component has area accounted for. The C2CMultiplierPortB component
+    does not have any area!
+
+    Parameters
+    ----------
+    resolution: int
+        The resolution of the multiplier.
+    voltage: float
+        The voltage of the multiplier in volts.
+    unit_capacitance: float
+        The unit capacitance of the multiplier in Farads.
+    a_hist: list[float]
+        The histogram of the analog operand's values. This is a histogram of the values,
+        assumed to be spaced between 0 and voltage, inclusive.
+    b_bit_distribution: list[float]
+        The distribution of the binary operand's bits. Each is a probability of a given
+        bit being 1.
+    tech_node: str
+        The tech node of the multiplier in meters.
+    """
+
+    priority = 0.5
+
+    def __init__(
+        self,
+        resolution: int,
+        voltage: float,
+        unit_capacitance: float,
+        a_hist: list[float],
+        b_bit_distribution: list[float],
+        tech_node: str,
+    ):
+        self.voltage = voltage
+        self.unit_capacitance = unit_capacitance
+        self.a_hist = a_hist
+        self.b_bit_distribution = b_bit_distribution
+        self.tech_node = tech_node
+
+        self.unit_cap = Capacitor(
+            capacitance=unit_capacitance,
+            voltage=voltage,
+            tech_node=tech_node,
+        )
+        self.unit2_cap = Capacitor(
+            capacitance=unit_capacitance * 2,
+            voltage=voltage,
+            tech_node=tech_node,
+        )
+        self.inverter = NOTGate(tech_node=self.tech_node, cycle_period=1e-9)
+
+        a_rms = (sum(i**2 * p for i, p in enumerate(a_hist)) / sum(a_hist)) ** 0.5
+        self.a_rms = a_rms * voltage / (len(a_hist) - 1)
+
+        if not all(0 <= p <= 1 for p in b_bit_distribution):
+            raise ValueError("Bit probabilities must be between 0 and 1")
+        self.b_lo2hi_probability = sum(p * (1 - p) for p in b_bit_distribution) / len(
+            b_bit_distribution
+        )
+
+        # Pass gates are 2 transistors, 100F^2 each
+        control_pass_gate_area = 2 * self.tech_node**2 * 100
+        cap_area = self.unit_cap.area + self.unit2_cap.area
+        inverter_area = self.inverter.area
+
+        # Assume pass gates don't leak
+        inverter_leak = self.inverter.leak_power
+        cap_leak = self.unit_cap.leak_power + self.unit2_cap.leak_power
+
+        super().__init__(
+            area=cap_area + inverter_area + control_pass_gate_area,
+            leak_power=cap_leak + inverter_leak,
+        )
+
+        self.resolution: float = self.scale(
+            "resolution",
+            resolution,
+            1,
+            area_scale_function=linear,
+            energy_scale_function=linear,
+            latency_scale_function=None,
+            leak_power_scale_function=linear,
+        )
+
+    @action
+    def switch_a(self):
+        """
+        Charge all capacitors to the values in a_hist.
+        """
+        # Count energy by just charging one of the capacitors and multiplying by the
+        # number of bits.
+        energy_latency = self.unit_cap.switch(self.a_hist)
+        energy_latency += self.unit2_cap.switch(self.a_hist)
+
+        # The reference node sees a cap of unit_capacitance * 1.67 / resolution per bit
+        # on average assuming a uniform-ish distribution of bits
+        energy, latency = energy_latency
+        energy *= 1.67 / self.resolution
+
+        return energy, latency
+
+    @action
+    def switch_b(self):
+        """
+        Connect capacitors to A with probability b_lo2hi_probability.
+        """
+        energy_latency = self.unit_cap.raise_voltage_to(self.a_rms)
+        energy_latency += self.unit2_cap.raise_voltage_to(self.a_rms)
+        energy, latency = energy_latency
+        energy *= self.b_lo2hi_probability
+        return energy, latency
+
+    @action
+    def read(self):
+        """
+        Returns the energy and latency to send a value through the multiplier's analog
+        port. If you are only using the read() action, then also initialize a
+        C2CMultiplierPortB to have it process the digital operand with the read()
+        action.
+        """
+        return self.switch_a()
+
+
+class C2CMultiplierPortB(C2CMultiplier):
+    def __init__(
+        self,
+        resolution: int,
+        voltage: float,
+        unit_capacitance: float,
+        a_hist: list[float],
+        b_bit_distribution: list[float],
+        tech_node: str,
+    ):
+        super().__init__(
+            resolution=resolution,
+            voltage=voltage,
+            unit_capacitance=unit_capacitance,
+            a_hist=a_hist,
+            b_bit_distribution=b_bit_distribution,
+            tech_node=tech_node,
+        )
+        self.area_scale = 0
+
+    @action
+    def read(self):
+        """
+        Returns the energy and latency to send a value through the multiplier's digital
+        port. If you are only using the read() action, then also initialize a
+        C2CMultiplier to have it process the analog operand with the read() action.
+        """
+        return self.switch_b()