🖥️ Basic Computer Simulator

A simple, low-level architecture simulator that models a basic Von Neumann computer. It loads a sequence of machine code instructions from an external program file, reads/writes data from/to a simulated memory bank, executes the operations sequentially, and manipulates core registers like the Accumulator (AC). 🚀

📂 Project Structure
The project currently consists of three fundamental components:

basic_computer_simulator.py🐍:
The core Python script responsible for initializing the CPU registers (such as Program Counter PC and Accumulator AC), managing the memory array, parsing instructions, and executing the fetch-decode-execute cycle.

program.txt📝:
The assembly/machine code file that defines the sequence of operations. Each row contains an instruction location address and an encoded operation/operand payload.

data.txt📊:
The memory initialization file containing predefined data inputs loaded into specific memory addresses prior to execution.

🔍 Code & Data Analysis
Based on your project files, here is a breakdown of exactly what your simulator executes:

1. Data File (data.txt) 🔢
   This file initializes specific memory slots with baseline integer values before the application runs:

Address 004 is loaded with the value 0003.

Address 005 is loaded with the value 0004.

Address 006 is initialized to 0000 (reserved for holding the final output).

2. Program File (program.txt) ⚙️
   The program simulates a classical three-instruction addition operation followed by a termination signal:

Code snippet Example

Target Operation: AC = M[4] + M[5]; store to M[6]; halt

300 2004   # 📥 Load data from Memory location 004 (value: 3) into the Accumulator (AC)
301 1005   # ➕ Add data from Memory location 005 (value: 4) to the Accumulator (AC)
302 3006   # 📤 Store the final value of the Accumulator (7) into Memory location 006
303 7001   # 🛑 Halt instruction: Terminates the execution cycle\

🚀 How to Execute

To run this simulation on your machine, follow these simple steps:

🛠️ Prerequisites

Make sure you have Python 3 installed. You can check your version by running:

Bash
python --version

🏃‍♂️ Execution Steps
Prepare Directory: Ensure all three files (basic_computer_simulator.py, program.txt, and data.txt) reside inside the exact same folder level. 📁

Open Terminal / Command Prompt: Navigate to your project directory:

Bash  
cd path/to/your/project-folder

Run the Simulator: Run the Python script directly from your command line terminal: ⚡

Bash  
python basic_computer_simulator.py 

💡 Interactive Help Mode:
You can view all supported operational commands, flag toggles, and runtime instructions dynamically during execution by typing the help command into the application interface console prompt.

📋 Expected Output Structure
When executed, your simulator will typically display the step-by-step register states (PC, AC, IR) through every clock cycle, ending with a dump of the updated memory addresses:

Plaintext  
Loading data into memory... ⏳  
Loading program instructions... ⏳  

[Cycle 1] 🔄 PC: 300 | AC: 0003 | IR: 2004 (LOAD M[4])  
[Cycle 2] 🔄 PC: 301 | AC: 0007 | IR: 1005 (ADD M[5])  
[Cycle 3] 🔄 PC: 302 | AC: 0007 | IR: 3006 (STORE M[6])  
[Cycle 4] 🔄 PC: 303 | AC: 0007 | IR: 7001 (HALT)  

🛑 Execution halted successfully.  
📊 Final Memory State:  
Address 004: 0003  
Address 005: 0004  
Address 006: 0007   

⚠️ Common Errors & Troubleshooting
Here are some common bugs or structural mistakes that might happen when modifying or running this simulation, along with how to fix them:

1. 🔍 FileNotFoundError

Symptom: The terminal throws an error saying FileNotFoundError: [Errno 2] No such file or directory: 'program.txt' or 'data.txt'.

Cause: Python is running in a directory where program.txt or data.txt cannot be found. This happens if you forgot to place them in the same directory or if your terminal workspace is opened to a different parent folder.

Fix: Ensure your terminal path matches the file location exactly using cd. You can check the current files in your folder using ls (Mac/Linux) or dir (Windows).

2. 🚯 ValueError: invalid literal for int() with base 10

Symptom: The simulator crashes when attempting to parse or load the text files.

Cause: Your text parser is likely attempting to convert an empty line, a trailing space, or a comment string (like # AC = ...) directly into an integer opcode without stripping or filtering it out first.

Fix: In your Python code, make sure you skip lines starting with # or empty spaces:

Python
if not line.strip() or line.strip().startswith('#'):
    continue

3. ♾️ Infinite Execution Loop (Missing HALT)

Symptom: The simulation keeps running endlessly, logs garbage data, or throws an index-out-of-bounds error after reaching the end of the script.

Cause: Your program.txt file is missing a terminal halt command (like 7001), or your execution loop logic inside basic_computer_simulator.py doesn't recognize the instruction opcode properly to break the cycle.

Fix: Double-check that your code reads the upper part of the instruction payload (e.g., 7 for HALT) and explicitly breaks out of the while execution loop.

4. 🔀 Address / Data Mismatch

Symptom: The final output calculation is unexpected or results in zero.

Cause: Your instruction points to an uninitialized address. For example, trying to run 1007 (Add address 007) when address 007 was never given an initial value in data.txt.

Fix: Ensure your data.txt file maps values to all specific memory target addresses accessed by your instructions in program.txt.