[](https://www.python.org/downloads/) [](https://pypi.org/project/SAPsim/) [](https://github.com/jesse-wei/SAPsim/actions/workflows/tests.yml) [](https://codecov.io/github/jesse-wei/SAPsim) [](https://SAPsim.readthedocs.io/en/latest/)
# SAPsim
Simulation of SAP (Simple-As-Possible computer) programs from COMP 311 (Computer Organization) @ [UNC](https://unc.edu).
<p align="center">
<img src="https://raw.githubusercontent.com/jesse-wei/SAPsim/main/docs/_static/SAPsim_demo.gif" alt="SAPsim demo">
</p>
## Install
`pip install SAPsim`
Python 3.9+ is required. If your `pip` command doesn't work, use `pip3`[^alias].
[^alias]: Consider aliasing `pip` to `pip3`.
## Usage
Write a SAP program in a CSV file using the format shown below.
<p align="center">
<img src="docs/_static/ex1.jpg" alt="Screenshot of ex1.csv in VSCode Edit CSV">
</p>
<p align="center">
<em><a href="https://github.com/jesse-wei/SAPsim/blob/main/tests/public_prog/ex1.csv">ex1.csv</a></em>
</p>
Two commented example programs are in [public_prog/](https://github.com/jesse-wei/SAPsim/tree/main/tests/public_prog). Also, there's an empty template file [here](docs/_static/template.csv). Lastly, I recommend editing the CSV using VSCode's [Edit csv](https://marketplace.visualstudio.com/items?itemName=janisdd.vscode-edit-csv) extension or Excel.
To run the SAP program, open a Python terminal and use `SAPsim.run()`.
```py
>>> from SAPsim import run
>>> run("ex1.csv") # Run at full speed (default)
┌──────┬────────┬───────────────┬───────┬───────┐
│ PC │ Addr │ Instruction │ Dec │ Hex │
├──────┼────────┼───────────────┼───────┼───────┤
│ │ 0 │ LDA 14 │ 30 │ 0x1e │
│ │ 1 │ SUB 13 │ 61 │ 0x3d │
│ │ 2 │ JZ 6 │ 134 │ 0x86 │
│ │ 3 │ LDI 0 │ 80 │ 0x50 │
│ │ 4 │ STA 15 │ 79 │ 0x4f │
│ │ 5 │ HLT 0 │ 240 │ 0xf0 │
│ │ 6 │ LDI 1 │ 81 │ 0x51 │
│ │ 7 │ STA 15 │ 79 │ 0x4f │
│ > │ 8 │ HLT 0 │ 240 │ 0xf0 │
│ │ 13 │ NOP 3 │ 3 │ 0x03 │
│ │ 14 │ NOP 3 │ 3 │ 0x03 │
│ │ 15 │ NOP 1 │ 1 │ 0x01 │
└──────┴────────┴───────────────┴───────┴───────┘
┌───────┬───┐
│ PC │ 8 │
│ Reg A │ 1 │
│ Reg B │ 3 │
│ FlagC │ 1 │
│ FlagZ │ 1 │
└───────┴───┘
>>> run("ex1.csv", debug=True) # Run in debug (step) mode
Initial state of simulation of tests/public_prog/ex1.csv
...
Debug mode: press Enter to execute next instruction ( > ).
...
```
**Note**: There is a debug (step) mode that runs an instruction each time you press Enter, as shown above. The default behavior is to run at full speed.
### SAP instruction set
<p align="center">
<img src="https://raw.githubusercontent.com/jesse-wei/SAPsim/main/docs/_static/sap_instruction_set.jpg" alt="SAP instruction set">
</p>
## Settings
To customize table appearance, use `table_format`. [Options](https://github.com/astanin/python-tabulate#table-format).
```py
>>> run("ex1.csv", table_format="github")
| PC | Addr | Instruction | Dec | Hex |
|------|--------|---------------|-------|-------|
| | 0 | LDA 14 | 30 | 0x1e |
| | 1 | SUB 13 | 61 | 0x3d |
| | 2 | JZ 6 | 134 | 0x86 |
| | 3 | LDI 0 | 80 | 0x50 |
| | 4 | STA 15 | 79 | 0x4f |
| | 5 | HLT 0 | 240 | 0xf0 |
| | 6 | LDI 1 | 81 | 0x51 |
| | 7 | STA 15 | 79 | 0x4f |
| > | 8 | HLT 0 | 240 | 0xf0 |
| | 13 | NOP 3 | 3 | 0x03 |
| | 14 | NOP 3 | 3 | 0x03 |
| | 15 | NOP 1 | 1 | 0x01 |
|-------|---|
| PC | 8 |
| Reg A | 1 |
| Reg B | 3 |
| FlagC | 1 |
| FlagZ | 1 |
```
To modify values in the SAP program without editing the CSV, use the `change` keyword argument.
```py
>>> run("ex1.csv", change={14: 4, 13: 2}) # Change initial byte at address 14 to 4 and at 13 to 2
┌──────┬────────┬───────────────┬───────┬───────┐
│ PC │ Addr │ Instruction │ Dec │ Hex │
├──────┼────────┼───────────────┼───────┼───────┤
│ │ 0 │ LDA 14 │ 30 │ 0x1e │
│ │ 1 │ SUB 13 │ 61 │ 0x3d │
│ │ 2 │ JZ 6 │ 134 │ 0x86 │
│ │ 3 │ LDI 0 │ 80 │ 0x50 │
│ │ 4 │ STA 15 │ 79 │ 0x4f │
│ > │ 5 │ HLT 0 │ 240 │ 0xf0 │
│ │ 6 │ LDI 1 │ 81 │ 0x51 │
│ │ 7 │ STA 15 │ 79 │ 0x4f │
│ │ 8 │ HLT 0 │ 240 │ 0xf0 │
│ │ 13 │ NOP 2 │ 2 │ 0x02 │
│ │ 14 │ NOP 4 │ 4 │ 0x04 │
│ │ 15 │ NOP 0 │ 0 │ 0x00 │
└──────┴────────┴───────────────┴───────┴───────┘
┌───────┬───┐
│ PC │ 5 │
│ Reg A │ 0 │
│ Reg B │ 2 │
│ FlagC │ 1 │
│ FlagZ │ 0 │
└───────┴───┘
```
## Rules
It's easy to just mimic the [example programs](https://github.com/jesse-wei/SAPsim/tree/main/tests/public_prog), but if you need it, here are the [rules for SAPsim programs](https://SAPsim.readthedocs.io/en/latest/rules.html).
## Documentation
[https://SAPsim.readthedocs.io](https://SAPsim.readthedocs.io/en/latest/)
Raw data
{
"_id": null,
"home_page": "https://github.com/jesse-wei/SAPsim",
"name": "SAPsim",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": "",
"keywords": "SAP,SAPsim,simple as possible,UNC,COMP311",
"author": "Jesse Wei",
"author_email": "Jesse Wei <jesse@cs.unc.edu>",
"download_url": "https://files.pythonhosted.org/packages/8d/87/c944634226b138bccc401b6540f6102951c56281b529c967bca6a43b55dc/SAPsim-1.1.1.tar.gz",
"platform": null,
"description": "[](https://www.python.org/downloads/) [](https://pypi.org/project/SAPsim/) [](https://github.com/jesse-wei/SAPsim/actions/workflows/tests.yml) [](https://codecov.io/github/jesse-wei/SAPsim) [](https://SAPsim.readthedocs.io/en/latest/)\n\n# SAPsim\n\nSimulation of SAP (Simple-As-Possible computer) programs from COMP 311 (Computer Organization) @ [UNC](https://unc.edu).\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/jesse-wei/SAPsim/main/docs/_static/SAPsim_demo.gif\" alt=\"SAPsim demo\">\n</p>\n\n## Install\n\n`pip install SAPsim`\n\nPython 3.9+ is required. If your `pip` command doesn't work, use `pip3`[^alias].\n\n[^alias]: Consider aliasing `pip` to `pip3`.\n\n## Usage\n\nWrite a SAP program in a CSV file using the format shown below.\n\n<p align=\"center\">\n <img src=\"docs/_static/ex1.jpg\" alt=\"Screenshot of ex1.csv in VSCode Edit CSV\">\n</p>\n<p align=\"center\">\n <em><a href=\"https://github.com/jesse-wei/SAPsim/blob/main/tests/public_prog/ex1.csv\">ex1.csv</a></em>\n</p>\n\nTwo commented example programs are in [public_prog/](https://github.com/jesse-wei/SAPsim/tree/main/tests/public_prog). Also, there's an empty template file [here](docs/_static/template.csv). Lastly, I recommend editing the CSV using VSCode's [Edit csv](https://marketplace.visualstudio.com/items?itemName=janisdd.vscode-edit-csv) extension or Excel.\n\nTo run the SAP program, open a Python terminal and use `SAPsim.run()`.\n\n```py\n>>> from SAPsim import run\n>>> run(\"ex1.csv\") # Run at full speed (default)\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 PC \u2502 Addr \u2502 Instruction \u2502 Dec \u2502 Hex \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 \u2502 0 \u2502 LDA 14 \u2502 30 \u2502 0x1e \u2502\n\u2502 \u2502 1 \u2502 SUB 13 \u2502 61 \u2502 0x3d \u2502\n\u2502 \u2502 2 \u2502 JZ 6 \u2502 134 \u2502 0x86 \u2502\n\u2502 \u2502 3 \u2502 LDI 0 \u2502 80 \u2502 0x50 \u2502\n\u2502 \u2502 4 \u2502 STA 15 \u2502 79 \u2502 0x4f \u2502\n\u2502 \u2502 5 \u2502 HLT 0 \u2502 240 \u2502 0xf0 \u2502\n\u2502 \u2502 6 \u2502 LDI 1 \u2502 81 \u2502 0x51 \u2502\n\u2502 \u2502 7 \u2502 STA 15 \u2502 79 \u2502 0x4f \u2502\n\u2502 > \u2502 8 \u2502 HLT 0 \u2502 240 \u2502 0xf0 \u2502\n\u2502 \u2502 13 \u2502 NOP 3 \u2502 3 \u2502 0x03 \u2502\n\u2502 \u2502 14 \u2502 NOP 3 \u2502 3 \u2502 0x03 \u2502\n\u2502 \u2502 15 \u2502 NOP 1 \u2502 1 \u2502 0x01 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2510\n\u2502 PC \u2502 8 \u2502\n\u2502 Reg A \u2502 1 \u2502\n\u2502 Reg B \u2502 3 \u2502\n\u2502 FlagC \u2502 1 \u2502\n\u2502 FlagZ \u2502 1 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2518\n>>> run(\"ex1.csv\", debug=True) # Run in debug (step) mode\nInitial state of simulation of tests/public_prog/ex1.csv\n...\nDebug mode: press Enter to execute next instruction ( > ).\n...\n```\n\n**Note**: There is a debug (step) mode that runs an instruction each time you press Enter, as shown above. The default behavior is to run at full speed.\n\n### SAP instruction set\n\n<p align=\"center\">\n <img src=\"https://raw.githubusercontent.com/jesse-wei/SAPsim/main/docs/_static/sap_instruction_set.jpg\" alt=\"SAP instruction set\">\n</p>\n\n## Settings\n\nTo customize table appearance, use `table_format`. [Options](https://github.com/astanin/python-tabulate#table-format).\n\n```py\n>>> run(\"ex1.csv\", table_format=\"github\")\n| PC | Addr | Instruction | Dec | Hex |\n|------|--------|---------------|-------|-------|\n| | 0 | LDA 14 | 30 | 0x1e |\n| | 1 | SUB 13 | 61 | 0x3d |\n| | 2 | JZ 6 | 134 | 0x86 |\n| | 3 | LDI 0 | 80 | 0x50 |\n| | 4 | STA 15 | 79 | 0x4f |\n| | 5 | HLT 0 | 240 | 0xf0 |\n| | 6 | LDI 1 | 81 | 0x51 |\n| | 7 | STA 15 | 79 | 0x4f |\n| > | 8 | HLT 0 | 240 | 0xf0 |\n| | 13 | NOP 3 | 3 | 0x03 |\n| | 14 | NOP 3 | 3 | 0x03 |\n| | 15 | NOP 1 | 1 | 0x01 |\n|-------|---|\n| PC | 8 |\n| Reg A | 1 |\n| Reg B | 3 |\n| FlagC | 1 |\n| FlagZ | 1 |\n```\n\nTo modify values in the SAP program without editing the CSV, use the `change` keyword argument.\n\n```py\n>>> run(\"ex1.csv\", change={14: 4, 13: 2}) # Change initial byte at address 14 to 4 and at 13 to 2\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2510\n\u2502 PC \u2502 Addr \u2502 Instruction \u2502 Dec \u2502 Hex \u2502\n\u251c\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u253c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2524\n\u2502 \u2502 0 \u2502 LDA 14 \u2502 30 \u2502 0x1e \u2502\n\u2502 \u2502 1 \u2502 SUB 13 \u2502 61 \u2502 0x3d \u2502\n\u2502 \u2502 2 \u2502 JZ 6 \u2502 134 \u2502 0x86 \u2502\n\u2502 \u2502 3 \u2502 LDI 0 \u2502 80 \u2502 0x50 \u2502\n\u2502 \u2502 4 \u2502 STA 15 \u2502 79 \u2502 0x4f \u2502\n\u2502 > \u2502 5 \u2502 HLT 0 \u2502 240 \u2502 0xf0 \u2502\n\u2502 \u2502 6 \u2502 LDI 1 \u2502 81 \u2502 0x51 \u2502\n\u2502 \u2502 7 \u2502 STA 15 \u2502 79 \u2502 0x4f \u2502\n\u2502 \u2502 8 \u2502 HLT 0 \u2502 240 \u2502 0xf0 \u2502\n\u2502 \u2502 13 \u2502 NOP 2 \u2502 2 \u2502 0x02 \u2502\n\u2502 \u2502 14 \u2502 NOP 4 \u2502 4 \u2502 0x04 \u2502\n\u2502 \u2502 15 \u2502 NOP 0 \u2502 0 \u2502 0x00 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2518\n\u250c\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u252c\u2500\u2500\u2500\u2510\n\u2502 PC \u2502 5 \u2502\n\u2502 Reg A \u2502 0 \u2502\n\u2502 Reg B \u2502 2 \u2502\n\u2502 FlagC \u2502 1 \u2502\n\u2502 FlagZ \u2502 0 \u2502\n\u2514\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2534\u2500\u2500\u2500\u2518\n```\n\n## Rules\n\nIt's easy to just mimic the [example programs](https://github.com/jesse-wei/SAPsim/tree/main/tests/public_prog), but if you need it, here are the [rules for SAPsim programs](https://SAPsim.readthedocs.io/en/latest/rules.html).\n\n## Documentation\n\n[https://SAPsim.readthedocs.io](https://SAPsim.readthedocs.io/en/latest/)\n",
"bugtrack_url": null,
"license": "",
"summary": "Simulation of SAP (Simple As Possible) computer programs from COMP311 (Computer Organization) @ UNC",
"version": "1.1.1",
"project_urls": {
"Bug Tracker": "https://github.com/jesse-wei/SAPsim/issues",
"Download": "https://github.com/jesse-wei/SAPsim/releases",
"Homepage": "https://github.com/jesse-wei/SAPsim"
},
"split_keywords": [
"sap",
"sapsim",
"simple as possible",
"unc",
"comp311"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "29c09d9d9fc6d24c73d2db68f915da2d907bf8ea09a786f24c448937f70abc09",
"md5": "4c58c82c08f27c56dbe34e38073c650d",
"sha256": "c74249e26cb77f722c4ec92d47b4d39f923a74a21861b115331c3f806e9e9c70"
},
"downloads": -1,
"filename": "SAPsim-1.1.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "4c58c82c08f27c56dbe34e38073c650d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 22774,
"upload_time": "2023-10-15T06:52:33",
"upload_time_iso_8601": "2023-10-15T06:52:33.630047Z",
"url": "https://files.pythonhosted.org/packages/29/c0/9d9d9fc6d24c73d2db68f915da2d907bf8ea09a786f24c448937f70abc09/SAPsim-1.1.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8d87c944634226b138bccc401b6540f6102951c56281b529c967bca6a43b55dc",
"md5": "f711ab51efd671a0c6856a76e5c58077",
"sha256": "61569e4a9dacd71dd03dd10f9fd2d7a90f504d013fcf46f73f330331110596f9"
},
"downloads": -1,
"filename": "SAPsim-1.1.1.tar.gz",
"has_sig": false,
"md5_digest": "f711ab51efd671a0c6856a76e5c58077",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 20711,
"upload_time": "2023-10-15T06:52:35",
"upload_time_iso_8601": "2023-10-15T06:52:35.081528Z",
"url": "https://files.pythonhosted.org/packages/8d/87/c944634226b138bccc401b6540f6102951c56281b529c967bca6a43b55dc/SAPsim-1.1.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-10-15 06:52:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jesse-wei",
"github_project": "SAPsim",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [],
"tox": true,
"lcname": "sapsim"
}
JSON
