bpred 0.2.0__tar.gz → 0.3.0__tar.gz

{bpred-0.2.0 → bpred-0.3.0}/CHANGELOG.md

@@ -5,6 +5,20 @@ All notable changes to this project will be documented in this file.
 The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
 This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.3.0] - 2026-06-23
+
+### Added
+
+- `LocalHistoryPredictor`: Yeh and Patt (1991) PAg two-level adaptive predictor.
+  A per-branch local history table (BHT) indexed by PC feeds a shared pattern
+  history table (PHT) of 2-bit saturating counters indexed by the local history
+  pattern.  Learns periodic per-branch patterns (for example strict alternating
+  T,N,T,N) that a bimodal predictor thrashes on; a period-k pattern is captured
+  once `history_bits >= k`.
+  Constructor: `LocalHistoryPredictor(history_bits=N, bht_size=B, pht_size=P)`.
+  Exported from `bpred` top-level package and available as the `local` CLI
+  subcommand.
+
 ## [0.2.0] - 2026-06-17
 
 ### Added
@@ -14,12 +28,6 @@ This project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
   Constructor: `PerceptronPredictor(history_length=H, table_size=N)`.
   Exported from `bpred` top-level package.
 
-### Notes
-
-- PyPI publish is queued behind the new-project creation quota (currently
-  rate-limited). Build artifact passes `twine check`. Publish will follow once
-  the quota resets.
-
 ## [0.1.0] - 2026-06-17
 
 ### Added

{bpred-0.2.0 → bpred-0.3.0}/PKG-INFO

@@ -1,7 +1,7 @@
 Metadata-Version: 2.4
 Name: bpred
-Version: 0.2.0
-Summary: Pure-Python simulator of classical CPU branch predictors: bimodal, gshare, and tournament
+Version: 0.3.0
+Summary: Pure-Python simulator of classical CPU branch predictors: bimodal, gshare, tournament, perceptron, and local-history
 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
@@ -28,7 +28,7 @@ License: MIT License
         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
+Keywords: bimodal,branch-prediction,computer-architecture,cpu-simulator,education,gshare,perceptron,two-level-adaptive
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Education
 Classifier: Intended Audience :: Science/Research
@@ -56,12 +56,13 @@ Description-Content-Type: text/markdown
 
 Pure-Python simulator of classical CPU branch predictors for computer architecture education.
 
-Implements four predictors from first principles with zero runtime dependencies:
+Implements five 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.
+- **Local-history / PAg** (Yeh and Patt 1991) -- a per-branch local history table feeds a shared pattern history table, learning periodic per-branch patterns that a bimodal predictor thrashes on.
 
 Part of the same open-source computer architecture education series as [tomasulo](https://github.com/amaar-mc/tomasulo) (out-of-order execution) and scoreboarding.
 
@@ -71,18 +72,11 @@ Part of the same open-source computer architecture education series as [tomasulo
 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 LocalHistoryPredictor
 from bpred import run_trace, accuracy, mispredictions
 
 # Bimodal: 2-bit counters, 1024-entry table
@@ -100,6 +94,9 @@ pred = TournamentPredictor(local=local, global_=global_, meta_bits=2)
 # Perceptron: 12-bit history, 1024-entry table
 pred = PerceptronPredictor(history_length=12, table_size=1024)
 
+# Local-history (PAg): 8-bit per-branch history, 1024-entry BHT, 256-entry PHT
+pred = LocalHistoryPredictor(history_bits=8, bht_size=1024, pht_size=256)
+
 # Feed a trace
 trace = [(0x1000, True), (0x1004, False), (0x1008, True)]
 result = run_trace(pred, trace=trace)
@@ -123,11 +120,30 @@ 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).
 
+### Why use the local-history (PAg) predictor?
+
+Bimodal predicts each branch from a single counter, so a branch whose outcome
+follows a short repeating pattern -- the textbook `T, N, T, N, ...` of a loop
+that runs an even number of times, for example -- makes the counter oscillate
+and the predictor thrashes near 50%.
+
+The local-history predictor (the PAg configuration of Yeh and Patt's two-level
+adaptive scheme, 1991) gives every branch its own N-bit shift register of
+recent outcomes in a branch history table (BHT).  That local pattern then
+indexes a shared pattern history table (PHT) of 2-bit counters, so each
+distinct recent-history pattern gets its own counter.  A period-k pattern is
+learned to near-100% accuracy once `history_bits >= k`, because each phase of
+the period maps to a different PHT entry.  The first level is per-address
+(`P`), the training is adaptive (`A`), and the second-level PHT is global
+(`g`), which is what the name PAg encodes.  The per-address-PHT variant (PAp)
+is a natural extension left as future work.
+
 ## 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 local --history-bits 8 --bht-size 1024 --pht-size 256 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 \

{bpred-0.2.0 → bpred-0.3.0}/README.md

@@ -6,12 +6,13 @@
 
 Pure-Python simulator of classical CPU branch predictors for computer architecture education.
 
-Implements four predictors from first principles with zero runtime dependencies:
+Implements five 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.
+- **Local-history / PAg** (Yeh and Patt 1991) -- a per-branch local history table feeds a shared pattern history table, learning periodic per-branch patterns that a bimodal predictor thrashes on.
 
 Part of the same open-source computer architecture education series as [tomasulo](https://github.com/amaar-mc/tomasulo) (out-of-order execution) and scoreboarding.
 
@@ -21,18 +22,11 @@ Part of the same open-source computer architecture education series as [tomasulo
 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 LocalHistoryPredictor
 from bpred import run_trace, accuracy, mispredictions
 
 # Bimodal: 2-bit counters, 1024-entry table
@@ -50,6 +44,9 @@ pred = TournamentPredictor(local=local, global_=global_, meta_bits=2)
 # Perceptron: 12-bit history, 1024-entry table
 pred = PerceptronPredictor(history_length=12, table_size=1024)
 
+# Local-history (PAg): 8-bit per-branch history, 1024-entry BHT, 256-entry PHT
+pred = LocalHistoryPredictor(history_bits=8, bht_size=1024, pht_size=256)
+
 # Feed a trace
 trace = [(0x1000, True), (0x1004, False), (0x1008, True)]
 result = run_trace(pred, trace=trace)
@@ -73,11 +70,30 @@ 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).
 
+### Why use the local-history (PAg) predictor?
+
+Bimodal predicts each branch from a single counter, so a branch whose outcome
+follows a short repeating pattern -- the textbook `T, N, T, N, ...` of a loop
+that runs an even number of times, for example -- makes the counter oscillate
+and the predictor thrashes near 50%.
+
+The local-history predictor (the PAg configuration of Yeh and Patt's two-level
+adaptive scheme, 1991) gives every branch its own N-bit shift register of
+recent outcomes in a branch history table (BHT).  That local pattern then
+indexes a shared pattern history table (PHT) of 2-bit counters, so each
+distinct recent-history pattern gets its own counter.  A period-k pattern is
+learned to near-100% accuracy once `history_bits >= k`, because each phase of
+the period maps to a different PHT entry.  The first level is per-address
+(`P`), the training is adaptive (`A`), and the second-level PHT is global
+(`g`), which is what the name PAg encodes.  The per-address-PHT variant (PAp)
+is a natural extension left as future work.
+
 ## 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 local --history-bits 8 --bht-size 1024 --pht-size 256 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 \

{bpred-0.2.0 → bpred-0.3.0}/pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "hatchling.build"
 
 [project]
 name = "bpred"
-version = "0.2.0"
-description = "Pure-Python simulator of classical CPU branch predictors: bimodal, gshare, and tournament"
+version = "0.3.0"
+description = "Pure-Python simulator of classical CPU branch predictors: bimodal, gshare, tournament, perceptron, and local-history"
 readme = "README.md"
 license = {file = "LICENSE"}
 authors = [{name = "Amaar Chughtai", email = "amaardevx@gmail.com"}]
-keywords = ["computer-architecture", "branch-prediction", "gshare", "bimodal", "cpu-simulator", "education"]
+keywords = ["computer-architecture", "branch-prediction", "gshare", "bimodal", "perceptron", "two-level-adaptive", "cpu-simulator", "education"]
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Education",

{bpred-0.2.0 → bpred-0.3.0}/src/bpred/__init__.py

@@ -1,6 +1,6 @@
 """bpred -- Pure-Python CPU branch predictor simulator.
 
-Provides four classical branch predictors and trace-driven simulation
+Provides five classical branch predictors and trace-driven simulation
 utilities for computer architecture education.
 
 Predictors
@@ -13,6 +13,8 @@ TournamentPredictor
     McFarling (1993) / Alpha 21264-style meta-selecting predictor.
 PerceptronPredictor
     Jimenez and Lin (2001) table of integer-weight perceptrons.
+LocalHistoryPredictor
+    Yeh and Patt (1991) PAg two-level adaptive local-history predictor.
 
 Functions
 ---------
@@ -26,6 +28,7 @@ mispredictions(*, trace_result)
 
 from bpred.bimodal import BimodalPredictor
 from bpred.gshare import GsharePredictor
+from bpred.local_history import LocalHistoryPredictor
 from bpred.perceptron import PerceptronPredictor
 from bpred.tournament import TournamentPredictor
 from bpred.trace import TraceResult, accuracy, mispredictions, run_trace
@@ -33,6 +36,7 @@ from bpred.trace import TraceResult, accuracy, mispredictions, run_trace
 __all__ = [
     "BimodalPredictor",
     "GsharePredictor",
+    "LocalHistoryPredictor",
     "PerceptronPredictor",
     "TournamentPredictor",
     "TraceResult",

{bpred-0.2.0 → bpred-0.3.0}/src/bpred/cli.py

@@ -9,6 +9,7 @@ from pathlib import Path
 from bpred import (
     BimodalPredictor,
     GsharePredictor,
+    LocalHistoryPredictor,
     TournamentPredictor,
     accuracy,
     mispredictions,
@@ -83,6 +84,17 @@ def _build_parser() -> argparse.ArgumentParser:
     gshare.add_argument("--table-size", type=int, required=True)
     gshare.add_argument("tracefile", type=Path)
 
+    # ------------------------------------------------------------------
+    # local (PAg)
+    # ------------------------------------------------------------------
+    local_p = sub.add_parser(
+        "local", help="Local-history PAg (Yeh and Patt 1991) predictor"
+    )
+    local_p.add_argument("--history-bits", type=int, required=True)
+    local_p.add_argument("--bht-size", type=int, required=True)
+    local_p.add_argument("--pht-size", type=int, required=True)
+    local_p.add_argument("tracefile", type=Path)
+
     # ------------------------------------------------------------------
     # tournament
     # ------------------------------------------------------------------
@@ -121,6 +133,12 @@ def _build_predictor(args: argparse.Namespace) -> BranchPredictor:
             history_bits=args.history_bits,
             table_size=args.table_size,
         )
+    if args.predictor == "local":
+        return LocalHistoryPredictor(
+            history_bits=args.history_bits,
+            bht_size=args.bht_size,
+            pht_size=args.pht_size,
+        )
     if args.predictor == "tournament":
         local: BranchPredictor = BimodalPredictor(
             counter_bits=args.local_counter_bits,

bpred-0.3.0/src/bpred/local_history.py

@@ -0,0 +1,161 @@
+"""Local-history two-level adaptive branch predictor (PAg).
+
+Reference: T.-Y. Yeh and Y. N. Patt, "Two-Level Adaptive Training Branch
+Prediction," in Proceedings of the 24th Annual International Symposium on
+Microarchitecture (MICRO 24), pp. 51-61, 1991.
+
+This implements the PAg configuration of the Yeh and Patt two-level scheme:
+
+- A *per-address* branch history table (BHT) indexed by PC.  Each BHT entry is
+  an N-bit shift register holding the recent taken/not-taken outcomes of that
+  specific branch (P = per-address first level).
+- A single *global* pattern history table (PHT) of 2-bit saturating counters,
+  shared across all branches and indexed by the local history pattern read from
+  the BHT (g = global second level).
+
+The "PAg" name decodes as: P (per-address first level) A (adaptive) g (global
+second level).  Contrast with the per-address second level "PAp" variant, noted
+as future work below.
+
+Indexing
+--------
+The local history register is an integer in [0, 2^history_bits - 1].  The BHT
+is indexed by ``pc % bht_size``.  The PHT is indexed by ``history % pht_size``;
+with the natural sizing ``pht_size == 2**history_bits`` this is a direct,
+collision-free mapping from every distinct history pattern to its own counter.
+
+PAp (future work)
+-----------------
+A PAp predictor gives each branch its own private PHT instead of sharing one
+global PHT.  That is a strict generalisation (a 2-D PHT indexed by branch and
+then by pattern) and is intentionally out of scope here to keep PAg focused.
+"""
+
+from __future__ import annotations
+
+from bpred.counter import SaturatingCounter
+
+_COUNTER_BITS = 2
+
+
+class LocalHistoryPredictor:
+    """Two-level adaptive predictor with per-branch local history (PAg).
+
+    Each branch has its own ``history_bits``-wide local history register stored
+    in the branch history table (BHT).  A single shared pattern history table
+    (PHT) of 2-bit saturating counters is indexed by that local history pattern.
+
+    predict(pc):
+        Read the branch's local history, index the PHT with it, and predict
+        taken iff the selected counter is in a taken state.
+
+    update(pc, taken):
+        Update the indexed PHT counter with the actual outcome, then shift the
+        outcome into that branch's local history register (most recent outcome
+        in the least-significant bit).
+    """
+
+    _bht: list[int]
+    _pht: list[SaturatingCounter]
+    _history_bits: int
+    _bht_size: int
+    _pht_size: int
+    _history_mask: int
+
+    def __init__(self, *, history_bits: int, bht_size: int, pht_size: int) -> None:
+        """Create a LocalHistoryPredictor (PAg).
+
+        Args:
+            history_bits: Width N of each per-branch local history register.
+                Must be >= 1.
+            bht_size:     Number of entries in the branch history table (BHT).
+                Must be >= 1.  Indexed by ``pc % bht_size``.
+            pht_size:     Number of 2-bit counters in the shared pattern history
+                table (PHT).  Must be >= 1.  Indexed by ``history % pht_size``;
+                use ``2**history_bits`` for a collision-free mapping.
+        """
+        if history_bits < 1:
+            raise ValueError(f"history_bits must be >= 1, got {history_bits}")
+        if bht_size < 1:
+            raise ValueError(f"bht_size must be >= 1, got {bht_size}")
+        if pht_size < 1:
+            raise ValueError(f"pht_size must be >= 1, got {pht_size}")
+
+        self._history_bits = history_bits
+        self._bht_size = bht_size
+        self._pht_size = pht_size
+        self._history_mask = (1 << history_bits) - 1
+        # All local histories start empty (all not-taken).
+        self._bht = [0] * bht_size
+        # All PHT counters start weakly taken (neutral).
+        initial = 1 << (_COUNTER_BITS - 1)
+        self._pht = [
+            SaturatingCounter(bits=_COUNTER_BITS, initial=initial)
+            for _ in range(pht_size)
+        ]
+
+    # ------------------------------------------------------------------
+    # Properties
+    # ------------------------------------------------------------------
+
+    @property
+    def history_bits(self) -> int:
+        """Width N of each per-branch local history register."""
+        return self._history_bits
+
+    @property
+    def bht_size(self) -> int:
+        """Number of entries in the branch history table."""
+        return self._bht_size
+
+    @property
+    def pht_size(self) -> int:
+        """Number of counters in the shared pattern history table."""
+        return self._pht_size
+
+    @property
+    def table_size(self) -> int:
+        """Pattern history table size (satisfies the BranchPredictor protocol)."""
+        return self._pht_size
+
+    # ------------------------------------------------------------------
+    # Internal helpers
+    # ------------------------------------------------------------------
+
+    def _bht_index(self, *, pc: int) -> int:
+        """BHT index: pc mod bht_size."""
+        return pc % self._bht_size
+
+    def _local_history(self, *, pc: int) -> int:
+        """Return the local history pattern for the branch at *pc*."""
+        return self._bht[self._bht_index(pc=pc)]
+
+    def _pht_index(self, *, history: int) -> int:
+        """PHT index: history mod pht_size."""
+        return history % self._pht_size
+
+    def _shift_history(self, *, pc: int, taken: bool) -> None:
+        """Shift *taken* into the LSB of the branch's local history register."""
+        idx = self._bht_index(pc=pc)
+        self._bht[idx] = ((self._bht[idx] << 1) | int(taken)) & self._history_mask
+
+    # ------------------------------------------------------------------
+    # Public interface
+    # ------------------------------------------------------------------
+
+    def predict(self, *, pc: int) -> bool:
+        """Return the taken prediction for the branch at *pc*."""
+        history = self._local_history(pc=pc)
+        return self._pht[self._pht_index(history=history)].predict()
+
+    def update(self, *, pc: int, taken: bool) -> None:
+        """Update the PHT counter, then shift the outcome into local history."""
+        history = self._local_history(pc=pc)
+        self._pht[self._pht_index(history=history)].update(taken=taken)
+        self._shift_history(pc=pc, taken=taken)
+
+    def __repr__(self) -> str:
+        return (
+            f"LocalHistoryPredictor(history_bits={self._history_bits}, "
+            f"bht_size={self._bht_size}, pht_size={self._pht_size})"
+        )

bpred-0.3.0/tests/test_local_history.py

@@ -0,0 +1,259 @@
+"""Tests for LocalHistoryPredictor (PAg, Yeh and Patt 1991)."""
+
+from bpred.bimodal import BimodalPredictor
+from bpred.local_history import LocalHistoryPredictor
+from bpred.trace import accuracy, run_trace
+
+# ------------------------------------------------------------------
+# Local history register behaviour
+# ------------------------------------------------------------------
+
+
+def test_local_history_starts_empty() -> None:
+    """Every BHT entry starts at 0 (no recorded outcomes)."""
+    p = LocalHistoryPredictor(history_bits=4, bht_size=8, pht_size=16)
+    for pc in range(8):
+        assert p._local_history(pc=pc) == 0  # noqa: SLF001
+
+
+def test_local_history_shifts_lsb_first() -> None:
+    """Outcomes shift into the LSB of the per-branch history register."""
+    p = LocalHistoryPredictor(history_bits=4, bht_size=8, pht_size=16)
+    p.update(pc=0, taken=True)
+    assert p._local_history(pc=0) == 0b0001  # noqa: SLF001
+    p.update(pc=0, taken=True)
+    assert p._local_history(pc=0) == 0b0011  # noqa: SLF001
+    p.update(pc=0, taken=False)
+    assert p._local_history(pc=0) == 0b0110  # noqa: SLF001
+    p.update(pc=0, taken=True)
+    assert p._local_history(pc=0) == 0b1101  # noqa: SLF001
+
+
+def test_local_history_capped_at_history_bits() -> None:
+    """A branch's local history never exceeds 2^history_bits - 1."""
+    p = LocalHistoryPredictor(history_bits=3, bht_size=4, pht_size=8)
+    mask = (1 << 3) - 1
+    for _ in range(10):
+        p.update(pc=0, taken=True)
+        assert p._local_history(pc=0) <= mask  # noqa: SLF001
+
+
+def test_per_branch_history_is_independent() -> None:
+    """Two branches that map to distinct BHT entries keep separate histories."""
+    p = LocalHistoryPredictor(history_bits=4, bht_size=8, pht_size=16)
+    p.update(pc=0, taken=True)
+    p.update(pc=1, taken=False)
+    assert p._local_history(pc=0) == 0b0001  # noqa: SLF001
+    assert p._local_history(pc=1) == 0b0000  # noqa: SLF001
+
+
+# ------------------------------------------------------------------
+# Periodic pattern learning (the PAg headline capability)
+# ------------------------------------------------------------------
+
+
+def test_alternating_pattern_beats_bimodal() -> None:
+    """A strict alternating T,N,T,N,... trace is learned to high accuracy.
+
+    With one bit of local history the PAg predictor distinguishes the two
+    phases of the period and reaches ~100% accuracy after warm-up.  A bimodal
+    predictor with a single counter is stuck near 50% because it has no
+    history and always predicts the majority class.
+    """
+    n = 400
+    alternating_trace = [(0x300, i % 2 == 0) for i in range(n)]
+
+    local = LocalHistoryPredictor(history_bits=1, bht_size=4, pht_size=2)
+    bimod = BimodalPredictor(counter_bits=2, table_size=1)
+
+    local_acc = accuracy(trace_result=run_trace(local, trace=alternating_trace))
+    bimod_acc = accuracy(trace_result=run_trace(bimod, trace=alternating_trace))
+
+    assert local_acc > 0.95, f"local accuracy too low: {local_acc:.3f}"
+    assert bimod_acc <= 0.55, f"bimodal unexpectedly good: {bimod_acc:.3f}"
+    assert local_acc > bimod_acc, (
+        f"local ({local_acc:.3f}) did not beat bimodal ({bimod_acc:.3f})"
+    )
+
+
+def test_length_k_pattern_captured_when_history_bits_ge_k() -> None:
+    """A length-k periodic pattern is learned once history_bits >= k.
+
+    Pattern of period 4: T, T, N, N repeating.  Predicting the next outcome
+    from the previous k outcomes requires distinguishing all positions in the
+    period, which needs at least k history bits.  With history_bits == 4 the
+    PAg predictor reaches near-perfect accuracy after warm-up.
+    """
+    period = [True, True, False, False]
+    k = len(period)
+    n = 400
+    trace = [(0x400, period[i % k]) for i in range(n)]
+
+    p = LocalHistoryPredictor(history_bits=k, bht_size=4, pht_size=1 << k)
+    acc = accuracy(trace_result=run_trace(p, trace=trace))
+    assert acc > 0.95, f"period-{k} pattern not learned: {acc:.3f}"
+
+
+def test_short_history_cannot_capture_long_period() -> None:
+    """history_bits below the period leaves the predictor unable to separate
+    distinct phases that share the same short suffix.
+
+    Period 4 pattern T,T,N,N with only 1 history bit: the suffixes '...T' and
+    '...N' each precede both a same and a different outcome, so a single shared
+    counter per pattern cannot reach the near-perfect accuracy of the
+    full-history case.
+    """
+    period = [True, True, False, False]
+    n = 400
+    trace = [(0x500, period[i % 4]) for i in range(n)]
+
+    short = LocalHistoryPredictor(history_bits=1, bht_size=4, pht_size=2)
+    full = LocalHistoryPredictor(history_bits=4, bht_size=4, pht_size=16)
+
+    short_acc = accuracy(trace_result=run_trace(short, trace=trace))
+    full_acc = accuracy(trace_result=run_trace(full, trace=trace))
+
+    assert full_acc > 0.95
+    assert short_acc < full_acc
+
+
+# ------------------------------------------------------------------
+# Strongly-biased branches
+# ------------------------------------------------------------------
+
+
+def test_always_taken_eventually_accurate() -> None:
+    """An always-taken branch reaches high accuracy after warm-up."""
+    p = LocalHistoryPredictor(history_bits=4, bht_size=16, pht_size=16)
+    trace = [(0x100, True)] * 50
+    acc = accuracy(trace_result=run_trace(p, trace=trace))
+    assert acc >= 0.9
+
+
+def test_always_not_taken_eventually_accurate() -> None:
+    """An always-not-taken branch reaches high accuracy after warm-up."""
+    p = LocalHistoryPredictor(history_bits=4, bht_size=16, pht_size=16)
+    trace = [(0x200, False)] * 50
+    acc = accuracy(trace_result=run_trace(p, trace=trace))
+    assert acc >= 0.9
+
+
+# ------------------------------------------------------------------
+# Counter saturation through the PHT
+# ------------------------------------------------------------------
+
+
+def test_pht_counter_saturates() -> None:
+    """Repeated taken outcomes drive the indexed PHT counter to its max."""
+    # history_bits=1, so an always-taken branch settles on history pattern 1
+    # and repeatedly hits PHT[1], saturating it at max_value (3 for 2-bit).
+    p = LocalHistoryPredictor(history_bits=1, bht_size=4, pht_size=2)
+    for _ in range(10):
+        p.update(pc=0, taken=True)
+    assert p._pht[1].value == p._pht[1].max_value  # noqa: SLF001
+    assert p._pht[1].value == 3  # noqa: SLF001
+
+
+def test_pht_starts_weakly_taken() -> None:
+    """All PHT counters start in the weakly-taken neutral state (value 2)."""
+    p = LocalHistoryPredictor(history_bits=2, bht_size=4, pht_size=4)
+    for counter in p._pht:  # noqa: SLF001
+        assert counter.value == 2
+        assert counter.predict() is True
+
+
+# ------------------------------------------------------------------
+# Table sizing
+# ------------------------------------------------------------------
+
+
+def test_tables_sized_as_documented() -> None:
+    """BHT and PHT are sized exactly as requested."""
+    p = LocalHistoryPredictor(history_bits=3, bht_size=8, pht_size=8)
+    assert len(p._bht) == 8  # noqa: SLF001
+    assert len(p._pht) == 8  # noqa: SLF001
+    assert p.history_bits == 3
+    assert p.bht_size == 8
+    assert p.pht_size == 8
+    assert p.table_size == 8
+
+
+# ------------------------------------------------------------------
+# Interface conformance
+# ------------------------------------------------------------------
+
+
+def test_predict_returns_bool() -> None:
+    """predict() must return bool, matching the BranchPredictor protocol."""
+    p = LocalHistoryPredictor(history_bits=4, bht_size=16, pht_size=16)
+    assert isinstance(p.predict(pc=0x1000), bool)
+
+
+def test_update_returns_none() -> None:
+    """update() must return None."""
+    p = LocalHistoryPredictor(history_bits=4, bht_size=16, pht_size=16)
+    assert p.update(pc=0x1000, taken=True) is None
+
+
+def test_run_trace_compatible() -> None:
+    """LocalHistoryPredictor is accepted by run_trace (protocol conformance)."""
+    p = LocalHistoryPredictor(history_bits=4, bht_size=16, pht_size=16)
+    trace = [(0x100, True), (0x104, False), (0x108, True)]
+    result = run_trace(p, trace=trace)
+    assert result.total == 3
+    assert len(result.predictions) == 3
+    assert all(isinstance(pred, bool) for pred in result.predictions)
+
+
+def test_deterministic() -> None:
+    """Same trace produces identical results on two fresh predictors."""
+    trace = [(i * 8, i % 3 != 0) for i in range(40)]
+    p1 = LocalHistoryPredictor(history_bits=4, bht_size=16, pht_size=16)
+    p2 = LocalHistoryPredictor(history_bits=4, bht_size=16, pht_size=16)
+    r1 = run_trace(p1, trace=trace)
+    r2 = run_trace(p2, trace=trace)
+    assert r1.predictions == r2.predictions
+    assert r1.correct == r2.correct
+    assert r1.hits == r2.hits
+
+
+# ------------------------------------------------------------------
+# Validation
+# ------------------------------------------------------------------
+
+
+def test_invalid_history_bits_raises() -> None:
+    """history_bits < 1 must raise ValueError."""
+    try:
+        LocalHistoryPredictor(history_bits=0, bht_size=4, pht_size=4)
+        assert False, "expected ValueError"
+    except ValueError:
+        pass
+
+
+def test_invalid_bht_size_raises() -> None:
+    """bht_size < 1 must raise ValueError."""
+    try:
+        LocalHistoryPredictor(history_bits=4, bht_size=0, pht_size=4)
+        assert False, "expected ValueError"
+    except ValueError:
+        pass
+
+
+def test_invalid_pht_size_raises() -> None:
+    """pht_size < 1 must raise ValueError."""
+    try:
+        LocalHistoryPredictor(history_bits=4, bht_size=4, pht_size=0)
+        assert False, "expected ValueError"
+    except ValueError:
+        pass
+
+
+def test_repr() -> None:
+    """__repr__ includes class name and all three parameters."""
+    p = LocalHistoryPredictor(history_bits=4, bht_size=16, pht_size=16)
+    r = repr(p)
+    assert "LocalHistoryPredictor" in r
+    assert "history_bits=4" in r
+    assert "bht_size=16" in r
+    assert "pht_size=16" in r