How dmitrybozhko/cpu-design-and-simulation-project works
Project type and purpose
• This is a Python-based toolset consisting of two command-line binaries:
• A Numeric tool (numeric_main) for low-level numeric routines
• A CPU simulator (cpu_main) that models a simple CPU (register file, ALU, memory, instruction runner)
• It’s an open-source library + CLI utilities for experimenting with numeric algorithms and RISC-style CPU behavior.
File structure
• Top level
• .gitignore, README.md, AI_USAGE.md, ai_report.json (project metadata)
• demo/ – example scripts demonstrating library usage
• count_ai_lines.py – analysis script
• src/ – main Python packages
• tests/ + test_*.py – unit & integration tests
• src/cli/ – CLI entry-points (wrappers that parse arguments and invoke core API)
• src/numeric_core/ – pure arithmetic and bit-level operations (adders, shifters, float32, conversions, public_api.py)
• src/cpu/ – CPU simulator modules (register_file, memory, ALU, interpreter, runner, state)
• tests are split into numeric unit tests, CPU unit tests, and CPU integration tests.
README insights
• Confirms two binaries invoked via python -m src.cli.numeric_main or python -m src.cli.cpu_main.
a. Main components
• CLI Layer: src.cli.numeric_main, src.cli.cpu_main
• Numeric Core Library: everything under src.numeric_core (bit_utils, adders, ALU, float32, etc.)
• CPU Simulator Library: modules under src.cpu (register_file, memory, alu, interpreter, runner, state)
• Demo & Tests: user examples (demo/bit_utils_demo.py) and test harness (tests/)
• Python Runtime: the interpreter hosting all of the above
b. Relationships & interactions
• CLI Layer → invokes Numeric Core API (for numeric tool) or CPU Simulator API
• CPU Simulator ALU component uses Numeric Core routines for arithmetic/bit ops
• Interpreter/Runner orchestrates fetch-decode-execute, using register_file & memory modules
• Demo scripts import public_api from numeric_core and runner from cpu
• Tests import and validate each module in isolation (unit) and in combination (integration)
c. Architectural patterns/design principles
• Layered Modular Design: clear separation between CLI, simulator core, numeric algorithms
• Public API Facade: numeric_core/public_api.py hides internal details
• Single Responsibility: each module (e.g., register_file, memory, alu) does one thing
• Test-Driven Structure: correspondence between implementation and test files
d. Key technologies/frameworks
• Python 3.x modules & __main__ entry points
• Standard library only (no external dependencies)
• pytest (inferred from tests/ naming and conftest.py)
– “CLI Layer” (show two entry points: numeric_main, cpu_main)
– “Demo & Tests” (pointing back to core for validation)
– CLI → Numeric Core
– CLI → CPU Simulator
– CPU Simulator → Numeric Core
– Runner → Interpreter → ALU/Memory/Register
– CLI (blue), Numeric Core (green), CPU Simulator (orange), Demo/Tests (gray)