mixal

Python bindings for the MIXAL emulator - a MIX assembly language emulator implementing the MIX computer architecture from Donald Knuth's "The Art of Computer Programming".

Installation

pip install mixal

Note: Requires CMake for building from source.

Quick Start

import mixal

# Create a MIX computer instance
computer = mixal.Computer()

# Load MIXAL assembly code
computer.load_codes("""
        ORIG 3000
        ENTA 42
        ADD  =100=
        HLT
""")

# Execute until halt
computer.execute_until_halt()

# Read results
print(computer.rA.value())  # 142
print(computer.elapsed())   # Execution time in cycles

API Reference

Computer

The main class representing the MIX virtual machine.

computer = mixal.Computer()

Registers

Attribute	Type	Description
`rA`	`Register5`	Accumulator (5 bytes + sign)
`rX`	`Register5`	Extension register (5 bytes + sign)
`rI1` - `rI6`	`Register2`	Index registers (2 bytes + sign)
`rJ`	`Register2`	Jump address register (2 bytes, always positive)

Methods

Method	Description
`load_codes(code)`	Load and assemble MIXAL source code
`execute_until_halt()`	Run until HLT instruction
`execute_single()`	Execute one instruction
`memory_at(addr)`	Access memory word at address (0-3999)
`get_device_word_at(device, index)`	Access I/O device buffer
`elapsed()`	Get total execution time in cycles
`reset()`	Reset computer to initial state

Register5 (ComputerWord)

5-byte register used for rA, rX, and memory words.

word = computer.rA  # or computer.memory_at(1000)

# Set value
word.set(12345)
word.set_characters("HELLO")
word.set_bytes(False, 1, 2, 3, 4, 5)  # sign + 5 bytes

# Get value
word.value()           # Integer value
word.float_value()     # Float interpretation
word.get_characters()  # Character string (5 chars)
word.get_bytes_string() # Byte representation

Register2

2-byte register used for rI1-rI6 and rJ.

reg = computer.rI1

reg.set(100)
reg.set_bytes(False, 1, 2)  # sign + 2 bytes
reg.value()

Examples

Finding Maximum Value (Algorithm M from TAOCP)

import random
import mixal

computer = mixal.Computer()

computer.load_codes("""
X       EQU  1000
        ORIG 3000
MAXIMUM STJ  EXIT
INIT    ENT3 0,1
        JMP  CHANGEM
LOOP    CMPA X,3
        JGE  *+3
CHANGEM ENT2 0,3
        LDA  X,3
        DEC3 1
        J3P  LOOP
EXIT    JMP  *
        ORIG 3500
        HLT
""")

# Setup test data
n = 100
computer.rI1.set(n)
computer.rJ.set(3500)

max_val = 0
for i in range(1001, 1001 + n):
    val = random.randint(0, 100000)
    computer.memory_at(i).set(val)
    max_val = max(max_val, val)

computer.execute_until_halt()

assert computer.rA.value() == max_val
print(f"Maximum: {computer.rA.value()}")
print(f"Cycles: {computer.elapsed()}")

I/O Operations

import mixal

computer = mixal.Computer()

# Card reader (16) -> Card punch (17)
computer.load_codes("""
        ORIG 3000
        IN   100(16)
LIN     JBUS LIN(16)
        OUT  100(17)
LOUT    JBUS LOUT(17)
""")

# Set input
computer.get_device_word_at(16, 0).set_characters("HELLO")

computer.execute_until_halt()

# Read output
output = computer.get_device_word_at(17, 0).get_characters()
print(output)  # "HELLO"

Arithmetic Operations

import mixal

computer = mixal.Computer()

computer.load_codes("""
        ORIG 3000
        ENTA 1000
        MUL  =3=
        HLT
""")

computer.execute_until_halt()

# After MUL, result is in rA:rX (10 bytes)
print(f"rA = {computer.rA.value()}")
print(f"rX = {computer.rX.value()}")

I/O Device Reference

Index	Device	Block Size
0-7	Magnetic tape units	100 words
8-15	Disk/drum units	100 words
16	Card reader	16 words
17	Card punch	16 words
18	Line printer	24 words
19	Terminal	14 words
20	Paper tape	14 words

Development

# Clone repository
git clone https://github.com/CyberZHG/MIXAL.git
cd MIXAL

# Install in development mode
pip install -e ".[test]"

# Run tests
pytest -v python/tests

# Code formatting
black python/
isort python/
flake8 python/

Metadata

Release files for mixal 2.5.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mixal 2.5.0
File	Size	Uploaded	Provenance
mixal-2.5.0.tar.gz	39.8 kB	Oct 23, 2026	Without provenance	Details

Release files / mixal-2.5.0.tar.gz

Download URL	mixal-2.5.0.tar.gz
Size	39.8 kB
Tags	Source
SHA-256 checksum How to use checksums	`33d3190dc5c7faf1f22ee5ebbcfb41b2d8fbfc970304fb8d1e22e1158c8bd94a`
BLAKE2b-256 checksum How to use checksums	`bd2ca05f331027e1cc4113c9e7dc36803216d5945e38d3bb85fa3fa76c8a2d69`
Upload date	Oct 23, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/6.1.0 CPython/3.8.20`

Security for mixal 2.5.0

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.