{"id":29861023,"url":"https://github.com/jesse-wei/sapsim","last_synced_at":"2025-07-30T04:10:16.458Z","repository":{"id":153268764,"uuid":"605739318","full_name":"jesse-wei/SAPsim","owner":"jesse-wei","description":"Simulation of SAP (Simple-As-Possible computer) programs","archived":false,"fork":false,"pushed_at":"2025-03-20T12:03:40.000Z","size":1580,"stargazers_count":6,"open_issues_count":3,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-29T13:50:00.278Z","etag":null,"topics":["assembly","comp311","computer-organization","python","sap","unc"],"latest_commit_sha":null,"homepage":"https://SAPsim.readthedocs.io","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jesse-wei.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-02-23T19:53:12.000Z","updated_at":"2025-01-15T21:42:36.000Z","dependencies_parsed_at":"2025-01-15T23:04:29.610Z","dependency_job_id":"82cdbe4a-d5fc-42a8-92e7-c7480537bfa9","html_url":"https://github.com/jesse-wei/SAPsim","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/jesse-wei/SAPsim","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesse-wei%2FSAPsim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesse-wei%2FSAPsim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesse-wei%2FSAPsim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesse-wei%2FSAPsim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jesse-wei","download_url":"https://codeload.github.com/jesse-wei/SAPsim/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jesse-wei%2FSAPsim/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267808215,"owners_count":24147388,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-07-30T02:00:09.044Z","response_time":70,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["assembly","comp311","computer-organization","python","sap","unc"],"created_at":"2025-07-30T04:10:12.926Z","updated_at":"2025-07-30T04:10:16.410Z","avatar_url":"https://github.com/jesse-wei.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"[![Python 3.9+ badge](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/) [![PyPI version badge](https://badge.fury.io/py/SAPsim.svg)](https://pypi.org/project/SAPsim/) [![tests GitHub action badge](https://github.com/jesse-wei/SAPsim/actions/workflows/tests.yml/badge.svg)](https://github.com/jesse-wei/SAPsim/actions/workflows/tests.yml) [![codecov badge](https://codecov.io/github/jesse-wei/SAPsim/branch/main/graph/badge.svg?token=RS7QI9QVKU)](https://codecov.io/github/jesse-wei/SAPsim) [![documentation badge](https://readthedocs.org/projects/sapsim/badge/?version=latest)](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\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/jesse-wei/SAPsim/main/docs/_static/SAPsim_demo.gif\" alt=\"SAPsim demo\"\u003e\n\u003c/p\u003e\n\n## Install\n\n`pip install SAPsim`\n\nIf you get the error `pip not found`, use `pip3` instead[^alias]. Similarly, for later commands that use `python`, you'll need to use `python3` instead.\n\nPython 3.9+ is required.\n\n[^alias]: Consider [aliasing `pip` to `pip3`](https://stackoverflow.com/a/44455078) and similar for `python`. Also consider using `pyenv`. [Relevant XKCD](https://opensource.com/sites/default/files/uploads/python_environment_xkcd.png)\n\n## Usage\n\nIn a `.csv` file, write a SAP program in this format (use these exact column names):\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/jesse-wei/SAPsim/main/docs/_static/ex1.jpg\" alt=\"Screenshot of ex1.csv in VSCode Edit CSV\"\u003e\n\u003c/p\u003e\n\u003cp align=\"center\"\u003e\n    \u003cem\u003e\u003ca href=\"https://github.com/jesse-wei/SAPsim/blob/main/tests/public_prog/ex1.csv\"\u003eex1.csv\u003c/a\u003e\u003c/em\u003e\n\u003c/p\u003e\n\nIn a Python shell, import `SAPsim` and use `SAPsim.run` to run the program.\n\n```py\n❯ python\n\u003e\u003e\u003e from SAPsim import run\n\u003e\u003e\u003e run(\"ex1.csv\")                  # Run ex1.csv at full speed (default)\n┌──────┬────────┬───────────────┬───────┬───────┐\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│ \u003e    │      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┌───────┬───┐\n│ PC    │ 8 │\n│ Reg A │ 1 │\n│ Reg B │ 3 │\n│ FlagC │ 1 │\n│ FlagZ │ 1 │\n└───────┴───┘\n\u003e\u003e\u003e run(\"ex1.csv\", debug=True)      # Run in debug (step) mode\nInitial state of simulation of ex1.csv\n...\nDebug mode: press Enter to execute next instruction ( \u003e ).\n...\n```\n\n\u003cp align=\"center\"\u003e\u003cem\u003eSAPsim running in Python terminal\u003c/em\u003e\u003c/p\u003e\n\n**Debug mode**: There is a debug (step) mode that runs one instruction at a time, as shown above. By default, the program is run at full speed.\n\nI recommend editing the CSV in VSCode or Excel. If you use VSCode, I recommend the extensions [Edit CSV](https://marketplace.visualstudio.com/items?itemName=janisdd.vscode-edit-csv) (Excel-like editing) and [Rainbow CSV](https://marketplace.visualstudio.com/items?itemName=mechatroner.rainbow-csv) (adds color to columns).\n\nLastly, here's a [blank template](https://github.com/jesse-wei/SAPsim/blob/main/docs/_static/template.csv) that includes only the column names and addresses 0-15 and [two commented example programs](https://github.com/jesse-wei/SAPsim/tree/main/tests/public_prog).\n\n### SAP instruction set\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://raw.githubusercontent.com/jesse-wei/SAPsim/main/docs/_static/sap_instruction_set.jpg\" alt=\"SAP instruction set\"\u003e\n\u003c/p\u003e\n\nAll instructions are supported.\n\n## Settings\n\nTo customize table appearance, use `table_format`. [Options](https://github.com/astanin/python-tabulate#table-format).\n\n```py\n\u003e\u003e\u003e run(\"ex1.csv\", table_format=\"outline\")\n+------+--------+---------------+-------+-------+\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| \u003e    |      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+-------+---+\n| PC    | 8 |\n| Reg A | 1 |\n| Reg B | 3 |\n| FlagC | 1 |\n| FlagZ | 1 |\n+-------+---+\n```\n\nTo modify values in the SAP program without editing the CSV, use the `change` keyword argument. For example, `run(\"ex1.csv\", change={14: 4, 13: 2})` would change the byte at address 14 to 4 and at 13 to 2 before execution.\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjesse-wei%2Fsapsim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjesse-wei%2Fsapsim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjesse-wei%2Fsapsim/lists"}