DREAMS: A Social Exchange Theory-Informed Modeling of Misinformation Engagement on Social Media

Disentangled Representations and Episodic Adaptive Modeling for Social Media Engagements

Project Structure

├── encoders.py          # Multi-modal encoders and disentanglement
├── memory.py           # Dual-timescale adapters and episodic memory
├── backbone.py         # Transformer backbone architecture
├── mamba_backbone.py   # Mamba state-space model backbone
├── adaptation.py       # FiLM and normalizing flow modules
├── heads.py           # Prediction heads for outputs
├── replay.py          # Replay buffer and DREAMS augmentation
├── model.py           # Complete integrated model
├── train.py           # Training script and trainer class
├── main.py            # Main entry point
├── config.json        # Configuration template
├── config_mamba_examples.json  # Example configs for Mamba variants
└── requirements.txt   # Python dependencies

Installation

# Clone the repository
git clone <repository-url>
cd DREAMS

# Install dependencies
pip install -r requirements.txt

Usage

Quick Start

Run with default configuration:

python main.py

Custom Configuration

1. Create a configuration file based on the template:

cp config.json my_config.json
# Edit my_config.json with your settings

2. Train with custom configuration:

python main.py --config my_config.json --output-dir experiments/exp1

Command Line Arguments

python main.py \
    --config config.json \
    --batch-size 64 \
    --epochs 200 \
    --lr 1e-3 \
    --device cuda \
    --resume checkpoint.pth \
    --output-dir output/

Resume Training

python main.py --resume output/checkpoint_epoch_50.pth

Configuration

The model is highly configurable through the JSON configuration file:

Data Configuration

• input_dim_o: Observation dimension (default: 128)
• input_dim_p: Platform dimension (default: 64)
• input_dim_t: Time dimension (default: 32)
• input_dim_x: History feature dimension (default: 100)

Model Architecture

• d_model: Transformer model dimension (default: 512)
• nhead: Number of attention heads (default: 8)
• num_layers: Number of transformer layers (default: 6)
• memory_size: Episodic memory capacity (default: 1000)
• num_platforms: Number of platforms for FiLM (default: 10)

Training Parameters

• batch_size: Training batch size (default: 32)
• num_epochs: Number of training epochs (default: 100)
• learning_rate: Base learning rate (default: 1e-4)
• optimizer: Optimizer type ('adam', 'adamw', 'sgd')
• scheduler: LR scheduler type ('cosine', 'step', 'plateau')

Loss Weights

• lambda_dis: Disentanglement loss weight (default: 0.1)
• lambda_rep: Replay loss weight (default: 0.05)
• beta_kl: KL divergence weight (default: 1.0)

Backbone Architectures

1. Transformer (Original)

Traditional multi-head attention transformer with quadratic complexity O(n²).

2. Mamba

State-space model with linear complexity O(n). Key features:

• Selective SSM: Selective state space model with input-dependent parameters
• Hardware-aware: Optimized parallel scan algorithm
• Efficient: Linear time and constant memory complexity

3. BiMamba

Bidirectional variant of Mamba that processes sequences in both directions:

• Forward and backward processing paths
• Captures bidirectional dependencies
• Useful for non-causal tasks

4. Hybrid Mamba-Transformer

Combines Mamba and Transformer layers:

• Mamba layers for efficient local pattern processing
• Transformer layers for global attention
• Configurable layer arrangement

Using Different Backbones

Transformer (Default)

{
  "model": {
    "backbone_type": "transformer",
    "d_model": 512,
    "nhead": 8,
    "num_layers": 6,
    "dim_feedforward": 2048
  }
}

Mamba

{
  "model": {
    "backbone_type": "mamba",
    "d_model": 512,
    "num_layers": 6,
    "d_state": 16,
    "d_conv": 4,
    "expand": 2
  }
}

BiMamba

{
  "model": {
    "backbone_type": "bimamba",
    "d_model": 512,
    "num_layers": 6,
    "d_state": 16,
    "d_conv": 4,
    "expand": 2
  }
}

Hybrid

{
  "model": {
    "backbone_type": "hybrid",
    "d_model": 512,
    "num_layers": 6,
    "nhead": 8,
    "dim_feedforward": 2048,
    "d_state": 16,
    "d_conv": 4,
    "expand": 2,
    "mamba_layers": [0, 2, 4]
  }
}

Training with Different Backbones

# Train with Mamba backbone
python main.py --config config_mamba_examples.json


# Train with Hybrid
python main.py --config config_hybrid.json

DREAMS Components

1. Encoders (encoders.py)

• BaseEncoder: Generic encoder for any modality
• ContextMLP: Combines encoded features
• MultiModalEncoder: Complete encoding pipeline with disentanglement

2. Memory Modules (memory.py)

• DualTimescaleAdapter: Fast/slow temporal processing
• AdaptiveMixing: Learned mixing of memory features
• EpisodicMemory: Long-term memory with attention retrieval
• WriteGate: Controlled memory writing

3. Backbone (backbone.py)

• TransformerBackbone: Main transformer architecture
• PositionalEncoding: Positional embeddings
• ProjectionLayer: Dimension mapping

4. Adaptation (adaptation.py)

• FiLM: Platform-specific modulation
• NormalizingFlow: Feature distribution matching
• CouplingLayer: Building block for normalizing flows

5. Prediction Heads (heads.py)

• BaseHead: Generic prediction head
• PredictionHeads: Multiple specialized heads
• MultiTaskHead: Shared representation for multi-task learning

6. Replay Buffer (replay.py)

• ReplayBuffer: Standard experience replay
• PrioritizedReplayBuffer: Prioritized sampling

Training Pipeline

The training follows this algorithm:

1. Encode inputs through modality-specific encoders
2. Disentangle representations and project onto unit sphere
3. Process temporal features with dual-timescale adapters
4. Transform through backbone transformer
5. Retrieve from episodic memory
6. Apply normalizing flow for distribution matching
7. Adapt with platform-specific FiLM
8. Predict outputs through specialized heads
9. Update episodic memory with gating
10. Store experiences in replay buffer

Monitoring

Training progress is logged to TensorBoard:

tensorboard --logdir runs/experiment

Tracked metrics include:

• Loss components (total, prediction, disentanglement, replay)
• Learning rates per parameter group
• Memory utilization statistics
• Mixing weights and gate values

Extending the Model

Adding a New Encoder

# In encoders.py
class CustomEncoder(BaseEncoder):
    def __init__(self, input_dim, hidden_dim, output_dim):
        super().__init__(input_dim, hidden_dim, output_dim)
        # Add custom layers
        
    def forward(self, x):
        # Custom forward pass
        return encoded

Creating Custom Augmentation

# In replay.py
class CustomDREAMS(DREAMS):
    def custom_augment(self, x):
        # Your augmentation logic
        return augmented_x

Implementing New Heads

# In heads.py
class CustomHead(BaseHead):
    def __init__(self, input_dim, output_dim):
        super().__init__(input_dim, [256, 128], output_dim)
        # Add custom architecture

Performance Tips

1. Gradient Accumulation: For larger effective batch sizes
2. Mixed Precision Training: Use torch.cuda.amp for faster training
3. Data Parallelism: Distribute across multiple GPUs
4. Efficient Data Loading: Increase num_workers in DataLoader
5. Memory Management: Adjust memory_size and buffer_capacity

Troubleshooting

Out of Memory

• Reduce batch_size
• Decrease d_model or num_layers
• Use gradient checkpointing
• Reduce memory_size

Slow Training

• Enable mixed precision training
• Use multiple GPUs with DataParallel
• Increase num_workers for data loading
• Use SSD for data storage

Poor Performance

• Adjust learning rates per module
• Tune loss weights (λ_dis, λ_rep)
• Increase model capacity
• Add more augmentation in DREAMS

License

This project is licensed under the MIT License - see the LICENSE file for details.