zctw

Python implementation of Context Tree Weighting (CTW) lossless compression.

Install

pip install zctw

Usage

from zctw import CTWCompressor, CTWSettings

# Use default settings
compressor = CTWCompressor()

# Or customize settings
settings = CTWSettings(treedepth=8, maxnrnodes=4194304)
compressor = CTWCompressor(settings)

# Compress data
original = b"Hello, World! This is a test of the CTW compression algorithm."
compressed = compressor.encode(original)

# Decompress
decompressed = compressor.decode(compressed)

print(f"Original: {len(original)} bytes")
print(f"Compressed: {len(compressed)} bytes")
print(f"Decompressed matches: {original == decompressed}")

CLI

# Encode a file
zctw e input.txt output.zctw

# Decode a file
zctw d output.zctw input_decoded.txt

# Show file info
zctw i output.zctw

CLI Options

• -dX: Set maximum tree depth (1-12)
• -tX: Set maximum number of tries in tree array (1-32)
• -nX: Set maximum number of nodes (supports K/M suffix, e.g., 4M)
• -fX: Set maximum file buffer size (supports K/M suffix)
• -bX: Set maximum value of log beta
• -s: Disable strict tree pruning
• -r: Enable weighting at root nodes
• -k: Use Krichevski-Trofimov estimator instead of Zero-Redundancy
• -y: Force overwriting of existing files
• -lX: Enable logging to file X

API

CTWSettings

@dataclass
class CTWSettings:
    treedepth: int          # max depth of trees, excluding root (default: 6)
    maxnrnodes: int         # max nodes in tree array (default: 4194304)
    maxnrtries: int        # max tries in hash table (default: 32)
    filebufsize: int       # actual file buffer size (default: 4194304)
    maxfilebufsize: int    # max file buffer size (default: 4194304)
    strictpruning: bool    # use strict pruning method (default: True)
    maxlogbeta: int        # max value of logbeta (default: 1024)
    rootweighting: bool    # perform weighting at root node (default: False)
    use_zeroredundancy: bool # use zero-redundancy estimator (default: True)

CTWCompressor

class CTWCompressor:
    def __init__(self, settings: CTWSettings | None = None)
    def encode(self, data: bytes) -> bytes
    def decode(self, compressed: bytes) -> bytes

Development

git clone https://github.com/daedalus/zctw.git
cd zctw
pip install -e ".[test]"

# run tests
pytest

# format
ruff format src/ tests/

# lint
ruff check src/ tests/

# type check
mypy src/

License

MIT License - see LICENSE file.