How quancore/social-lstm works
Project type and purpose
• This is a research‐oriented machine‐learning pipeline for pedestrian trajectory forecasting (“Social LSTM implementation in PyTorch”).
• It includes data handling (train/validation/test splits), multiple LSTM model definitions (Social LSTM, Occupancy LSTM, Vanilla LSTM), training scripts, evaluation and visualization.
File‐structure analysis
• data/… — raw datasets organized into train, validation, test with subfolders per benchmark (biwi, crowds, stanford, mot).
• generator.py — synthetic data generator.
• utils.py & helper.py — data loaders, batching, common utilities.
• model.py, olstm_model.py, vlstm_model.py — neural‐network definitions.
• train.py, olstm_train.py, vlstm_train.py — training orchestrators for each model variant.
• validation.py — external evaluation logic.
• test.py — inference & output formatting for submission.
• hyperparameter.py — random hyperparameter selector.
• make_directories.sh — directory scaffolding.
Key insights from README
• Core stack: Python + PyTorch.
• Three model families share a common training/evaluation pipeline.
• Automatic directory creation and data‐flow handled by training scripts.
a. Components
• Data Storage (data/)
• Data Generation (generator.py)
• Preprocessing & Batching (utils.py, helper.py)
• Model Definitions (model.py, olstm_model.py, vlstm_model.py)
• Training Orchestrators (train.py, olstm_train.py, vlstm_train.py)
• Hyperparameter Selector (hyperparameter.py)
• Evaluation (validation.py)
• Inference & Submission (test.py)
• Setup Script (make_directories.sh)
b. Relationships & data flow
1. Raw data → (generator.py for synthetic) → data/
2. data/ → utils.py/helper.py → batched datasets
3. batched data + hyperparameter.py → training scripts → model definitions → updated model weights
4. Trained model → validation.py → metrics → logs
5. Validated model → test.py → prediction output
7. make_directories.sh can be invoked at start of any training script to ensure directories exist
c. Architectural patterns & principles
• Modular separation: data layer, model layer, training/eval layer, visualization.
• Reuse: single utils/helpers across all model variants.
• Orchestrator scripts (train.py, olstm_train.py, vlstm_train.py) call common routines.
d. Technologies/Frameworks
• PyTorch for NN implementations.
• Bash for environment setup.
• Standard Python I/O libs for file handling.