scoreboarding 0.1.0__tar.gz

scoreboarding-0.1.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,22 @@
+---
+name: Bug report
+about: Report a bug in the simulator
+labels: bug
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**Program / input**
+Paste the program text (FU declarations + instructions) that triggers the bug.
+
+**Expected behavior**
+What cycle numbers did you expect (show your hand derivation if possible)?
+
+**Actual behavior**
+What cycle numbers did the simulator produce?
+
+**Environment**
+- scoreboarding version:
+- Python version:
+- OS:

scoreboarding-0.1.0/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,17 @@
+---
+name: Feature request
+about: Suggest a new feature or improvement
+labels: enhancement
+---
+
+**Is your feature request related to a problem?**
+A clear and concise description of the problem.
+
+**Proposed solution**
+Describe the feature or change you would like.
+
+**Alternatives considered**
+Any alternative approaches you considered.
+
+**Additional context**
+Any other context, references, or examples.

scoreboarding-0.1.0/.github/workflows/ci.yml

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

scoreboarding-0.1.0/.gitignore

@@ -0,0 +1,40 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+uv.lock
+
+# mypy
+.mypy_cache/
+*.pyi
+
+# pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# ruff
+.ruff_cache/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db

scoreboarding-0.1.0/CHANGELOG.md

@@ -0,0 +1,27 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-06-17
+
+### Added
+- `FunctionalUnit`, `Instruction`, `Trace`, `InstructionResult`, `CycleSnapshot` data
+  model in `src/scoreboarding/model.py`.
+- Cycle-exact Scoreboarding engine in `src/scoreboarding/engine.py` implementing all
+  four stages (Issue, Read Operands, Execute, Write Result) with structural, RAW, WAR,
+  and WAW hazard detection.
+- `render_trace()` timing-table renderer.
+- `scoreboarding` CLI with `--snapshots` flag for per-cycle state dumps.
+- 50 tests covering golden trace, in-order issue invariant, all four hazard types,
+  simulation termination, and error handling.
+- `examples/classic.txt` -- the classic CDC 6600 floating-point scheduling example.
+- CI on Python 3.10, 3.11, 3.12, 3.13 via GitHub Actions.
+- PyPI release pending (package-upload quota exhausted at release time; will follow).
+
+[Unreleased]: https://github.com/amaar-mc/scoreboarding/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/amaar-mc/scoreboarding/releases/tag/v0.1.0

scoreboarding-0.1.0/CLAUDE.md

@@ -0,0 +1,53 @@
+# CLAUDE.md -- scoreboarding
+
+## Project
+
+Pure-Python cycle-exact Thornton Scoreboarding (CDC 6600) simulator.
+Companion to `tomasulo` (out-of-order with register renaming).
+
+## Layout
+
+```
+src/scoreboarding/
+  model.py      -- dataclasses: FunctionalUnit, Instruction, FunctionalUnitStatus,
+                   InstructionStatus, InstructionResult, CycleSnapshot, Trace
+  engine.py     -- the simulation engine (four stages, three tables)
+  render.py     -- render_trace() timing-table formatter
+  cli.py        -- scoreboarding CLI: run(argv) + main()
+  __init__.py   -- public API re-exports
+  py.typed      -- PEP 561 marker
+tests/
+  test_engine.py  -- golden trace + all hazard invariants (30 tests)
+  test_cli.py     -- CLI parse + run tests (14 tests)
+  test_render.py  -- render output tests (6 tests)
+```
+
+## Dev gates (must all pass)
+
+```bash
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+uv build
+uv run --with twine twine check dist/*
+```
+
+## Key constraints
+
+- mypy strict: no `Any`, no missing annotations.
+- No default parameter values in public API; use keyword-only args.
+- No em dashes in source or docs (use -- or plain dashes).
+- No TODO/FIXME in code.
+- ruff: line-length=100, selectors E,F,I,UP,B,SIM,RUF.
+- Zero runtime deps.
+
+## Algorithm
+
+Four stages: Issue (structural + WAW check), Read Operands (RAW wait),
+Execute (latency countdown), Write Result (WAR check then broadcast).
+See docs/architecture.md for the full description.
+
+## PyPI
+
+Not yet published (quota exhausted at initial release). `uv build && twine check dist/*`
+to validate the distribution. Publish when quota resets.

scoreboarding-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,32 @@
+# Code of Conduct
+
+## Our Pledge
+
+We are committed to making participation in this project a harassment-free experience
+for everyone, regardless of age, body size, disability, ethnicity, gender identity and
+expression, level of experience, nationality, personal appearance, race, religion, or
+sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior 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
+
+Examples of unacceptable behavior:
+- Harassment, trolling, or personal attacks
+- Publishing others' private information without consent
+- Other conduct which could reasonably be considered inappropriate
+
+## Enforcement
+
+Instances of abusive or unacceptable behavior may be reported by opening a GitHub
+issue or contacting the maintainer directly. All complaints will be reviewed and
+investigated and will result in a response that is deemed necessary and appropriate.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

scoreboarding-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,37 @@
+# Contributing
+
+Contributions are welcome. Please open an issue before submitting large changes.
+
+## Development setup
+
+```bash
+git clone https://github.com/amaar-mc/scoreboarding
+cd scoreboarding
+uv venv .venv
+uv pip install -e ".[dev]"
+```
+
+## Quality gates (all must pass)
+
+```bash
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+uv build
+```
+
+## Code style
+
+- Python 3.10+, strict mypy, ruff lint.
+- No default parameter values in public API functions -- use keyword-only arguments.
+- No `TODO` or `FIXME` in committed code -- implement or note the omission in an issue.
+- Commit format: `type(scope): description`.
+
+## Testing
+
+New behaviour must be accompanied by tests. Bug fixes must include a failing test
+that demonstrates the bug before the fix is applied.
+
+## License
+
+By contributing you agree that your changes are licensed under the MIT License.

scoreboarding-0.1.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.

scoreboarding-0.1.0/PKG-INFO

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: scoreboarding
+Version: 0.1.0
+Summary: Pure-Python cycle-exact simulator of Thornton's Scoreboarding (CDC 6600) in-order dynamic scheduling, with structural, WAR, and WAW hazard detection and per-instruction traces for computer architecture education.
+Project-URL: Homepage, https://github.com/amaar-mc/scoreboarding
+Project-URL: Repository, https://github.com/amaar-mc/scoreboarding
+Project-URL: Issues, https://github.com/amaar-mc/scoreboarding/issues
+Project-URL: Changelog, https://github.com/amaar-mc/scoreboarding/blob/main/CHANGELOG.md
+Author: Amaar Chughtai
+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: cdc-6600,computer-architecture,cpu-simulator,education,hazards,in-order,instruction-scheduling,pipeline,scoreboarding,simulation
+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: hatchling>=1.25; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# scoreboarding
+
+<p align="center">
+  <img src="assets/logo.png" alt="scoreboarding logo" width="160">
+</p>
+
+Pure-Python cycle-exact simulator of Thornton's **Scoreboarding** algorithm,
+as implemented in the CDC 6600 (1964). Designed for computer architecture
+education: readable source, zero runtime dependencies, and per-instruction
+cycle-number traces.
+
+> PyPI publish pending (package-upload quota). `pip install scoreboarding`
+> will work once the first release is live. Install from source in the meantime.
+
+---
+
+## What is Scoreboarding?
+
+Scoreboarding is an **in-order issue, out-of-order execution** dynamic
+scheduling technique. The processor issues instructions one at a time
+(program order), but lets them read operands and execute independently once
+their hazards clear. A central scoreboard -- three tables -- tracks every
+in-flight instruction and enforces the classic CDC 6600 hazard rules without
+any register renaming.
+
+### The Four Stages
+
+| Stage | What happens | Hazard checked |
+|---|---|---|
+| **Issue** | Assign instruction to a free FU | Structural (FU busy) + WAW (another active insn writes same dest) |
+| **Read Operands** | Read both source registers | RAW (stall until producing FU has written result) |
+| **Execute** | Occupy the FU for its full latency | -- |
+| **Write Result** | Commit result to register file, free FU | WAR (stall until every earlier reader has read its operand) |
+
+### Three Tracking Tables
+
+1. **Instruction Status** -- per-instruction cycle stamps (Issue / ReadOperands / ExecuteComplete / WriteResult).
+2. **Functional Unit Status** -- per-FU: busy flag, op, destination (Fi), sources (Fj, Fk), producing FUs (Qj, Qk), ready flags (Rj, Rk).
+3. **Register Result Status** -- which FU will next write each register (None once written).
+
+### How it differs from Tomasulo
+
+| | Scoreboarding | Tomasulo |
+|---|---|---|
+| Issue order | In order | In order |
+| Execution order | Out of order | Out of order |
+| WAW handling | Stall Issue | Register renaming (RS tags) |
+| WAR handling | Stall Write Result | Eliminated by renaming |
+| RAW handling | Stall Read Operands | Stall in RS until CDB broadcast |
+| Register renaming | No | Yes (via reservation stations) |
+| Broadcast mechanism | Central scoreboard | Common Data Bus |
+
+See the sibling package [tomasulo](https://github.com/amaar-mc/tomasulo) for the
+Tomasulo out-of-order scheduler with register renaming.
+
+---
+
+## Install
+
+```bash
+# From source (until PyPI release):
+git clone https://github.com/amaar-mc/scoreboarding
+cd scoreboarding
+uv pip install -e ".[dev]"
+```
+
+---
+
+## Usage
+
+### Python API
+
+```python
+from scoreboarding import FunctionalUnit, Instruction, run, render_trace
+
+fus = [
+    FunctionalUnit(name="Load1", kind="load", latency=2),
+    FunctionalUnit(name="Mult1", kind="mult", latency=10),
+    FunctionalUnit(name="Add1",  kind="add",  latency=2),
+    FunctionalUnit(name="Div1",  kind="div",  latency=40),
+]
+
+program = [
+    Instruction(op="LD",   dest="F6",  src1="R2", src2=""),
+    Instruction(op="LD",   dest="F2",  src1="R3", src2=""),
+    Instruction(op="MULT", dest="F0",  src1="F2", src2="F4"),
+    Instruction(op="SUB",  dest="F8",  src1="F6", src2="F2"),
+    Instruction(op="DIV",  dest="F10", src1="F0", src2="F6"),
+    Instruction(op="ADD",  dest="F6",  src1="F8", src2="F2"),
+]
+
+trace = run(program, functional_units=fus)
+print(render_trace(trace))
+```
+
+### Example timing table
+
+```
++---------------------+-------+---------+----------+-------------+
+| Instruction         | Issue | ReadOps | ExecComp | WriteResult |
++---------------------+-------+---------+----------+-------------+
+| LD F6, R2           |     1 |       1 |        2 |           3 |
+| LD F2, R3           |     3 |       3 |        4 |           5 |
+| MULT F0, F2, F4     |     4 |       5 |       14 |          15 |
+| SUB F8, F6, F2      |     4 |       5 |        6 |           7 |
+| DIV F10, F0, F6     |     5 |      15 |       54 |          55 |
+| ADD F6, F8, F2      |     8 |       8 |        9 |          16 |
++---------------------+-------+---------+----------+-------------+
+Total cycles: 16
+```
+
+### CLI
+
+```bash
+# Use the bundled example:
+scoreboarding examples/classic.txt
+
+# Enable per-cycle snapshots:
+scoreboarding --snapshots examples/classic.txt
+
+# Read from stdin:
+cat examples/classic.txt | scoreboarding -
+```
+
+Program file format:
+
+```
+# Comments start with #
+FU Load1 load 2
+FU Mult1 mult 10
+FU Add1  add  2
+FU Div1  div  40
+
+LD   F6, R2
+LD   F2, R3
+MULT F0, F2, F4
+SUB  F8, F6, F2
+DIV  F10, F0, F6
+ADD  F6, F8, F2
+```
+
+---
+
+## Development
+
+```bash
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+uv build
+```
+
+CI runs on Python 3.10, 3.11, 3.12, 3.13 via GitHub Actions.
+
+---
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

scoreboarding-0.1.0/README.md

@@ -0,0 +1,159 @@
+# scoreboarding
+
+<p align="center">
+  <img src="assets/logo.png" alt="scoreboarding logo" width="160">
+</p>
+
+Pure-Python cycle-exact simulator of Thornton's **Scoreboarding** algorithm,
+as implemented in the CDC 6600 (1964). Designed for computer architecture
+education: readable source, zero runtime dependencies, and per-instruction
+cycle-number traces.
+
+> PyPI publish pending (package-upload quota). `pip install scoreboarding`
+> will work once the first release is live. Install from source in the meantime.
+
+---
+
+## What is Scoreboarding?
+
+Scoreboarding is an **in-order issue, out-of-order execution** dynamic
+scheduling technique. The processor issues instructions one at a time
+(program order), but lets them read operands and execute independently once
+their hazards clear. A central scoreboard -- three tables -- tracks every
+in-flight instruction and enforces the classic CDC 6600 hazard rules without
+any register renaming.
+
+### The Four Stages
+
+| Stage | What happens | Hazard checked |
+|---|---|---|
+| **Issue** | Assign instruction to a free FU | Structural (FU busy) + WAW (another active insn writes same dest) |
+| **Read Operands** | Read both source registers | RAW (stall until producing FU has written result) |
+| **Execute** | Occupy the FU for its full latency | -- |
+| **Write Result** | Commit result to register file, free FU | WAR (stall until every earlier reader has read its operand) |
+
+### Three Tracking Tables
+
+1. **Instruction Status** -- per-instruction cycle stamps (Issue / ReadOperands / ExecuteComplete / WriteResult).
+2. **Functional Unit Status** -- per-FU: busy flag, op, destination (Fi), sources (Fj, Fk), producing FUs (Qj, Qk), ready flags (Rj, Rk).
+3. **Register Result Status** -- which FU will next write each register (None once written).
+
+### How it differs from Tomasulo
+
+| | Scoreboarding | Tomasulo |
+|---|---|---|
+| Issue order | In order | In order |
+| Execution order | Out of order | Out of order |
+| WAW handling | Stall Issue | Register renaming (RS tags) |
+| WAR handling | Stall Write Result | Eliminated by renaming |
+| RAW handling | Stall Read Operands | Stall in RS until CDB broadcast |
+| Register renaming | No | Yes (via reservation stations) |
+| Broadcast mechanism | Central scoreboard | Common Data Bus |
+
+See the sibling package [tomasulo](https://github.com/amaar-mc/tomasulo) for the
+Tomasulo out-of-order scheduler with register renaming.
+
+---
+
+## Install
+
+```bash
+# From source (until PyPI release):
+git clone https://github.com/amaar-mc/scoreboarding
+cd scoreboarding
+uv pip install -e ".[dev]"
+```
+
+---
+
+## Usage
+
+### Python API
+
+```python
+from scoreboarding import FunctionalUnit, Instruction, run, render_trace
+
+fus = [
+    FunctionalUnit(name="Load1", kind="load", latency=2),
+    FunctionalUnit(name="Mult1", kind="mult", latency=10),
+    FunctionalUnit(name="Add1",  kind="add",  latency=2),
+    FunctionalUnit(name="Div1",  kind="div",  latency=40),
+]
+
+program = [
+    Instruction(op="LD",   dest="F6",  src1="R2", src2=""),
+    Instruction(op="LD",   dest="F2",  src1="R3", src2=""),
+    Instruction(op="MULT", dest="F0",  src1="F2", src2="F4"),
+    Instruction(op="SUB",  dest="F8",  src1="F6", src2="F2"),
+    Instruction(op="DIV",  dest="F10", src1="F0", src2="F6"),
+    Instruction(op="ADD",  dest="F6",  src1="F8", src2="F2"),
+]
+
+trace = run(program, functional_units=fus)
+print(render_trace(trace))
+```
+
+### Example timing table
+
+```
++---------------------+-------+---------+----------+-------------+
+| Instruction         | Issue | ReadOps | ExecComp | WriteResult |
++---------------------+-------+---------+----------+-------------+
+| LD F6, R2           |     1 |       1 |        2 |           3 |
+| LD F2, R3           |     3 |       3 |        4 |           5 |
+| MULT F0, F2, F4     |     4 |       5 |       14 |          15 |
+| SUB F8, F6, F2      |     4 |       5 |        6 |           7 |
+| DIV F10, F0, F6     |     5 |      15 |       54 |          55 |
+| ADD F6, F8, F2      |     8 |       8 |        9 |          16 |
++---------------------+-------+---------+----------+-------------+
+Total cycles: 16
+```
+
+### CLI
+
+```bash
+# Use the bundled example:
+scoreboarding examples/classic.txt
+
+# Enable per-cycle snapshots:
+scoreboarding --snapshots examples/classic.txt
+
+# Read from stdin:
+cat examples/classic.txt | scoreboarding -
+```
+
+Program file format:
+
+```
+# Comments start with #
+FU Load1 load 2
+FU Mult1 mult 10
+FU Add1  add  2
+FU Div1  div  40
+
+LD   F6, R2
+LD   F2, R3
+MULT F0, F2, F4
+SUB  F8, F6, F2
+DIV  F10, F0, F6
+ADD  F6, F8, F2
+```
+
+---
+
+## Development
+
+```bash
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+uv build
+```
+
+CI runs on Python 3.10, 3.11, 3.12, 3.13 via GitHub Actions.
+
+---
+
+## License
+
+MIT -- see [LICENSE](LICENSE).

scoreboarding-0.1.0/SECURITY.md

@@ -0,0 +1,16 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| ------- | --------- |
+| 0.1.x   | Yes       |
+
+## Reporting a Vulnerability
+
+This is a pure-Python CPU simulator with zero runtime dependencies and no network
+access. The attack surface is limited to malformed program files processed by the CLI.
+
+If you discover a security vulnerability, please open a GitHub issue with the label
+`security`. Do not include exploit code in the public issue; describe the class of
+vulnerability and a minimal reproduction. We will respond within 7 days.