bpred 0.2.0__py3-none-any.whl

bpred/__init__.py

@@ -0,0 +1,42 @@
+"""bpred -- Pure-Python CPU branch predictor simulator.
+
+Provides four classical branch predictors and trace-driven simulation
+utilities for computer architecture education.
+
+Predictors
+----------
+BimodalPredictor
+    Smith (1981) table of saturating counters indexed by PC.
+GsharePredictor
+    McFarling (1993) global-history XOR predictor.
+TournamentPredictor
+    McFarling (1993) / Alpha 21264-style meta-selecting predictor.
+PerceptronPredictor
+    Jimenez and Lin (2001) table of integer-weight perceptrons.
+
+Functions
+---------
+run_trace(predictor, *, trace)
+    Feed a list of (pc, taken) pairs through a predictor.
+accuracy(*, trace_result)
+    Fraction of correctly predicted branches.
+mispredictions(*, trace_result)
+    Count of incorrectly predicted branches.
+"""
+
+from bpred.bimodal import BimodalPredictor
+from bpred.gshare import GsharePredictor
+from bpred.perceptron import PerceptronPredictor
+from bpred.tournament import TournamentPredictor
+from bpred.trace import TraceResult, accuracy, mispredictions, run_trace
+
+__all__ = [
+    "BimodalPredictor",
+    "GsharePredictor",
+    "PerceptronPredictor",
+    "TournamentPredictor",
+    "TraceResult",
+    "accuracy",
+    "mispredictions",
+    "run_trace",
+]

bpred/bimodal.py

@@ -0,0 +1,70 @@
+"""Bimodal (Smith) branch predictor.
+
+Reference: J. E. Smith, "A study of branch prediction strategies," in
+Proceedings of the 8th Annual Symposium on Computer Architecture (ISCA),
+pp. 135-148, 1981.
+"""
+
+from __future__ import annotations
+
+from bpred.counter import SaturatingCounter
+
+
+class BimodalPredictor:
+    """A table of saturating counters indexed by PC mod table_size.
+
+    Each counter independently tracks the taken/not-taken history for
+    branches that alias to the same table entry.  With 2-bit counters
+    (counter_bits=2) this is the classic 2-bit predictor from Smith 1981.
+    """
+
+    _table: list[SaturatingCounter]
+    _table_size: int
+    _counter_bits: int
+
+    def __init__(self, *, counter_bits: int, table_size: int) -> None:
+        if counter_bits < 1:
+            raise ValueError(f"counter_bits must be >= 1, got {counter_bits}")
+        if table_size < 1:
+            raise ValueError(f"table_size must be >= 1, got {table_size}")
+        self._counter_bits = counter_bits
+        self._table_size = table_size
+        # Initialise all counters to weakly taken (threshold - 1 rounded up)
+        # so the predictor starts in a neutral "weakly taken" state.
+        initial = 1 << (counter_bits - 1)  # weakly taken
+        self._table = [
+            SaturatingCounter(bits=counter_bits, initial=initial)
+            for _ in range(table_size)
+        ]
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def table_size(self) -> int:
+        """Number of entries in the prediction table."""
+        return self._table_size
+
+    @property
+    def counter_bits(self) -> int:
+        """Bit-width of each saturating counter."""
+        return self._counter_bits
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def predict(self, *, pc: int) -> bool:
+        """Return the taken prediction for the branch at *pc*."""
+        return self._table[pc % self._table_size].predict()
+
+    def update(self, *, pc: int, taken: bool) -> None:
+        """Update the counter for the branch at *pc* with the actual outcome."""
+        self._table[pc % self._table_size].update(taken=taken)
+
+    def __repr__(self) -> str:
+        return (
+            f"BimodalPredictor(counter_bits={self._counter_bits}, "
+            f"table_size={self._table_size})"
+        )

bpred/cli.py

@@ -0,0 +1,167 @@
+"""Command-line interface for bpred."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+
+from bpred import (
+    BimodalPredictor,
+    GsharePredictor,
+    TournamentPredictor,
+    accuracy,
+    mispredictions,
+    run_trace,
+)
+from bpred.tournament import BranchPredictor
+
+
+def _parse_taken(token: str) -> bool:
+    """Convert a taken token to bool.
+
+    Accepts: 1/0, T/F, true/false (case-insensitive).
+    """
+    normalised = token.strip().lower()
+    if normalised in {"1", "t", "true"}:
+        return True
+    if normalised in {"0", "f", "false"}:
+        return False
+    raise ValueError(f"Cannot parse taken value: {token!r}")
+
+
+def _parse_pc(token: str) -> int:
+    """Parse a PC value as decimal or hex (0x prefix)."""
+    token = token.strip()
+    if token.startswith("0x") or token.startswith("0X"):
+        return int(token, 16)
+    return int(token)
+
+
+def _load_trace(path: Path) -> list[tuple[int, bool]]:
+    """Load a trace file with lines of the form ``<pc> <taken>``.
+
+    Blank lines and lines beginning with ``#`` are ignored.
+    """
+    trace: list[tuple[int, bool]] = []
+    with path.open() as fh:
+        for lineno, raw in enumerate(fh, start=1):
+            line = raw.strip()
+            if not line or line.startswith("#"):
+                continue
+            parts = line.split()
+            if len(parts) != 2:
+                raise ValueError(
+                    f"Line {lineno}: expected '<pc> <taken>', got {line!r}"
+                )
+            pc = _parse_pc(parts[0])
+            taken = _parse_taken(parts[1])
+            trace.append((pc, taken))
+    return trace
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="bpred",
+        description="Simulate classical CPU branch predictors on a branch trace.",
+    )
+    sub = parser.add_subparsers(dest="predictor", required=True)
+
+    # ------------------------------------------------------------------
+    # bimodal
+    # ------------------------------------------------------------------
+    bimodal = sub.add_parser("bimodal", help="Bimodal (Smith 1981) predictor")
+    bimodal.add_argument("--counter-bits", type=int, required=True)
+    bimodal.add_argument("--table-size", type=int, required=True)
+    bimodal.add_argument("tracefile", type=Path)
+
+    # ------------------------------------------------------------------
+    # gshare
+    # ------------------------------------------------------------------
+    gshare = sub.add_parser("gshare", help="Gshare (McFarling 1993) predictor")
+    gshare.add_argument("--history-bits", type=int, required=True)
+    gshare.add_argument("--table-size", type=int, required=True)
+    gshare.add_argument("tracefile", type=Path)
+
+    # ------------------------------------------------------------------
+    # tournament
+    # ------------------------------------------------------------------
+    tourn = sub.add_parser(
+        "tournament", help="Tournament (Alpha 21264-style) predictor"
+    )
+    tourn.add_argument(
+        "--local-predictor",
+        choices=["bimodal"],
+        required=True,
+    )
+    tourn.add_argument("--local-counter-bits", type=int, required=True)
+    tourn.add_argument("--local-table-size", type=int, required=True)
+    tourn.add_argument(
+        "--global-predictor",
+        choices=["gshare"],
+        required=True,
+    )
+    tourn.add_argument("--global-history-bits", type=int, required=True)
+    tourn.add_argument("--global-table-size", type=int, required=True)
+    tourn.add_argument("--meta-bits", type=int, required=True)
+    tourn.add_argument("tracefile", type=Path)
+
+    return parser
+
+
+def _build_predictor(args: argparse.Namespace) -> BranchPredictor:
+    """Construct the predictor requested by *args*."""
+    if args.predictor == "bimodal":
+        return BimodalPredictor(
+            counter_bits=args.counter_bits,
+            table_size=args.table_size,
+        )
+    if args.predictor == "gshare":
+        return GsharePredictor(
+            history_bits=args.history_bits,
+            table_size=args.table_size,
+        )
+    if args.predictor == "tournament":
+        local: BranchPredictor = BimodalPredictor(
+            counter_bits=args.local_counter_bits,
+            table_size=args.local_table_size,
+        )
+        global_: BranchPredictor = GsharePredictor(
+            history_bits=args.global_history_bits,
+            table_size=args.global_table_size,
+        )
+        return TournamentPredictor(
+            local=local,
+            global_=global_,
+            meta_bits=args.meta_bits,
+        )
+    raise ValueError(f"Unknown predictor: {args.predictor}")
+
+
+def main() -> None:
+    """Entry point for the ``bpred`` CLI."""
+    parser = _build_parser()
+    args = parser.parse_args()
+
+    tracefile: Path = args.tracefile
+    if not tracefile.exists():
+        print(f"error: trace file not found: {tracefile}", file=sys.stderr)
+        sys.exit(1)
+
+    try:
+        trace = _load_trace(tracefile)
+    except ValueError as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(1)
+
+    predictor = _build_predictor(args)
+    result = run_trace(predictor, trace=trace)
+
+    acc = accuracy(trace_result=result)
+    misses = mispredictions(trace_result=result)
+
+    print(f"Predictor : {predictor!r}")
+    print(f"Branches  : {result.total}")
+    print(f"Hits      : {result.hits}")
+    print(f"Misses    : {misses}")
+    print(f"Accuracy  : {acc:.4%}")

bpred/counter.py

@@ -0,0 +1,70 @@
+"""Saturating counter used as the base building block for all branch predictors."""
+
+from __future__ import annotations
+
+
+class SaturatingCounter:
+    """An n-bit saturating counter in the range [0, 2^n - 1].
+
+    Prediction is *taken* when the value is >= 2^(n-1).
+    Incrementing toward 2^n - 1 models a taken branch; decrementing toward 0
+    models a not-taken branch.  At the extremes the counter saturates rather
+    than wrapping.
+
+    The n=1 special case produces a 1-bit predictor with states {0, 1}.
+    """
+
+    _value: int
+    _max: int
+    _threshold: int
+
+    def __init__(self, *, bits: int, initial: int) -> None:
+        if bits < 1:
+            raise ValueError(f"bits must be >= 1, got {bits}")
+        self._max = (1 << bits) - 1
+        self._threshold = 1 << (bits - 1)
+        if not (0 <= initial <= self._max):
+            raise ValueError(f"initial {initial} out of range [0, {self._max}]")
+        self._value = initial
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def value(self) -> int:
+        """Current counter value."""
+        return self._value
+
+    @property
+    def max_value(self) -> int:
+        """Maximum value this counter can hold (2^bits - 1)."""
+        return self._max
+
+    # ------------------------------------------------------------------
+    # Core operations
+    # ------------------------------------------------------------------
+
+    def predict(self) -> bool:
+        """Return True (taken) when value >= threshold."""
+        return self._value >= self._threshold
+
+    def increment(self) -> None:
+        """Increment toward max_value (saturating)."""
+        if self._value < self._max:
+            self._value += 1
+
+    def decrement(self) -> None:
+        """Decrement toward 0 (saturating)."""
+        if self._value > 0:
+            self._value -= 1
+
+    def update(self, *, taken: bool) -> None:
+        """Increment on taken, decrement on not-taken."""
+        if taken:
+            self.increment()
+        else:
+            self.decrement()
+
+    def __repr__(self) -> str:
+        return f"SaturatingCounter(value={self._value}, max={self._max})"

bpred/gshare.py

@@ -0,0 +1,94 @@
+"""Gshare branch predictor.
+
+Reference: S. McFarling, "Combining Branch Predictors," WRL Technical Note
+TN-36, Digital Equipment Corporation Western Research Laboratory, June 1993.
+"""
+
+from __future__ import annotations
+
+from bpred.counter import SaturatingCounter
+
+_COUNTER_BITS = 2
+
+
+class GsharePredictor:
+    """Global-history XOR-indexed branch predictor (gshare).
+
+    A global history register (GHR) of *history_bits* bits is XOR'd with the
+    lower *history_bits* bits of the PC to index into a prediction table of
+    2-bit saturating counters.
+
+    After each branch the actual outcome is shifted into the GHR (MSB first,
+    keeping only the most recent *history_bits* outcomes).
+    """
+
+    _table: list[SaturatingCounter]
+    _table_size: int
+    _history_bits: int
+    _history_mask: int
+    _ghr: int  # global history register
+
+    def __init__(self, *, history_bits: int, table_size: int) -> None:
+        if history_bits < 1:
+            raise ValueError(f"history_bits must be >= 1, got {history_bits}")
+        if table_size < 1:
+            raise ValueError(f"table_size must be >= 1, got {table_size}")
+        self._history_bits = history_bits
+        self._history_mask = (1 << history_bits) - 1
+        self._table_size = table_size
+        self._ghr = 0
+        initial = 1 << (_COUNTER_BITS - 1)  # weakly taken
+        self._table = [
+            SaturatingCounter(bits=_COUNTER_BITS, initial=initial)
+            for _ in range(table_size)
+        ]
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def table_size(self) -> int:
+        """Number of entries in the prediction table."""
+        return self._table_size
+
+    @property
+    def history_bits(self) -> int:
+        """Width of the global history register."""
+        return self._history_bits
+
+    @property
+    def ghr(self) -> int:
+        """Current value of the global history register."""
+        return self._ghr
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _index(self, *, pc: int) -> int:
+        """Compute table index: (pc XOR ghr) mod table_size."""
+        return (pc ^ self._ghr) % self._table_size
+
+    def _shift_history(self, *, taken: bool) -> None:
+        """Shift *taken* into the MSB of the GHR, keeping history_bits."""
+        self._ghr = ((self._ghr << 1) | int(taken)) & self._history_mask
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def predict(self, *, pc: int) -> bool:
+        """Return the taken prediction for the branch at *pc*."""
+        return self._table[self._index(pc=pc)].predict()
+
+    def update(self, *, pc: int, taken: bool) -> None:
+        """Update the counter and GHR for the branch at *pc*."""
+        self._table[self._index(pc=pc)].update(taken=taken)
+        self._shift_history(taken=taken)
+
+    def __repr__(self) -> str:
+        return (
+            f"GsharePredictor(history_bits={self._history_bits}, "
+            f"table_size={self._table_size})"
+        )

bpred/perceptron.py

@@ -0,0 +1,183 @@
+"""Perceptron branch predictor.
+
+Reference: D. A. Jimenez and C. Lin, "Dynamic Branch Prediction with
+Perceptrons," in Proceedings of the 7th International Symposium on High-
+Performance Computer Architecture (HPCA), pp. 197-206, January 2001.
+
+Each perceptron is a vector of integer weights.  The dot product of those
+weights with the history vector (bias + H history bits) gives the confidence
+and direction of the prediction.  Weight updates use the perceptron learning
+rule, gated by a threshold theta to prevent over-training on easy branches.
+
+Training threshold (Jimenez & Lin, Section 3.3):
+    theta = floor(1.93 * H + 14)
+where H is the history length.  This integer form is the standard used in
+hardware and simulation; it derives from the optimal threshold analysis in
+the paper.
+
+History encoding:
+    taken   -> +1
+    not-taken -> -1
+
+The bias input x_0 is always +1.
+
+Weights are stored as plain Python ints and are left unclamped (unbounded).
+Hardware implementations clamp to a signed fixed-point range for area
+efficiency, but clamping is orthogonal to correctness and is omitted here
+to keep the simulator transparent and exact.
+"""
+
+from __future__ import annotations
+
+import math
+
+
+class PerceptronPredictor:
+    """Table of perceptrons for branch prediction (Jimenez and Lin 2001).
+
+    Each perceptron is a list of (H + 1) integer weights: w[0] is the bias
+    weight (multiplied by x_0 = +1 always) and w[1..H] are multiplied by the
+    corresponding bits of the global history register (GHR).
+
+    The table is indexed by pc % table_size.  The GHR is an integer where
+    bit position i (0 = most recent) stores the outcome of the i-th most
+    recent branch: 1 for taken, 0 for not-taken.  When computing the dot
+    product the bits are converted to {+1, -1} on the fly.
+    """
+
+    _table: list[list[int]]
+    _table_size: int
+    _history_length: int
+    _theta: int
+    _ghr: int         # packed history; bit 0 = most recent outcome
+    _history_mask: int
+
+    def __init__(self, *, history_length: int, table_size: int) -> None:
+        """Create a PerceptronPredictor.
+
+        Args:
+            history_length: Number of history bits H.  Must be >= 1.
+            table_size:     Number of perceptrons in the table.  Must be >= 1.
+        """
+        if history_length < 1:
+            raise ValueError(
+                f"history_length must be >= 1, got {history_length}"
+            )
+        if table_size < 1:
+            raise ValueError(f"table_size must be >= 1, got {table_size}")
+
+        self._history_length = history_length
+        self._table_size = table_size
+        # Standard threshold from Jimenez & Lin Section 3.3:
+        #   theta = floor(1.93 * H + 14)
+        self._theta = math.floor(1.93 * history_length + 14)
+        self._history_mask = (1 << history_length) - 1
+        self._ghr = 0
+        # All weights initialised to 0: bias and history weights start neutral.
+        self._table = [
+            [0] * (history_length + 1) for _ in range(table_size)
+        ]
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def table_size(self) -> int:
+        """Number of entries (perceptrons) in the table."""
+        return self._table_size
+
+    @property
+    def history_length(self) -> int:
+        """Number of global history bits H."""
+        return self._history_length
+
+    @property
+    def theta(self) -> int:
+        """Training threshold: floor(1.93 * H + 14)."""
+        return self._theta
+
+    @property
+    def ghr(self) -> int:
+        """Current value of the global history register (raw packed int)."""
+        return self._ghr
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _index(self, *, pc: int) -> int:
+        """Table index: pc mod table_size."""
+        return pc % self._table_size
+
+    def _history_vector(self) -> list[int]:
+        """Return the current history as a list of +1/-1 values.
+
+        x[0] is the bias (always +1).
+        x[i] for i in 1..H corresponds to the (i-1)-th most recent branch,
+        where bit (i-1) of _ghr is 1 (taken) or 0 (not-taken).
+        """
+        x: list[int] = [1]  # x[0] = bias = +1
+        for i in range(self._history_length):
+            bit = (self._ghr >> i) & 1
+            x.append(1 if bit else -1)
+        return x
+
+    def _dot(self, *, weights: list[int]) -> int:
+        """Compute y = sum(w[i] * x[i]) using current history."""
+        x = self._history_vector()
+        total = 0
+        for w, xi in zip(weights, x):
+            total += w * xi
+        return total
+
+    def _shift_history(self, *, taken: bool) -> None:
+        """Shift the new outcome into the GHR as the most recent bit."""
+        self._ghr = ((self._ghr << 1) | int(taken)) & self._history_mask
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def predict(self, *, pc: int) -> bool:
+        """Return the taken prediction for the branch at *pc*.
+
+        Computes y = w dot x; predicts taken if y >= 0.
+        """
+        idx = self._index(pc=pc)
+        y = self._dot(weights=self._table[idx])
+        return y >= 0
+
+    def update(self, *, pc: int, taken: bool) -> None:
+        """Update the perceptron for *pc* with the actual outcome.
+
+        Training rule (Jimenez & Lin):
+          t = +1 if taken, -1 if not-taken.
+          Compute y = w dot x.
+          If prediction was wrong OR |y| <= theta:
+              for each i: w[i] = w[i] + t * x[i]
+          Shift taken into the GHR after training.
+
+        The GHR is updated AFTER training so that the same history vector
+        used during prediction is also used during training.
+        """
+        idx = self._index(pc=pc)
+        weights = self._table[idx]
+        x = self._history_vector()
+        y = self._dot(weights=weights)
+
+        predicted_taken = y >= 0
+        t = 1 if taken else -1
+
+        # Train when prediction was wrong or confidence is below theta.
+        if predicted_taken != taken or abs(y) <= self._theta:
+            for i in range(len(weights)):
+                weights[i] += t * x[i]
+
+        self._shift_history(taken=taken)
+
+    def __repr__(self) -> str:
+        return (
+            f"PerceptronPredictor(history_length={self._history_length}, "
+            f"table_size={self._table_size})"
+        )

bpred/tournament.py

@@ -0,0 +1,137 @@
+"""Tournament (hybrid) branch predictor.
+
+Reference: S. McFarling, "Combining Branch Predictors," WRL Technical Note
+TN-36, Digital Equipment Corporation Western Research Laboratory, June 1993.
+
+The design follows the Alpha 21264 tournament predictor: a meta-selector table
+of saturating counters chooses between a local and a global sub-predictor.
+The chooser is updated only when the two sub-predictors disagree, biasing it
+toward whichever was correct.
+"""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from bpred.counter import SaturatingCounter
+
+
+class BranchPredictor(Protocol):
+    """Structural protocol satisfied by BimodalPredictor and GsharePredictor."""
+
+    @property
+    def table_size(self) -> int: ...
+
+    def predict(self, *, pc: int) -> bool: ...
+
+    def update(self, *, pc: int, taken: bool) -> None: ...
+
+
+class TournamentPredictor:
+    """Meta-predictor that combines a local and a global sub-predictor.
+
+    The chooser table contains *meta_bits*-bit saturating counters.  A low
+    chooser value (< threshold) means "trust the local predictor"; a high
+    value (>= threshold) means "trust the global predictor."
+
+    Chooser update rule (classic Alpha 21264):
+    - Both correct or both wrong: no update.
+    - Only local correct: decrement chooser toward 0 (favor local).
+    - Only global correct: increment chooser toward max (favor global).
+
+    Both sub-predictors are always updated with the actual outcome,
+    regardless of which one the meta-selector chose.
+    """
+
+    _local: BranchPredictor
+    _global: BranchPredictor
+    _chooser: list[SaturatingCounter]
+    _chooser_size: int
+    _meta_bits: int
+    _threshold: int
+
+    def __init__(
+        self,
+        *,
+        local: BranchPredictor,
+        global_: BranchPredictor,
+        meta_bits: int,
+    ) -> None:
+        if meta_bits < 1:
+            raise ValueError(f"meta_bits must be >= 1, got {meta_bits}")
+        self._local = local
+        self._global = global_
+        self._meta_bits = meta_bits
+        self._threshold = 1 << (meta_bits - 1)
+        # Chooser table sized to the larger sub-predictor table.
+        self._chooser_size = max(local.table_size, global_.table_size)
+        # Start neutral: weakly global (threshold value).
+        initial = self._threshold
+        self._chooser = [
+            SaturatingCounter(bits=meta_bits, initial=initial)
+            for _ in range(self._chooser_size)
+        ]
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def table_size(self) -> int:
+        """Size of the meta-selector chooser table."""
+        return self._chooser_size
+
+    @property
+    def meta_bits(self) -> int:
+        """Bit-width of each chooser counter."""
+        return self._meta_bits
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _chooser_index(self, *, pc: int) -> int:
+        return pc % self._chooser_size
+
+    def _use_global(self, *, pc: int) -> bool:
+        """Return True when the chooser favors the global sub-predictor."""
+        idx = self._chooser_index(pc=pc)
+        return self._chooser[idx].value >= self._threshold
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def predict(self, *, pc: int) -> bool:
+        """Return the prediction chosen by the meta-selector."""
+        if self._use_global(pc=pc):
+            return self._global.predict(pc=pc)
+        return self._local.predict(pc=pc)
+
+    def update(self, *, pc: int, taken: bool) -> None:
+        """Update both sub-predictors and the chooser.
+
+        The chooser is updated only when the two sub-predictors disagree.
+        """
+        local_pred = self._local.predict(pc=pc)
+        global_pred = self._global.predict(pc=pc)
+
+        # Update chooser only on disagreement.
+        if local_pred != global_pred:
+            local_correct = local_pred == taken
+            global_correct = global_pred == taken
+            idx = self._chooser_index(pc=pc)
+            if local_correct and not global_correct:
+                self._chooser[idx].decrement()
+            elif global_correct and not local_correct:
+                self._chooser[idx].increment()
+
+        # Always update both sub-predictors.
+        self._local.update(pc=pc, taken=taken)
+        self._global.update(pc=pc, taken=taken)
+
+    def __repr__(self) -> str:
+        return (
+            f"TournamentPredictor(local={self._local!r}, "
+            f"global_={self._global!r}, meta_bits={self._meta_bits})"
+        )

bpred/trace.py

@@ -0,0 +1,95 @@
+"""Trace-driven simulation utilities."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+
+class BranchPredictor(Protocol):
+    """Structural protocol for any predictor accepted by run_trace."""
+
+    def predict(self, *, pc: int) -> bool: ...
+
+    def update(self, *, pc: int, taken: bool) -> None: ...
+
+
+@dataclass(frozen=True)
+class TraceResult:
+    """Result of running a branch trace through a predictor.
+
+    Attributes:
+        predictions: Ordered list of predictions made before each update.
+        correct:     Whether each prediction matched the actual outcome.
+        total:       Total number of branches in the trace.
+        hits:        Number of correctly predicted branches.
+    """
+
+    predictions: list[bool]
+    correct: list[bool]
+    total: int
+    hits: int
+
+
+def run_trace(
+    predictor: BranchPredictor,
+    *,
+    trace: list[tuple[int, bool]],
+) -> TraceResult:
+    """Feed (pc, taken) pairs through *predictor* and collect statistics.
+
+    For each entry the prediction is recorded *before* the predictor is
+    updated, matching real hardware behaviour.
+
+    Args:
+        predictor: Any object with ``predict`` and ``update`` methods.
+        trace:     Ordered list of (pc, taken) pairs.
+
+    Returns:
+        A :class:`TraceResult` with per-branch predictions and aggregate counts.
+    """
+    predictions: list[bool] = []
+    correct: list[bool] = []
+    hits = 0
+
+    for pc, taken in trace:
+        pred = predictor.predict(pc=pc)
+        hit = pred == taken
+        predictions.append(pred)
+        correct.append(hit)
+        if hit:
+            hits += 1
+        predictor.update(pc=pc, taken=taken)
+
+    return TraceResult(
+        predictions=predictions,
+        correct=correct,
+        total=len(trace),
+        hits=hits,
+    )
+
+
+def accuracy(*, trace_result: TraceResult) -> float:
+    """Return prediction accuracy as a fraction in [0.0, 1.0].
+
+    Args:
+        trace_result: Result from :func:`run_trace`.
+
+    Returns:
+        hits / total, or 0.0 for an empty trace.
+    """
+    if trace_result.total == 0:
+        return 0.0
+    return trace_result.hits / trace_result.total
+
+
+def mispredictions(*, trace_result: TraceResult) -> int:
+    """Return the number of mispredicted branches.
+
+    Args:
+        trace_result: Result from :func:`run_trace`.
+
+    Returns:
+        total - hits
+    """
+    return trace_result.total - trace_result.hits

bpred-0.2.0.dist-info/METADATA

@@ -0,0 +1,172 @@
+Metadata-Version: 2.4
+Name: bpred
+Version: 0.2.0
+Summary: Pure-Python simulator of classical CPU branch predictors: bimodal, gshare, and tournament
+Project-URL: Homepage, https://github.com/amaar-mc/bpred
+Project-URL: Repository, https://github.com/amaar-mc/bpred
+Project-URL: Issues, https://github.com/amaar-mc/bpred/issues
+Author-email: Amaar Chughtai <amaardevx@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2026 Amaar Chughtai
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Keywords: bimodal,branch-prediction,computer-architecture,cpu-simulator,education,gshare
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: dev
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# bpred
+
+<p align="center">
+  <img src="assets/logo.png" alt="bpred logo" width="160">
+</p>
+
+Pure-Python simulator of classical CPU branch predictors for computer architecture education.
+
+Implements four predictors from first principles with zero runtime dependencies:
+
+- **Bimodal** (Smith 1981) -- a table of n-bit saturating counters indexed by PC.
+- **Gshare** (McFarling 1993) -- PC XOR global-history register indexes 2-bit counters.
+- **Tournament** (McFarling 1993 / Alpha 21264) -- a meta-selector combining local and global sub-predictors.
+- **Perceptron** (Jimenez and Lin 2001) -- a table of integer-weight perceptrons that can learn linearly-separable history patterns bimodal and gshare cannot capture.
+
+Part of the same open-source computer architecture education series as [tomasulo](https://github.com/amaar-mc/tomasulo) (out-of-order execution) and scoreboarding.
+
+## Install
+
+```bash
+pip install bpred
+```
+
+PyPI publication is pending; install from source in the meantime:
+
+```bash
+git clone https://github.com/amaar-mc/bpred
+cd bpred
+pip install -e ".[dev]"
+```
+
+## Python API
+
+```python
+from bpred import BimodalPredictor, GsharePredictor, PerceptronPredictor, TournamentPredictor
+from bpred import run_trace, accuracy, mispredictions
+
+# Bimodal: 2-bit counters, 1024-entry table
+pred = BimodalPredictor(counter_bits=2, table_size=1024)
+
+# Gshare: 10-bit history, 1024-entry table
+pred = GsharePredictor(history_bits=10, table_size=1024)
+
+# Tournament
+from bpred import BimodalPredictor, GsharePredictor
+local = BimodalPredictor(counter_bits=2, table_size=1024)
+global_ = GsharePredictor(history_bits=10, table_size=1024)
+pred = TournamentPredictor(local=local, global_=global_, meta_bits=2)
+
+# Perceptron: 12-bit history, 1024-entry table
+pred = PerceptronPredictor(history_length=12, table_size=1024)
+
+# Feed a trace
+trace = [(0x1000, True), (0x1004, False), (0x1008, True)]
+result = run_trace(pred, trace=trace)
+print(accuracy(trace_result=result))       # e.g. 0.6667
+print(mispredictions(trace_result=result)) # e.g. 1
+```
+
+### Why use the perceptron predictor?
+
+Bimodal and gshare each use a single scalar counter per table entry, so they
+can only learn the *average* bias of a branch.  When the taken/not-taken
+outcome correlates with a specific combination of recent history bits (a
+linearly-separable pattern), those predictors plateau.
+
+The perceptron predictor maintains a weight vector per entry.  The dot product
+of those weights with the history vector expresses arbitrary linear functions
+over H history bits.  This lets it learn, for example, "taken when the last
+4 branches were all taken" or "taken on every other iteration" -- patterns
+that require tracking distinct history bits simultaneously.  The trade-off is
+that the predictor needs more warm-up branches to converge and the weights
+grow without bound (in simulation; hardware clamps them to a fixed-point
+range).
+
+## CLI
+
+```
+bpred bimodal --counter-bits 2 --table-size 1024 path/to/trace.trace
+bpred gshare --history-bits 10 --table-size 1024 path/to/trace.trace
+bpred tournament \
+  --local-predictor bimodal --local-counter-bits 2 --local-table-size 1024 \
+  --global-predictor gshare --global-history-bits 10 --global-table-size 1024 \
+  --meta-bits 2 \
+  path/to/trace.trace
+```
+
+Trace file format -- one branch per line:
+
+```
+# pc taken
+0x1000 1
+0x1004 0
+0x1008 T
+0x100c false
+```
+
+## Accuracy example
+
+Running the bundled sample trace with a gshare predictor:
+
+```
+$ bpred gshare --history-bits 4 --table-size 16 examples/sample.trace
+Predictor : GsharePredictor(history_bits=4, table_size=16)
+Branches  : 20
+Hits      : 18
+Misses    : 2
+Accuracy  : 90.0000%
+```
+
+## Development
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+ruff check .
+mypy src
+```
+
+## License
+
+MIT. See [LICENSE](LICENSE).

bpred-0.2.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+bpred/__init__.py,sha256=ElpUYpNLQehyeVkLYEUGIu3raUigNZZiUlP7PRAMmyI,1222
+bpred/bimodal.py,sha256=rNN8Kpr_bcyWXFWkRaIj7BBexhy1U1V_vmbpT9DZNqo,2538
+bpred/cli.py,sha256=i-QdTse5wAv-ocgMKyknxPG6XFJpYAOiUtW-zYFEDbQ,5475
+bpred/counter.py,sha256=7J0VdMzxJ6nFsqJyOCpjAdu1r0GwHPa-2quy9G2KShM,2255
+bpred/gshare.py,sha256=hxVuWkZ8A7xe1SqV3AtBeHf0VjytvBVJuZtZjo-dt68,3306
+bpred/perceptron.py,sha256=MWrajdEnAEpVxRvYhgIxZHAKOWhxZd1mXqZIgs-isY8,6609
+bpred/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+bpred/tournament.py,sha256=AoixJLPSoBzSaIVQC2ugWBqQO2w4sZlGP9FAgYayXVc,4815
+bpred/trace.py,sha256=f6JtONZZ48m6uKfQTPKig3WCZZcw8gwsBlCWn9oBQmc,2448
+bpred-0.2.0.dist-info/METADATA,sha256=1SUBzl07nULlpobSovRYgqOdlEJRqsNiOTdozJ6a21Y,6274
+bpred-0.2.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+bpred-0.2.0.dist-info/entry_points.txt,sha256=ZBCc52QaGDNOg73I2UjdBCFiPvPlssxZ9gNAqqfeymc,41
+bpred-0.2.0.dist-info/licenses/LICENSE,sha256=NORTVJb4x206RXQkpZt_vpj8I7aZL6Vn26BvTOq6J40,1071
+bpred-0.2.0.dist-info/RECORD,,

bpred-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

bpred-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bpred = bpred.cli:main

bpred-0.2.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Amaar Chughtai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.