bpred 0.2.0__tar.gz

bpred-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,22 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy src
+      - run: pytest -q

bpred-0.2.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.cache/
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+htmlcov/
+.coverage
+coverage.xml
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# uv
+uv.lock
+
+# Distribution / packaging
+*.tar.gz
+*.whl
+MANIFEST
+
+# IDEs
+.idea/
+.vscode/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store

bpred-0.2.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+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.2.0] - 2026-06-17
+
+### Added
+
+- `PerceptronPredictor`: Jimenez and Lin (2001) table of integer-weight perceptrons.
+  Captures linearly-separable history patterns that bimodal and gshare cannot learn.
+  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
+
+- `SaturatingCounter`: n-bit saturating counter building block.
+- `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.
+- `run_trace`, `accuracy`, `mispredictions`: trace-driven simulation utilities.
+- `bpred` CLI supporting bimodal, gshare, and tournament subcommands.
+- Full mypy strict and ruff linting.
+- CI on Python 3.10, 3.11, 3.12, 3.13.

bpred-0.2.0/CLAUDE.md

@@ -0,0 +1,59 @@
+# bpred -- Project Instructions
+
+## What this is
+
+Pure-Python simulator of classical CPU branch predictors (bimodal, gshare,
+tournament). Zero runtime dependencies. Target: Python 3.10+.
+
+## Source layout
+
+```
+src/bpred/
+  counter.py    -- SaturatingCounter (shared building block)
+  bimodal.py    -- BimodalPredictor
+  gshare.py     -- GsharePredictor
+  tournament.py -- TournamentPredictor + BranchPredictor protocol
+  trace.py      -- run_trace, accuracy, mispredictions, TraceResult
+  cli.py        -- argparse CLI entry point
+  __init__.py   -- public re-exports
+  py.typed      -- PEP 561 marker
+tests/
+  test_counter.py    -- golden FSM values + property tests for counter
+  test_bimodal.py
+  test_gshare.py
+  test_tournament.py
+  test_property.py   -- property-style exhaustive tests
+  test_trace.py
+```
+
+## Conventions
+
+- No default parameter values anywhere. All parameters are keyword-only.
+- Strict mypy passes on all files in src/.
+- ruff lint set: E, F, I, UP, ANN.
+- No runtime dependencies (stdlib only).
+- No em dash characters in any file.
+- Commits: `type(scope): description`. No Co-authored-by trailers.
+
+## Running checks
+
+```bash
+pytest -q
+ruff check .
+mypy src
+uv build
+uv run --with twine twine check dist/*
+```
+
+## Predictor invariants
+
+- SaturatingCounter value always stays in [0, max_value].
+- predict() is a pure function of current state.
+- Gshare GHR is updated AFTER recording the prediction.
+- Tournament: chooser updated only when sub-predictors disagree.
+- Tournament: both sub-predictors always updated regardless of chooser.
+
+## What NOT to assert in tests
+
+Do NOT assert that tournament is never worse than both sub-predictors on a
+single prediction. A meta-selector can choose the wrong sub-predictor.

bpred-0.2.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Code of Conduct
+
+## Our Pledge
+
+We as contributors and maintainers pledge to make participation in this project
+a harassment-free experience for everyone, regardless of age, body size,
+disability, ethnicity, sex characteristics, gender identity and expression,
+level of experience, education, socioeconomic status, nationality, personal
+appearance, race, religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behaviour that contributes to a positive environment:
+
+- Using welcoming and inclusive language.
+- Being respectful of differing viewpoints and experiences.
+- Gracefully accepting constructive criticism.
+- Focusing on what is best for the community.
+- Showing empathy toward other community members.
+
+Examples of unacceptable behaviour:
+
+- The use of sexualised language or imagery.
+- Trolling, insulting or derogatory comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information without explicit permission.
+- Other conduct which could reasonably be considered inappropriate in a
+  professional setting.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behaviour may be
+reported by opening a GitHub issue or contacting the maintainer directly.
+All complaints will be reviewed and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

bpred-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thank you for your interest in contributing to `bpred`.
+
+## Setup
+
+```bash
+git clone https://github.com/amaar-mc/bpred
+cd bpred
+pip install -e ".[dev]"
+```
+
+## Running checks
+
+```bash
+pytest -q          # tests
+ruff check .       # linting
+mypy src           # type checking
+```
+
+All three must pass before opening a pull request.
+
+## Guidelines
+
+- Zero runtime dependencies. All new code must work with the Python standard
+  library only.
+- Strict typing. All public functions must have complete type annotations, and
+  `mypy --strict` must pass.
+- No default parameter values on public APIs. All parameters must be explicit
+  keyword arguments.
+- Test behaviour, not implementation. New predictors must come with tests
+  covering correctness on structured traces, not just "it ran without crashing."
+- Bug fixes: add a failing test first, then fix the bug.
+
+## Pull requests
+
+- Open an issue first for significant changes.
+- Keep commits focused. One logical change per commit.
+- Commit message format: `type(scope): description` (e.g.
+  `feat(gshare): add history_bits validation`).
+- Do not add `Co-authored-by` trailers or automated tool footers.
+
+## Code of Conduct
+
+See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).

bpred-0.2.0/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.

bpred-0.2.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,122 @@
+# 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/SECURITY.md

@@ -0,0 +1,22 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+`bpred` is a pure-Python educational simulator with zero runtime dependencies
+and no network access, secrets handling, or persistent storage. The attack
+surface is minimal.
+
+If you discover a security vulnerability (for example, a path traversal issue
+in the CLI trace-file parser), please report it by opening a GitHub issue
+marked with the `security` label. For sensitive matters that should not be
+public, contact the maintainer directly via the email address listed in
+`pyproject.toml`.
+
+We aim to acknowledge reports within 72 hours and to release a fix within
+14 days for confirmed vulnerabilities.

bpred-0.2.0/docs/architecture.md

@@ -0,0 +1,101 @@
+# Predictor Architecture
+
+This document describes the three branch predictors implemented in `bpred`,
+their algorithmic basis, and the primary academic references.
+
+## References
+
+- J. E. Smith, "A study of branch prediction strategies," in _Proceedings of
+  the 8th Annual Symposium on Computer Architecture (ISCA)_, pp. 135-148, 1981.
+- S. McFarling, "Combining Branch Predictors," WRL Technical Note TN-36,
+  Digital Equipment Corporation Western Research Laboratory, June 1993.
+
+---
+
+## Saturating Counter
+
+A saturating counter is the base component of all three predictors. An n-bit
+counter holds a value in [0, 2^n - 1]. It predicts _taken_ when the value is
+>= 2^(n-1) and _not-taken_ otherwise. Taken outcomes increment the counter
+toward the maximum; not-taken outcomes decrement it toward zero. At either
+extreme the counter saturates rather than wrapping.
+
+The 2-bit variant (n=2) is the classic design from Smith (1981). Its four
+states are:
+
+| Value | Name            | Predict |
+|-------|-----------------|---------|
+| 0     | Strongly Not-Taken (SN) | not-taken |
+| 1     | Weakly Not-Taken (WN)   | not-taken |
+| 2     | Weakly Taken (WT)       | taken |
+| 3     | Strongly Taken (ST)     | taken |
+
+Two consecutive mispredictions are required to flip the prediction, providing
+hysteresis against noise.
+
+---
+
+## Bimodal Predictor
+
+**Reference:** Smith (1981).
+
+A flat table of `table_size` saturating counters of `counter_bits` bits each.
+The table is indexed by `pc mod table_size`. On every branch:
+
+1. Predict using the counter at index `pc mod table_size`.
+2. Update that counter with the actual outcome.
+
+Multiple branches whose PCs map to the same entry share a counter (aliasing).
+Larger tables reduce aliasing at the cost of hardware area.
+
+---
+
+## Gshare Predictor
+
+**Reference:** McFarling (1993).
+
+Gshare extends the bimodal idea by incorporating global correlation. A global
+history register (GHR) of `history_bits` bits records the outcomes of the most
+recent branches across the entire program. The table index is:
+
+```
+index = (pc XOR ghr) mod table_size
+```
+
+Each entry is a 2-bit saturating counter. After every branch the actual
+outcome is shifted into the GHR (MSB first), discarding outcomes older than
+`history_bits`.
+
+XOR hashing distributes entries more uniformly across the table than either
+PC or GHR alone, and exploits cross-branch correlation to improve accuracy
+on correlated loops and function-call patterns.
+
+---
+
+## Tournament Predictor
+
+**Reference:** McFarling (1993); Alpha 21264 implementation.
+
+A tournament predictor combines two sub-predictors (a local and a global) using
+a meta-selector table. The meta-selector contains saturating counters of
+`meta_bits` bits that choose which sub-predictor to trust for each PC.
+
+### Prediction
+
+1. Look up the chooser counter at `pc mod chooser_size`.
+2. If counter value < threshold (2^(meta_bits - 1)), use the _local_ predictor.
+3. Otherwise use the _global_ predictor.
+
+### Update (Alpha 21264 scheme)
+
+Both sub-predictors are always updated with the actual outcome. The chooser is
+updated only when the two sub-predictors _disagree_:
+
+- If only the local predictor was correct: decrement the chooser (bias toward local).
+- If only the global predictor was correct: increment the chooser (bias toward global).
+- If both or neither was correct: no chooser update.
+
+This approach concentrates meta-selector learning signal on cases where the
+choice actually matters.
+
+The chooser table size equals `max(local.table_size, global_.table_size)`.