tomasulo 0.1.0__tar.gz

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

@@ -0,0 +1,35 @@
+---
+name: Bug report
+about: Report incorrect simulation output or a crash
+title: "bug: "
+labels: bug
+assignees: ""
+---
+
+## Description
+
+A clear description of the bug.
+
+## Program / input
+
+```
+# Paste the instruction program or Python snippet that triggers the bug
+```
+
+## Expected behavior
+
+What should happen (include expected cycle numbers if it is a trace bug).
+
+## Actual behavior
+
+What actually happens. Include the full output or traceback.
+
+## Environment
+
+- tomasulo version:
+- Python version:
+- OS:
+
+## Additional context
+
+Any other information that might help diagnose the issue.

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

@@ -0,0 +1,28 @@
+---
+name: Feature request
+about: Suggest a new feature or improvement
+title: "feat: "
+labels: enhancement
+assignees: ""
+---
+
+## Summary
+
+A clear, one-sentence description of the feature.
+
+## Motivation
+
+Why is this feature useful? What problem does it solve?
+
+## Proposed design
+
+If you have a concrete design in mind, describe it here. API changes,
+new CLI flags, algorithm extensions, etc.
+
+## Alternatives considered
+
+What alternatives did you consider and why did you rule them out?
+
+## Additional context
+
+Any other context, references, or screenshots.

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

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: Test 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: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv pip install -e ".[dev]"
+
+      - name: Run tests
+        run: uv run pytest -q
+
+      - name: Lint
+        run: uv run ruff check .
+
+      - name: Type check
+        run: uv run mypy src

tomasulo-0.1.0/.gitignore

@@ -0,0 +1,42 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+*.so
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# uv
+uv.lock
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# macOS
+.DS_Store
+
+# Distribution
+*.whl
+*.tar.gz

tomasulo-0.1.0/CHANGELOG.md

@@ -0,0 +1,20 @@
+# 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).
+
+## [0.1.0] - 2026-06-17
+
+### Added
+
+- `Instruction`, `InstructionResult`, `StationState`, `RegisterStatus`,
+  `CycleSnapshot`, and `Trace` dataclasses in `tomasulo.model`.
+- `TomasuloSim` class implementing the classic Tomasulo algorithm with
+  reservation stations, CDB, and register renaming.
+- `render_trace` function for human-readable timing tables.
+- `tomasulo` CLI entry point that reads a plain text program file and
+  prints a timing table; supports `--snapshots` for per-cycle detail.
+- Full test suite with golden trace and invariant checks.
+- CI workflow for Python 3.10, 3.11, 3.12, 3.13.

tomasulo-0.1.0/CLAUDE.md

@@ -0,0 +1,63 @@
+# tomasulo
+
+Pure-Python simulator of Tomasulo's out-of-order instruction scheduling
+algorithm. Zero runtime dependencies. For computer architecture education.
+
+## Commands
+
+- Create env and install: `uv venv && uv pip install -e ".[dev]"`
+- Test: `uv run pytest -q`
+- Lint: `uv run ruff check .` (format with `uv run ruff format .`)
+- Types: `uv run mypy src`
+- Build: `uv build` (then `uv run --with twine twine check dist/*` before publishing)
+- Run the CLI: `uv run tomasulo examples/sample_program.txt`
+
+## Architecture
+
+`src/tomasulo/`:
+- `model.py` -- dataclasses: Instruction, InstructionResult, StationState,
+  RegisterStatus, CycleSnapshot, Trace
+- `simulator.py` -- TomasuloSim class; the core engine with _Station internal
+  state
+- `trace.py` -- render_trace() for human-readable timing tables
+- `cli.py` -- argparse CLI; run(argv) is testable, main() is the console entry
+- `__init__.py` -- public surface
+
+See `docs/architecture.md` for the algorithm, stage ordering, and hazard
+handling.
+
+## Algorithm stage order (critical)
+
+Each cycle: **WRITE first, then EXECUTE, then ISSUE.**
+
+The next-cycle rule: if a station's operands become ready during the WRITE
+phase of cycle N, the station starts executing in cycle N+1, not cycle N.
+This is enforced by setting `remaining` in a second pass after EXECUTE, not
+during WRITE.
+
+## Conventions
+
+- No default parameter values anywhere in the public API.
+- No em dash characters in code, comments, or docs (use -- or commas).
+- No TODOs in committed code.
+- All computed values are 0.0 (value model -- scheduling only, not arithmetic).
+- Station tag tie-break for CDB: lowest index in declaration order wins.
+
+## Testing rules
+
+- Golden trace tests verify exact cycle numbers for the classic 6-instruction
+  program with standard latencies and station counts.
+- Invariant tests verify algorithm properties (RAW, WAW, structural stall).
+- Bug fixes start with a failing test.
+
+## Release
+
+- Semantic versioning; update `CHANGELOG.md` and `__version__`.
+- Gates: `uv run pytest && uv run ruff check . && uv run mypy src && uv build && uv run --with twine twine check dist/*`.
+- Tag `vX.Y.Z`, GitHub release. Do NOT publish to PyPI without explicit review.
+
+## Style
+
+- No em dash characters in docs, comments, or commit messages.
+- Comments explain non-obvious reasoning only.
+- Commit format: `type(scope): description`

tomasulo-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,35 @@
+# Code of Conduct
+
+## Our pledge
+
+We pledge to make 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:
+
+- Trolling, insulting comments, and personal or political attacks.
+- Public or private harassment.
+- Publishing others' private information without explicit permission.
+- Other conduct that could reasonably be considered inappropriate in a
+  professional setting.
+
+## Enforcement
+
+Project maintainers are responsible for clarifying and enforcing standards of
+acceptable behavior. Instances of abusive, harassing, or otherwise
+unacceptable behavior may be reported by opening an issue or contacting the
+maintainer directly.
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

tomasulo-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Contributions are welcome. Please open an issue first to discuss significant
+changes before submitting a pull request.
+
+## Development setup
+
+```
+git clone https://github.com/amaar-mc/tomasulo.git
+cd tomasulo
+uv venv && uv pip install -e ".[dev]"
+```
+
+## Gates (all must pass)
+
+```
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+uv build
+uv run --with twine twine check dist/*
+```
+
+## Code style
+
+- Line length: 100.
+- Type hints on every function signature and class attribute.
+- Google-style docstrings.
+- No default parameter values in public functions or constructors.
+- No em dash characters in code, comments, or docs (use -- or commas).
+- No TODOs left in committed code.
+
+## Commit messages
+
+Format: `type(scope): description`
+
+Examples: `feat(simulator): add WAW hazard detection`, `fix(trace): correct
+snapshot cycle numbering`.
+
+## Testing
+
+- Bug fixes must include a failing test first.
+- Test behavior, not implementation internals.
+- Keep test coverage above 90%.

tomasulo-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.

tomasulo-0.1.0/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: tomasulo
+Version: 0.1.0
+Summary: Pure-Python simulator of Tomasulo's out-of-order instruction scheduling: reservation stations, common data bus, and register renaming, with cycle-by-cycle traces for computer architecture education.
+Project-URL: Homepage, https://github.com/amaar-mc/tomasulo
+Project-URL: Repository, https://github.com/amaar-mc/tomasulo
+Project-URL: Issues, https://github.com/amaar-mc/tomasulo/issues
+Project-URL: Changelog, https://github.com/amaar-mc/tomasulo/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: common-data-bus,computer-architecture,cpu-simulator,education,instruction-scheduling,out-of-order,register-renaming,reservation-stations,simulation,tomasulo
+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
+
+# tomasulo
+
+Pure-Python simulator of Tomasulo's out-of-order instruction scheduling algorithm. Implements reservation stations, a Common Data Bus (CDB), and register renaming for computer architecture education.
+
+Zero runtime dependencies. Requires Python 3.10+.
+
+## Installation
+
+```
+pip install tomasulo
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```
+uv pip install tomasulo
+```
+
+## Quick start
+
+```python
+from tomasulo import Instruction, TomasuloSim, render_trace
+
+program = [
+    Instruction(op="LOAD", dest="F6",  src1="R2", src2="R0"),
+    Instruction(op="LOAD", dest="F2",  src1="R3", src2="R0"),
+    Instruction(op="MUL",  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"),
+]
+
+sim = TomasuloSim(
+    stations={"add": 3, "mult": 2, "load": 3},
+    latencies={"ADD": 2, "SUB": 2, "MUL": 10, "DIV": 40, "LOAD": 2},
+)
+trace = sim.run(program=program)
+print(render_trace(trace=trace))
+```
+
+Output:
+
+```
+   #  Op     Dest   Src1   Src2    Issue  ExecComplete   Write
+---------------------------------------------------------------------
+   1  LOAD   F6     R2     R0          1             3       4
+   2  LOAD   F2     R3     R0          2             4       5
+   3  MUL    F0     F2     F4          3            15      16
+   4  SUB    F8     F6     F2          4             6       7
+   5  DIV    F10    F0     F6          5            56      57
+   6  ADD    F6     F8     F2          6             9      10
+```
+
+## CLI
+
+```
+tomasulo examples/sample_program.txt
+tomasulo examples/sample_program.txt --snapshots
+tomasulo --help
+```
+
+Program file format -- one instruction per line:
+
+```
+# comments are ignored
+LOAD F6  R2  R0
+LOAD F2  R3  R0
+MUL  F0  F2  F4
+SUB  F8  F6  F2
+DIV  F10 F0  F6
+ADD  F6  F8  F2
+```
+
+## Public API
+
+```python
+@dataclass
+class Instruction:
+    op: str    # "ADD", "SUB", "MUL", "DIV", "LOAD"
+    dest: str  # destination register e.g. "F0"
+    src1: str  # first source register; for LOAD: base address register
+    src2: str  # second source register; for LOAD: unused, pass "R0" by convention
+
+@dataclass
+class InstructionResult:
+    instruction: Instruction
+    issue_cycle: int
+    exec_complete_cycle: int
+    write_cycle: int
+
+@dataclass
+class Trace:
+    results: list[InstructionResult]
+    snapshots: list[CycleSnapshot]
+
+class TomasuloSim:
+    def __init__(self, stations: dict[str, int], latencies: dict[str, int]) -> None: ...
+    def run(self, program: list[Instruction]) -> Trace: ...
+
+def render_trace(trace: Trace) -> str: ...
+```
+
+## Algorithm
+
+Stage order each cycle: **WRITE, then EXECUTE, then ISSUE.**
+
+Hazards handled:
+
+- **RAW**: a station waits on the tag (Qj/Qk) of the station that will produce a missing operand. When that station broadcasts on the CDB the value is forwarded and the tag is cleared.
+- **WAR and WAW**: handled by register renaming. Each issued instruction renames its destination to the station tag. Only the last writer commits to the register file.
+- **Structural**: at most one result per cycle on the CDB. Ties broken by lowest station index (declaration order).
+
+See `docs/architecture.md` for a full description.
+
+## Development
+
+```
+uv venv && uv pip install -e ".[dev]"
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+uv build
+```
+
+## License
+
+MIT. Copyright (c) 2026 Amaar Chughtai.

tomasulo-0.1.0/README.md

@@ -0,0 +1,127 @@
+# tomasulo
+
+Pure-Python simulator of Tomasulo's out-of-order instruction scheduling algorithm. Implements reservation stations, a Common Data Bus (CDB), and register renaming for computer architecture education.
+
+Zero runtime dependencies. Requires Python 3.10+.
+
+## Installation
+
+```
+pip install tomasulo
+```
+
+Or with [uv](https://github.com/astral-sh/uv):
+
+```
+uv pip install tomasulo
+```
+
+## Quick start
+
+```python
+from tomasulo import Instruction, TomasuloSim, render_trace
+
+program = [
+    Instruction(op="LOAD", dest="F6",  src1="R2", src2="R0"),
+    Instruction(op="LOAD", dest="F2",  src1="R3", src2="R0"),
+    Instruction(op="MUL",  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"),
+]
+
+sim = TomasuloSim(
+    stations={"add": 3, "mult": 2, "load": 3},
+    latencies={"ADD": 2, "SUB": 2, "MUL": 10, "DIV": 40, "LOAD": 2},
+)
+trace = sim.run(program=program)
+print(render_trace(trace=trace))
+```
+
+Output:
+
+```
+   #  Op     Dest   Src1   Src2    Issue  ExecComplete   Write
+---------------------------------------------------------------------
+   1  LOAD   F6     R2     R0          1             3       4
+   2  LOAD   F2     R3     R0          2             4       5
+   3  MUL    F0     F2     F4          3            15      16
+   4  SUB    F8     F6     F2          4             6       7
+   5  DIV    F10    F0     F6          5            56      57
+   6  ADD    F6     F8     F2          6             9      10
+```
+
+## CLI
+
+```
+tomasulo examples/sample_program.txt
+tomasulo examples/sample_program.txt --snapshots
+tomasulo --help
+```
+
+Program file format -- one instruction per line:
+
+```
+# comments are ignored
+LOAD F6  R2  R0
+LOAD F2  R3  R0
+MUL  F0  F2  F4
+SUB  F8  F6  F2
+DIV  F10 F0  F6
+ADD  F6  F8  F2
+```
+
+## Public API
+
+```python
+@dataclass
+class Instruction:
+    op: str    # "ADD", "SUB", "MUL", "DIV", "LOAD"
+    dest: str  # destination register e.g. "F0"
+    src1: str  # first source register; for LOAD: base address register
+    src2: str  # second source register; for LOAD: unused, pass "R0" by convention
+
+@dataclass
+class InstructionResult:
+    instruction: Instruction
+    issue_cycle: int
+    exec_complete_cycle: int
+    write_cycle: int
+
+@dataclass
+class Trace:
+    results: list[InstructionResult]
+    snapshots: list[CycleSnapshot]
+
+class TomasuloSim:
+    def __init__(self, stations: dict[str, int], latencies: dict[str, int]) -> None: ...
+    def run(self, program: list[Instruction]) -> Trace: ...
+
+def render_trace(trace: Trace) -> str: ...
+```
+
+## Algorithm
+
+Stage order each cycle: **WRITE, then EXECUTE, then ISSUE.**
+
+Hazards handled:
+
+- **RAW**: a station waits on the tag (Qj/Qk) of the station that will produce a missing operand. When that station broadcasts on the CDB the value is forwarded and the tag is cleared.
+- **WAR and WAW**: handled by register renaming. Each issued instruction renames its destination to the station tag. Only the last writer commits to the register file.
+- **Structural**: at most one result per cycle on the CDB. Ties broken by lowest station index (declaration order).
+
+See `docs/architecture.md` for a full description.
+
+## Development
+
+```
+uv venv && uv pip install -e ".[dev]"
+uv run pytest -q
+uv run ruff check .
+uv run mypy src
+uv build
+```
+
+## License
+
+MIT. Copyright (c) 2026 Amaar Chughtai.

tomasulo-0.1.0/SECURITY.md

@@ -0,0 +1,30 @@
+# Security Policy
+
+## Supported versions
+
+Only the latest release receives security fixes.
+
+| Version | Supported |
+|---------|-----------|
+| 0.1.x   | Yes       |
+
+## Reporting a vulnerability
+
+Please do not report security vulnerabilities through public GitHub issues.
+
+Instead, open a [GitHub Security Advisory](https://github.com/amaar-mc/tomasulo/security/advisories/new)
+or email the maintainer directly. You should receive a response within 72 hours.
+
+Include as much of the following as possible:
+
+- Type of issue (e.g. arbitrary code execution, path traversal).
+- Affected source files with line numbers.
+- Steps to reproduce.
+- Proof-of-concept or exploit code (if available).
+- Impact assessment.
+
+## Notes
+
+`tomasulo` is a pure simulation library with no network I/O, no file writes
+outside of explicit CLI invocations, and no execution of user-provided code.
+The primary attack surface is the instruction text parser in `cli.py`.