Skip to content

WASM_INSTALLATION.md

Latest commit

 

History

History
431 lines (310 loc) · 10.5 KB

WASM_INSTALLATION.md

File metadata and controls

431 lines (310 loc) · 10.5 KB

WASM Installation Guide

Overview

The Multilingual Programming Language includes optional WebAssembly (WASM) support for potentially significant performance improvements on compute-intensive operations while maintaining Python compatibility through automatic fallback.

Key Features:

  • ✅ Potential speedups for matrix ops, crypto, and scientific computing (benchmark-dependent)
  • ✅ Zero code changes required - transparent backend selection
  • ✅ Automatic Python fallback if WASM unavailable
  • ✅ Works on Windows, Linux, macOS
  • ✅ Supports Python 3.12+ (full features 3.12+)

Installation Options

Option 1: Minimal Installation (Python Only)

pip install multilingualprogramming

Features:

  • ✅ Full language support
  • ✅ 17 languages
  • ✅ All standard library modules
  • ⚠️ No WASM acceleration (Python fallback only)

Size: ~50 MB Dependencies: roman, python-dateutil

Option 2: Recommended Installation (Python + WASM)

pip install multilingualprogramming[wasm]

Features:

  • ✅ Full language support
  • ✅ Potential acceleration on matrix, crypto, and scientific computing
  • ✅ Potential acceleration on JSON parsing (workload-dependent)
  • ✅ Automatic fallback to Python

Requirements:

  • Python 3.12+
  • wasmtime runtime (auto-installed)

Size: ~150 MB (includes WASM binaries) Dependencies: roman, python-dateutil, wasmtime

Option 3: Performance Installation (Python + WASM + NumPy)

pip install multilingualprogramming[performance]

Features:

  • ✅ All WASM features
  • ✅ NumPy-optimized fallbacks (matrix ops up to 10x faster than pure Python)
  • ✅ Hybrid execution (WASM where available, NumPy where not)
  • ✅ Best of both worlds

Size: ~250 MB (includes NumPy + WASM) Dependencies: roman, python-dateutil, wasmtime, numpy

Detailed Setup Instructions

Linux Installation

# Python 3.12+
python3 -m pip install multilingualprogramming[wasm]

# Verify installation
python3 -c "from multilingualprogramming.runtime.backend_selector import BackendSelector; print('✓ Installed successfully')"

# Check WASM availability
python3 -c "from multilingualprogramming.runtime.backend_selector import BackendSelector; s = BackendSelector(); print(f'WASM Available: {s.is_wasm_available()}')"

macOS Installation

# Homebrew (optional, for dependencies)
brew install python@3.12

# Install package
python3 -m pip install multilingualprogramming[wasm]

# Verify
python3 -c "from multilingualprogramming.runtime import backend_selector; print('✓ Installed')"

Windows Installation

# PowerShell (run as normal user, not admin)
python -m pip install multilingualprogramming[wasm]

# Verify
python -c "from multilingualprogramming.runtime.backend_selector import BackendSelector; print('WASM Available:', BackendSelector().is_wasm_available())"

Verifying Installation

Quick Test

from multilingualprogramming.runtime.backend_selector import BackendSelector, Backend

# Create selector with auto-detection
selector = BackendSelector()

# Test with Python fallback
print(f"WASM Available: {selector.is_wasm_available()}")

# Run a test operation
result = selector.call_function("fibonacci", 10)
print(f"Fibonacci(10): {result}")

Comprehensive Check

#!/usr/bin/env python3
import sys
import platform
from multilingualprogramming.runtime.backend_selector import BackendSelector
from multilingualprogramming.runtime.python_fallbacks import (
    MatrixOperations,
    NumericOperations,
)

print("="*60)
print("Multilingual Programming - WASM Installation Check")
print("="*60)

# System info
print(f"\n1. System Information:")
print(f"   Platform: {platform.system()}")
print(f"   Python: {sys.version}")
print(f"   Architecture: {platform.machine()}")

# WASM check
selector = BackendSelector()
print(f"\n2. WASM Support:")
print(f"   Available: {selector.is_wasm_available()}")
print(f"   Selector: {selector}")

# Fallback check
print(f"\n3. Fallback Functions:")
from multilingualprogramming.runtime.python_fallbacks import FALLBACK_REGISTRY
print(f"   Registered: {len(FALLBACK_REGISTRY)} functions")

# Test operations
print(f"\n4. Basic Operations:")
try:
    fib = NumericOperations.fibonacci(10)
    print(f"   ✓ Fibonacci(10): {fib}")

    result = MatrixOperations.multiply([[1, 2], [3, 4]], [[5, 6], [7, 8]])
    print(f"   ✓ Matrix multiply: success")
except Exception as e:
    print(f"   ✗ Error: {e}")

print("\n" + "="*60)
if selector.is_wasm_available():
    print("✓ WASM support enabled - benchmark your workload for observed speedups.")
else:
    print("⚠ WASM not available - using Python fallback")
    print("  To enable WASM: pip install wasmtime")
print("="*60 + "\n")

Troubleshooting

Issue: "ModuleNotFoundError: No module named 'wasmtime'"

Solution:

pip install wasmtime
# or
pip install multilingualprogramming[wasm]

Issue: WASM Not Available on macOS/ARM64

Status: WASM support on ARM64 is being added in PyPI Distribution Workaround: Use Python fallback

from multilingualprogramming.runtime.backend_selector import BackendSelector, Backend
selector = BackendSelector(prefer_backend=Backend.PYTHON)

Issue: Performance Not Improved

Checklist:

  1. Verify WASM is available:

    from multilingualprogramming.runtime.backend_selector import BackendSelector
print(BackendSelector().is_wasm_available())

  2. Ensure operation is registered:

    from multilingualprogramming.runtime.python_fallbacks import FALLBACK_REGISTRY
print("operation_name" in FALLBACK_REGISTRY)

  3. Check current backend:

    selector = BackendSelector()
print(f"Current selector: {selector}")

Issue: ImportError on Windows

Solution: Install redistributables

# Windows Visual C++ Redistributables
# Download from: https://support.microsoft.com/en-us/help/2977003

# Or use vcpkg
vcpkg install wasmtime:x64-windows

Configuration

Python Code Configuration

from multilingualprogramming.runtime.backend_selector import BackendSelector, Backend

# Force Python fallback (always works)
selector_python = BackendSelector(prefer_backend=Backend.PYTHON)
result = selector_python.call_function("fibonacci", 10)

# Auto-detect (WASM if available, else Python)
selector_auto = BackendSelector(prefer_backend=Backend.AUTO)
result = selector_auto.call_function("matrix_multiply", a, b)

# Force WASM (will fail if unavailable)
selector_wasm = BackendSelector(prefer_backend=Backend.WASM)
try:
    result = selector_wasm.call_function("fibonacci", 10)
except RuntimeError as e:
    print(f"WASM not available: {e}")

Environment Variables

# Backend selection for runtime is controlled in code:
#   BackendSelector(prefer_backend=Backend.AUTO | Backend.WASM | Backend.PYTHON)

# For test suites only (tests/conftest.py):
export WASM_BACKEND=auto      # default
export WASM_BACKEND=wasm      # force WASM tests
export WASM_BACKEND=fallback  # force Python fallback tests

Performance Expectations

Speedup by Operation

The numbers below are illustrative benchmark results, not guaranteed performance.

Operation Python WASM Speedup
Matrix 1000×1000 multiply 5.0s 50ms 100x
Matrix 100×100 multiply 50ms 1ms 50x
XOR cipher (1MB) 500ms 5ms 100x
Fibonacci(30) 200ms 2ms 100x
JSON parse (10MB) 200ms 20ms 10x
Blur 4K image 2s 40ms 50x

When You'll See Benefits

High speedup potential (benchmark-dependent):

  • Matrix operations with n > 100
  • Cryptographic operations
  • Scientific computing (Monte Carlo, numerical integration)
  • Large-scale data processing

Moderate speedup (10x):

  • JSON parsing of large documents
  • Image processing
  • String operations

Minimal speedup (<5x):

  • Small arrays/matrices
  • Simple operations (likely overhead > benefit)

Uninstalling WASM Support

To keep multilingual, remove WASM only

pip uninstall wasmtime
# Then use with Python fallback

Complete uninstall

pip uninstall multilingualprogramming

System Requirements

Minimum Requirements

Component Requirement
Python 3.12+
RAM 256 MB
Disk 50 MB (Python only)
OS Windows, Linux, macOS, BSD

Recommended Requirements (WASM)

Component Requirement
Python 3.12+
RAM 512 MB
Disk 150 MB (with WASM)
OS Windows, Linux, macOS
CPU Any (benefits most with 64-bit)

Building from Source (Advanced)

For Contributing to WASM Development

git clone https://github.com/johnsamuelwrites/multilingual.git
cd multilingual

# Install development dependencies
pip install -e ".[dev,wasm]"

# Run tests
pytest tests/wasm_corpus_test.py
pytest tests/wasm_comprehensive_test.py

# Validate WASM codegen and backend wiring
pytest tests/wasm_codegen_poc_test.py

Supported Platforms

Tier 1 (Fully Supported)

  • ✅ Linux x86_64 (Ubuntu 18.04+, Debian 10+, CentOS 7+)
  • ✅ Windows x86_64 (Windows 7+, Server 2012+)
  • ✅ macOS x86_64 (10.11+)
  • ✅ macOS ARM64 (11.0+) - WASM via emulation

Tier 2 (Community Support)

  • ⚠️ Linux ARM64 (aarch64)
  • ⚠️ Windows ARM64
  • ⚠️ BSD variants
  • ⚠️ 32-bit systems

Getting Help

Documentation

Support Channels

Reporting Issues

When reporting WASM issues, please include:

import sys
import platform
from multilingualprogramming.runtime.backend_selector import BackendSelector

print(f"Python: {sys.version}")
print(f"Platform: {platform.system()} {platform.machine()}")
print(f"WASM: {BackendSelector().is_wasm_available()}")

Next Steps

  1. ✅ Install: pip install multilingualprogramming[wasm]
  2. ✅ Verify: Run quick test above
  3. ✅ Learn: Check WASM Development Guide
  4. ✅ Optimize: Follow Performance Tuning Guide
  5. ✅ Contribute: Join development!

Version: PyPI Distribution Final Last Updated: February 22, 2026 Status: Stable; validate for your workload/platform requirements.