lmc2py

A Python package that runs "Little Minion Computer" .lmc and assembly (.txt/.asm) files. The LMC is a conceptual model of a simple CPU, created by Durham professor Dr. Magnus Bordewich.

Features

• Interprets LMC assembly and .lmc machine code
• Test programs against multiple or all inputs (0–999)
• Batch testing with LMC-style test files
• Check outputs with custom checker functions
• Optional graph of inputs vs cycles (requires lmc2py[plot])

Installation

From the project directory:

uv sync
# or: pip install -e .

For graph support (--graph):

uv sync --extra plot
# or: pip install -e ".[plot]"

Usage

CLI

Run LMC programs from the command line:

# After installing, the `lmc` command is available
lmc path/to/file.lmc
lmc path/to/file.lmc -i 997
lmc path/to/file.lmc --all -q -f

Or run as a module:

python -m lmc path/to/file.lmc --options

Import

Use the interpreter from Python:

fromlmcimportLMC, LMCWrapper, get_mailboxes_from_file# Load and run with the wrapper (batch, checker, feedback, etc.)wrapper=LMCWrapper("program.lmc", potential_values=[1, 2, 3], quiet=True)
wrapper.run_batch()
# Or use the core LMC and parser directlymailboxes, _=get_mailboxes_from_file("program.lmc")
vm=LMC([42], mailboxes)
inputs, outputs, cycles=vm.run_cycles()

The default behaviour is to execute the given file once. Assembly (.txt/.asm) is compiled to mailbox code first. The program reports fetch/execute cycles.

Optional flags (short and long form):

• -h, --help: displays this list of options, instead of doing anything else. A source file is not needed in this case.
• -a, --all: executes the program once for each value between 0 and 999.
• -i [VAL], --input [VAL]: executes the program once for each VAL given. Multiple inputs can be given as a list, like -i 840 961 997.
• -b [FILE], --batch [FILE]: Runs from any test file that is compatible with the original LMC and gives expected outputs based on those specified in this file.
• -q, --quiet: executes the program without any terminal output, except errors. If you use this flag without any output flags, the program may not return anything.
• -f [FILE], --feedback [FILE]: save the results of the program to a text file. If no FILE is specified, this will be a file in the source file's directory called feedback_<filename>.
• -ch CHECKER, --checker CHECKER: run a checker function from a python file with the same inputs as the LMC code, to show the expected output and see if your program's output matches. Some example checker functions are included in checks/.
• -g, --graph: show a scatter graph relating input to the number of cycles. Helps with visualizing program efficiency.

Something to consider

If your program requires multiple inputs, and it is passed a series of inputs using either --all or --input, it will use the next value from that series each time. If it runs out of inputs and then hits another IN statement, it will prompt you for another in the terminal.

Furthermore, if you attempt to use both the --batch and --checker arguments at the same time, the expected outputs in the batch file will be used and the checker function will be ignored.