Examples

Complete examples demonstrating DREAM in real-world scenarios.

Example 1: Speech Recognition

End-to-end speech recognition with MFCC features.

import torch
import torch.nn as nn
import torchaudio
from dream import DREAM

# Load audio
waveform, sr = torchaudio.load('audio.wav')
waveform = torchaudio.functional.resample(waveform, sr, 16000)

# Extract MFCC features
mfcc_transform = torchaudio.transforms.MFCC(
    sample_rate=16000,
    n_mfcc=13,
    melkwargs={'n_mels': 40, 'hop_length': 160}
)
mfcc = mfcc_transform(waveform)

# Add delta features
delta = torchaudio.functional.compute_deltas(mfcc)
delta2 = torchaudio.functional.compute_deltas(delta)
features = torch.cat([mfcc, delta, delta2], dim=0)  # 39 features

# Transpose: (features, time) → (1, time, features)
x = features.transpose(0, 1).unsqueeze(0)

# Model
model = DREAM(input_dim=39, hidden_dim=256, rank=16)
classifier = nn.Linear(256, 40)  # 40 phoneme classes

# Process
output, final_state = model(x, return_sequences=False)
logits = classifier(final_state.h)
predictions = logits.argmax(dim=-1)

print(f"Predicted phoneme: {predictions.item()}")

Full Training Pipeline

import torch
import torch.nn as nn
from torch.utils.data import Dataset, DataLoader
from dream import DREAM

class SpeechDataset(Dataset):
    def __init__(self, audio_paths, labels):
        self.audio_paths = audio_paths
        self.labels = labels
    
    def __getitem__(self, idx):
        # Load and extract features
        waveform, sr = torchaudio.load(self.audio_paths[idx])
        waveform = torchaudio.functional.resample(waveform, sr, 16000)
        
        mfcc = torchaudio.transforms.MFCC(
            sample_rate=16000,
            n_mfcc=13,
            melkwargs={'n_mels': 40, 'hop_length': 160}
        )(waveform)
        
        delta = torchaudio.functional.compute_deltas(mfcc)
        delta2 = torchaudio.functional.compute_deltas(delta)
        features = torch.cat([mfcc, delta, delta2], dim=0)
        
        return features.transpose(0, 1), self.labels[idx]
    
    def __len__(self):
        return len(self.audio_paths)

# Collate function for variable-length sequences
def collate_fn(batch):
    features, labels = zip(*batch)
    lengths = torch.tensor([f.shape[0] for f in features])
    
    # Pad to max length
    max_len = lengths.max()
    padded = torch.zeros(len(features), max_len, 39)
    for i, f in enumerate(features):
        padded[i, :f.shape[0]] = f
    
    return padded, torch.tensor(labels), lengths

# Create dataset and loader
dataset = SpeechDataset(audio_paths, labels)
loader = DataLoader(dataset, batch_size=32, collate_fn=collate_fn)

# Model
model = DREAM(input_dim=39, hidden_dim=256, rank=16)
classifier = nn.Linear(256, 40)

# Training
optimizer = torch.optim.AdamW(
    list(model.parameters()) + list(classifier.parameters()),
    lr=1e-3
)
criterion = nn.CrossEntropyLoss()

for epoch in range(20):
    for batch_x, batch_y, lengths in loader:
        optimizer.zero_grad()
        
        # Process with masking
        output, state = model.forward_with_mask(batch_x, lengths)
        
        # Use final state for classification
        logits = classifier(state.h)
        loss = criterion(logits, batch_y)
        
        loss.backward()
        torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
        optimizer.step()
    
    print(f"Epoch {epoch}: Loss = {loss.item():.4f}")

Example 2: Time Series Forecasting

Predict future values based on historical time series data.

import torch
import torch.nn as nn
from dream import DREAM

class Forecaster(nn.Module):
    def __init__(self, input_dim, hidden_dim, forecast_horizon):
        super().__init__()
        self.encoder = DREAM(input_dim, hidden_dim)
        self.decoder = nn.Linear(hidden_dim, forecast_horizon)

    def forward(self, x):
        # x: (batch, time, input_dim)
        _, final_state = self.encoder(x, return_sequences=False)
        prediction = self.decoder(final_state.h)  # (batch, horizon)
        return prediction

# Usage
model = Forecaster(input_dim=10, hidden_dim=64, forecast_horizon=5)

# Training data: 50 timesteps, predict next 5
x = torch.randn(32, 50, 10)
y = torch.randn(32, 5)  # Target: next 5 timesteps

pred = model(x)
print(f"Prediction shape: {pred.shape}")  # (32, 5)

# Training
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
criterion = nn.MSELoss()

for epoch in range(100):
    optimizer.zero_grad()
    pred = model(x)
    loss = criterion(pred, y)
    loss.backward()
    optimizer.step()
    
    if epoch % 10 == 0:
        print(f"Epoch {epoch}: Loss = {loss.item():.4f}")

Multi-Step Forecasting

class MultiStepForecaster(nn.Module):
    def __init__(self, input_dim, hidden_dim, forecast_horizon):
        super().__init__()
        self.encoder = DREAM(input_dim, hidden_dim)
        self.decoder = DREAM(input_dim, hidden_dim)
        self.output_layer = nn.Linear(hidden_dim, input_dim)
        self.forecast_horizon = forecast_horizon

    def forward(self, x):
        # Encode history
        _, enc_state = self.encoder(x, return_sequences=False)
        
        # Decode future (autoregressive)
        predictions = []
        last_output = x[:, -1:, :]  # Start with last input
        
        for _ in range(self.forecast_horizon):
            output, enc_state = self.decoder(last_output, enc_state)
            next_pred = self.output_layer(output)
            predictions.append(next_pred)
            last_output = next_pred
        
        return torch.cat(predictions, dim=1)

# Usage
model = MultiStepForecaster(input_dim=10, hidden_dim=64, forecast_horizon=10)
x = torch.randn(32, 50, 10)
predictions = model(x)  # (32, 10, 10)

Example 3: Anomaly Detection

Detect anomalies in time series using reconstruction error.

import torch
import torch.nn as nn
from dream import DREAM

class AnomalyDetector(nn.Module):
    def __init__(self, input_dim, hidden_dim):
        super().__init__()
        self.model = DREAM(input_dim, hidden_dim)
        self.reconstructor = nn.Linear(hidden_dim, input_dim)

    def forward(self, x):
        # x: (batch, time, input_dim)
        output, _ = self.model(x, return_sequences=True)
        # Reconstruct input
        reconstruction = self.reconstructor(output)
        return reconstruction

    def anomaly_score(self, x):
        reconstruction = self.forward(x)
        # MSE between input and reconstruction
        error = (x - reconstruction) ** 2
        return error.mean(dim=-1)  # (batch, time)

# Train on normal data
model = AnomalyDetector(input_dim=20, hidden_dim=64)
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)

for epoch in range(50):
    for x in normal_data_loader:
        optimizer.zero_grad()
        reconstruction = model(x)
        loss = ((x - reconstruction) ** 2).mean()
        loss.backward()
        optimizer.step()

# Detect anomalies
model.eval()
with torch.no_grad():
    test_error = model.anomaly_score(test_data)
    anomalies = test_error > threshold  # Boolean mask
    
    print(f"Detected {anomalies.sum()} anomalies")

Threshold Selection

# Use validation data to set threshold
model.eval()
errors = []

with torch.no_grad():
    for x in val_loader:  # Normal data only
        error = model.anomaly_score(x).mean().item()
        errors.append(error)

# Set threshold at 95th percentile
threshold = torch.quantile(torch.tensor(errors), 0.95)
print(f"Anomaly threshold: {threshold:.4f}")

Example 4: Sequence Classification

Classify sequences into categories.

import torch
import torch.nn as nn
from dream import DREAM

class SequenceClassifier(nn.Module):
    def __init__(self, input_dim, hidden_dim, num_classes):
        super().__init__()
        self.encoder = DREAM(input_dim, hidden_dim)
        self.classifier = nn.Linear(hidden_dim, num_classes)

    def forward(self, x):
        _, final_state = self.encoder(x, return_sequences=False)
        return self.classifier(final_state.h)

# Usage
model = SequenceClassifier(input_dim=39, hidden_dim=256, num_classes=10)

x = torch.randn(32, 100, 39)  # Batch of sequences
labels = torch.randint(0, 10, (32,))  # Class labels

logits = model(x)
predictions = logits.argmax(dim=-1)

accuracy = (predictions == labels).float().mean()
print(f"Accuracy: {accuracy.item():.4f}")

With Attention Pooling

class AttentionClassifier(nn.Module):
    def __init__(self, input_dim, hidden_dim, num_classes):
        super().__init__()
        self.encoder = DREAM(input_dim, hidden_dim)
        self.attention = nn.Linear(hidden_dim, 1)
        self.classifier = nn.Linear(hidden_dim, num_classes)

    def forward(self, x):
        # Get all outputs
        output, _ = self.encoder(x, return_sequences=True)  # (batch, time, hidden)
        
        # Attention weights
        attn_weights = torch.softmax(self.attention(output), dim=1)  # (batch, time, 1)
        
        # Weighted sum
        context = (attn_weights * output).sum(dim=1)  # (batch, hidden)
        
        return self.classifier(context)

model = AttentionClassifier(input_dim=39, hidden_dim=256, num_classes=10)

Example 5: Language Modeling

Character-level language modeling.

import torch
import torch.nn as nn
from dream import DREAM

class LanguageModel(nn.Module):
    def __init__(self, vocab_size, embed_dim, hidden_dim):
        super().__init__()
        self.embedding = nn.Embedding(vocab_size, embed_dim)
        self.dream = DREAM(embed_dim, hidden_dim)
        self.output = nn.Linear(hidden_dim, vocab_size)

    def forward(self, x):
        # x: (batch, seq_len) token IDs
        embedded = self.embedding(x)  # (batch, seq_len, embed_dim)
        output, _ = self.dream(embedded, return_sequences=True)
        return self.output(output)

# Usage
vocab_size = 65  # ASCII characters
model = LanguageModel(vocab_size, embed_dim=64, hidden_dim=128)

# Training data
text = "hello world"
chars = sorted(list(set(text)))
char_to_idx = {c: i for i, c in enumerate(chars)}
idx_to_char = {i: c for i, c in enumerate(chars)}

# Prepare data
seq_len = 10
x = torch.tensor([[char_to_idx[c] for c in text[i:i+seq_len]] 
                  for i in range(len(text) - seq_len)])
y = torch.tensor([[char_to_idx[c] for c in text[i+1:i+seq_len+1]] 
                  for i in range(len(text) - seq_len)])

# Training
optimizer = torch.optim.Adam(model.parameters(), lr=1e-3)
criterion = nn.CrossEntropyLoss()

for epoch in range(100):
    optimizer.zero_grad()
    logits = model(x)
    loss = criterion(logits.view(-1, vocab_size), y.view(-1))
    loss.backward()
    torch.nn.utils.clip_grad_norm_(model.parameters(), max_norm=1.0)
    optimizer.step()
    
    if epoch % 10 == 0:
        print(f"Epoch {epoch}: Loss = {loss.item():.4f}")

# Generation
def generate(model, seed_text, length=50):
    model.eval()
    tokens = [char_to_idx.get(c, 0) for c in seed_text]
    
    with torch.no_grad():
        for _ in range(length):
            x = torch.tensor([tokens[-10:]])  # Last 10 tokens
            logits = model(x)
            next_token = logits[0, -1].argmax().item()
            tokens.append(next_token)
    
    return ''.join([idx_to_char[t] for t in tokens])

generated = generate(model, "hello", length=50)
print(f"Generated: {generated}")

Example 6: Online Learning

Continuously adapt to streaming data.

import torch
from dream import DREAM

# Model with high plasticity for online learning
model = DREAM(
    input_dim=64,
    hidden_dim=128,
    rank=16,
    base_plasticity=0.2,      # High plasticity
    forgetting_rate=0.02,     # Faster forgetting
    ltc_surprise_scale=20.0,  # High adaptivity
)

# Initialize state (persists across all data)
state = model.init_state(batch_size=1)

# Process streaming data
for data_point in data_stream:
    x = data_point.unsqueeze(0).unsqueeze(0)  # (1, 1, input_dim)
    
    # Process single timestep
    output, state = model(x, state)
    
    # Monitor surprise (adaptation signal)
    surprise = state.avg_surprise.item()
    
    if surprise > 0.7:
        print(f"High surprise detected: {surprise:.4f}")
        # Could trigger learning rate adjustment, alert, etc.
    
    # Use output for prediction
    prediction = output.squeeze()

Example 7: Multi-Task Learning

Share DREAM encoder across multiple tasks.

import torch
import torch.nn as nn
from dream import DREAM

class MultiTaskModel(nn.Module):
    def __init__(self, input_dim, hidden_dim, task_dims):
        super().__init__()
        # Shared encoder
        self.encoder = DREAM(input_dim, hidden_dim)
        
        # Task-specific heads
        self.task_heads = nn.ModuleDict({
            name: nn.Linear(hidden_dim, dim)
            for name, dim in task_dims.items()
        })

    def forward(self, x, task_name):
        _, final_state = self.encoder(x, return_sequences=False)
        return self.task_heads[task_name](final_state.h)

# Usage
model = MultiTaskModel(
    input_dim=39,
    hidden_dim=256,
    task_dims={
        'phoneme': 40,      # Phoneme classification
        'speaker': 10,      # Speaker identification
        'emotion': 6,       # Emotion recognition
    }
)

# Train on multiple tasks
for epoch in range(50):
    for task_name, (x, y) in task_loaders.items():
        optimizer.zero_grad()
        
        output = model(x, task_name)
        loss = criterion(output, y)
        
        loss.backward()
        optimizer.step()
        
        print(f"Task {task_name}: Loss = {loss.item():.4f}")

Next Steps

Troubleshooting - Common issues
Contributing - Contribute to DREAM
FAQ - Frequently asked questions

Examples

On this page