Real-World Examples

Impressive real-world applications built with Shed Skin

Overview

While Shed Skin is excellent for compute-intensive algorithms, some of the most impressive examples are full-featured applications that demonstrate its ability to handle complex, real-world software. This page highlights the most notable examples that showcase Shed Skin’s practical capabilities.

DOOM Renderer

Lines of code: 666
Category: Game engine
Speed: ~10-20x faster than CPython

A complete WAD (game data file) rendering engine that can play DOOM levels with impressive performance.

What it does

• Loads and parses DOOM1.WAD files
• Renders 3D environments using classic DOOM algorithms
• Handles player movement and game state
• Plays background music (FLAC support)

Performance Impact

Watch this video demonstrating the dramatic difference in performance before and after Shed Skin compilation. The compiled version runs smoothly at playable frame rates, while the Python version is extremely sluggish.

Running the Example

cd examples/doom

# Download DOOM1.WAD (shareware version)
# https://doomwiki.org/wiki/DOOM1.WAD

# Compile as extension module
shedskin build -e doom.py
cp build/doom.so .

# Run
python doom_main.py

Code Snippet

The DOOM example showcases complex data structure handling and real-time rendering algorithms that benefit greatly from compilation.

Commodore 64 Emulator

Lines of code: 3,332
Category: Emulator
Speed: Fast enough for real-time emulation

A full Commodore 64 emulator that runs classic C64 programs and games.

Features

• Complete 6502 CPU emulation
• VIC-II graphics chip emulation
• SID sound chip emulation
• CIA timer/IO emulation
• Loads T64, D64, and PRG files
• Sprite handling
• Joystick support

Project Structure

c64/
  c64/
    c64.py          # Main emulator
    cpu.py          # 6502 CPU core
    vic_ii.py       # Video chip
    sid.py          # Sound chip
    cia.py          # IO chip
    memory.py       # Memory management
    mmu.py          # Memory mapping
    loaders/        # File format loaders

Running the Example

cd examples/c64/c64
shedskin build -e c64
cp build/c64.so .
cd ..
python c64_main.py --tape=intkarat.t64

# Then in the emulator:
load
run

Why It’s Impressive

Emulating a complete computer system requires:

• Cycle-accurate CPU emulation
• Real-time graphics rendering
• Complex state management
• Proper timing and synchronization

Shed Skin’s performance makes this possible in Python, achieving frame rates suitable for interactive use.

Pylot Ray Tracer

Lines of code: 943
Category: Graphics rendering
Features: Multiprocessing support

A sophisticated ray tracer that produces photorealistic images with advanced lighting effects.

Features

• Realistic lighting and shadows
• Reflection and refraction
• Multiple primitive types (spheres, planes, etc.)
• Multiprocessing for parallel rendering
• High-quality output

Running the Example

cd examples/pylot/pylot
shedskin build -e SimpleGeometry
cp build/SimpleGeometry.so .
cd ..
python pylot_main.py

Performance

Ray tracing is extremely compute-intensive, making it an ideal use case for Shed Skin. The compiled version achieves 20-40x speedup over pure Python, turning impractical render times into reasonable ones.

PyCSG - Constructive Solid Geometry

Lines of code: 212
Category: 3D modeling

Constructive Solid Geometry (CSG) allows complex 3D shapes to be created by combining simple primitives using boolean operations (union, intersection, subtraction).

Capabilities

• Boolean operations on 3D solids
• STL file export
• Complex geometric calculations
• Mesh generation

Code Example

# Example CSG operations (simplified)
def csg_union(solid1, solid2):
    # Combine two solids
    result = clip_to(solid1, solid2)
    result.extend(clip_to(solid2, solid1))
    return result

def csg_subtract(solid1, solid2):
    # Subtract solid2 from solid1
    a = clip_to(solid1, solid2, invert=True)
    b = clip_to(solid2, solid1, invert=True)
    return a + invert(b)

Use Cases

• 3D modeling and CAD
• Procedural geometry generation
• Game level design
• 3D printing preparation

Othello Engine

Lines of code: 341 (othello2)
Category: Game AI

A strong Othello (Reversi) game engine with sophisticated AI.

Features

• Alpha-beta pruning search
• Position evaluation
• Move generation and validation
• Human vs Computer play
• Strong playing strength

Code Example

def alphabeta(board, depth, alpha, beta, player):
    """Alpha-beta pruning search algorithm"""
    if depth == 0:
        return evaluate(board)
    
    moves = legal_moves(board, player)
    if not moves:
        return evaluate(board)
    
    best_score = -infinity
    for move in moves:
        new_board = make_move(board, move, player)
        score = -alphabeta(new_board, depth-1, -beta, -alpha, -player)
        best_score = max(best_score, score)
        alpha = max(alpha, score)
        if alpha >= beta:
            break  # Beta cutoff
    
    return best_score

Performance Impact

Board game AI requires evaluating millions of positions. Shed Skin’s speedup allows:

• Deeper search (more moves ahead)
• Stronger play within time limits
• Real-time interactive response

Chess Engine

Lines of code: 316 (chess), 285 (sunfish)
Category: Game AI

Two different chess engines demonstrating different design approaches.

Chess.py Features

• Alpha-beta search with quiescence
• Move generation using the 0x88 board representation
• Position evaluation
• Legal move validation

Code Example

def alphaBeta(board, alpha, beta, n):
    """Alpha-beta search with quiescence"""
    if n == 0:
        return alphaBetaQui(board, alpha, beta, n)
    
    bestMove = iNone
    for mv in legalMoves(board):
        newboard = copy(board)
        move(newboard, mv)
        value = alphaBeta(newboard, -beta, -alpha, n - 1)
        value = (-value[0], value[1])
        
        if value[0] >= beta:
            return (beta, mv)
        if value[0] > alpha:
            alpha = value[0]
            bestMove = mv
    
    return (alpha, bestMove)

0x88 Board Representation

setup = (4, 2, 3, 5, 6, 3, 2, 4, iNone, iNone) + \
        (iTrue,)*4 + (iNone, iNone) + \
        (1,) * 8 + ...

squares = tuple([i for i in range(128) if not i & 8])
knightMoves = (-33, -31, -18, -14, 14, 18, 31, 33)

The 0x88 trick uses a 160-element array (16x10) where the extra space allows fast boundary checking using bitwise operations.

NES Emulator (Pygasus)

Lines of code: 1,510
Category: Emulator

A Nintendo Entertainment System emulator capable of running classic NES games.

Features

• 6502 CPU emulation
• PPU (Picture Processing Unit) graphics
• APU (Audio Processing Unit) sound
• Mapper support for different cartridge types
• Controller input

Performance Requirements

NES emulation requires:

• Processing ~1.79 MHz CPU cycles
• Rendering 60 frames per second
• Audio generation at 44.1 kHz
• Real-time synchronization

Shed Skin makes this achievable with reasonable performance.

Advanced Ray Tracers

MiniLight

Lines of code: 442
Category: Global illumination

An advanced ray tracer implementing physically-based rendering:

• Monte Carlo path tracing
• Global illumination
• Realistic light transport
• HDR output

Path Tracing

Lines of code: 219
Category: Ray tracing

Modern path tracing algorithm:

• Unbiased rendering
• Physically accurate materials
• Indirect lighting
• Soft shadows and ambient occlusion

Performance Comparison

# Typical ray tracing inner loop
def trace_ray(ray, depth):
    if depth > max_depth:
        return background_color
    
    hit = find_nearest_intersection(ray)
    if not hit:
        return background_color
    
    # Compute lighting
    color = ambient * hit.material.color
    
    for light in lights:
        shadow_ray = Ray(hit.point, light.position)
        if not is_occluded(shadow_ray):
            color += compute_lighting(hit, light)
    
    # Reflection
    if hit.material.reflective:
        reflect_ray = compute_reflection(ray, hit)
        color += trace_ray(reflect_ray, depth + 1)
    
    return color

This type of code runs 20-40x faster with Shed Skin, making high-quality renders practical.

Compression Algorithms

Tarsalzp

Lines of code: 868
Category: Data compression

A sophisticated data compression algorithm implementing:

• LZMA-style compression
• Range encoding
• Dictionary compression
• High compression ratios

Performance Critical Code

Compression algorithms involve:

• Heavy bit manipulation
• Hash table operations
• Sequential data processing
• Buffer management

Shed Skin’s compiled output handles these operations efficiently, achieving 15-25x speedup.

Scientific Computing

Quantum Monte Carlo (Quameon)

Lines of code: 1,194
Category: Quantum physics simulation

Quantum Monte Carlo algorithms for simulating quantum systems:

• Variational Monte Carlo
• Diffusion Monte Carlo
• Random walk simulations
• Statistical analysis

Barnes-Hut Simulation

Lines of code: 404
Category: N-body physics

Efficient gravitational force calculation:

def barnes_hut(bodies):
    # Build quadtree
    root = build_tree(bodies)
    
    # Calculate forces
    for body in bodies:
        force = calculate_force_recursive(body, root)
        body.apply_force(force)
    
    # Update positions
    for body in bodies:
        body.update_position(dt)

The Barnes-Hut algorithm reduces N-body simulation from O(N²) to O(N log N), and Shed Skin makes it fast enough for real-time visualization.

Why These Examples Matter

These real-world examples demonstrate that Shed Skin can handle:

1. Large codebases: Thousands of lines of complex code
2. Complex algorithms: Emulators, game engines, ray tracers
3. Real-time performance: Interactive applications and simulations
4. Multiple modules: Projects spanning many files
5. Extension modules: Integration with existing Python code

Running Examples with GUI

Many examples require pygame or other graphics libraries:

# Install dependencies
pip install pygame

# For extension modules
cd examples/doom
shedskin build -e doom.py
cp build/doom.so .
python doom_main.py

Performance Summary

Example	Category	Lines	Typical Speedup
DOOM	Game Engine	666	10-20x
C64	Emulator	3,332	8-15x
Pylot	Ray Tracer	943	20-40x
Chess	Game AI	316	12-18x
Pygasus	Emulator	1,510	8-15x
MiniLight	Ray Tracer	442	20-35x
Quameon	Scientific	1,194	15-30x
Barnes-Hut	Physics	404	20-40x

Learning from Real-World Code

These examples are excellent for learning:

• Code organization: How to structure larger projects
• Type discipline: Maintaining consistent types throughout
• Performance patterns: What code patterns work well
• Module interaction: How to split code across files
• Extension design: Creating Python-importable modules

Explore the examples directory to see the full source code for all these projects.