Vikhrmodels/physics-generalization

---
language:
- en
- ru
license: apache-2.0
task_categories:
- text-generation
tags:
- physics
- simulation
- 2d-physics
- rigid-body
- pymunk
- synthetic
- scene-generation
size_categories:
- 1M<n<10M
---

# Physics Generalization Dataset

**1,000,020 diverse 2D rigid body physics simulation scenes** for training and evaluating LLMs on physics prediction tasks.

## Overview

This dataset contains procedurally generated physics simulations across **30 distinct scenario types** organized in 6 categories. Unlike typical physics datasets that only feature random objects falling in a box, this dataset covers a wide range of physical phenomena: collisions, stacking, ramps, pendulums, constraints, and mini-game-inspired physics.

Each scene is a 200-frame simulation at 1/60s timestep using the Pymunk (Chipmunk2D) physics engine, exported in JSONL format with rich metadata.

## Dataset Structure

### Splits

| Split | Scenes | Scenario Types | Purpose |
|-------|--------|----------------|---------|
| **train** | 900,000 | 24 (seen only) | Training |
| **val** | 100,020 | 30 (seen + unseen) | Evaluation |

### Unseen Scenarios (held out from training)

6 scenario types appear **only in val**, enabling out-of-distribution generalization evaluation:

| Difficulty | Scenario | Description |
|-----------|----------|-------------|
| Simple | `pong` | Ball bouncing between two paddles (zero gravity) |
| Simple | `bowling` | Heavy ball rolling toward arranged pins |
| Simple | `ramp_roll` | Objects rolling down an inclined plane |
| Complex | `angry_birds` | Projectile launched at multi-layer block structure |
| Complex | `hourglass` | Objects falling through narrow gap between chambers |
| Complex | `newtons_cradle` | Balls suspended by pin joints, momentum transfer |

### Seen Scenarios (in both train and val)

24 scenario types with 37,500 samples each in train:

**Collision & Ballistics:** `billiards`, `breakout`, `explosion`, `head_on`, `projectile`

**Stacking & Structural:** `bridge`, `dominos`, `jenga`, `pyramid`, `tower`

**Ramps & Terrain:** `funnel`, `marble_run`, `plinko`, `ski_jump` (+ unseen `ramp_roll`)

**Pendulums & Constraints:** `chain`, `pendulum`, `seesaw`, `wrecking_ball` (+ unseen `newtons_cradle`)

**Mini-game Physics:** `basketball`, `pinball` (+ unseen `angry_birds`, `bowling`, `pong`)

**Complex & Chaotic:** `avalanche`, `conveyor`, `orbit`, `wind` (+ unseen `hourglass`)

## Data Format

Each scene is a JSONL file (1 header line + 200 frame lines).

### Header (line 1)
```json
{
"type": "scene_header",
"seed": 1315353,
"scenario_type": "explosion",
"scenario_category": "collision",
"difficulty": 4,
"description": "Explosion: 25 objects flying outward from center.",
"object_count": 25,
"gravity": {"x": 0.0, "y": -981.0},
"timestep": 0.016666666666666666,
"static_geometry": [...],
"constraints": [...],
"objects": [
{
"id": 0, "type": "circle",
"position": {"x": 401.23, "y": 302.45},
"material": {"mass": 2.5, "friction": 0.6, "elasticity": 0.7},
"radius": 15.3
}
]
}
```

### Frame (lines 2-201)
```json
{
"frame": 1,
"description": "Frame 1: All objects are in motion.",
"objects": [
{
"id": 0, "type": "circle",
"position": {"x": 415.67, "y": 318.90},
"velocity": {"x": 280.5, "y": 320.1},
"angle": 0.052,
"angular_velocity": 0.003,
"material": {"mass": 2.5, "friction": 0.6, "elasticity": 0.7}
}
]
}
```

## Key Features

- **30 scenario types** with qualitatively different physics (not just parameter variation)
- **Difficulty scaling** (1-5) per scenario: controls object count, velocity, structural complexity
- **Deterministic** generation via seed-based RNG
- **Constraints/Joints**: PinJoint, PivotJoint for pendulums, seesaws, chains, Newton's cradle
- **Custom static geometry**: ramps, funnels, peg grids, bumpers, hourglass chambers, basketball hoops
- **Rich text descriptions** for each scene (useful as LLM context)
- **Zero gravity** scenarios: billiards, pong, orbit
- **Initial velocities**: projectiles, explosions, head-on collisions (not just "objects at rest")
- **Clean train/unseen split** for generalization evaluation

## Physics Engine

- **Pymunk** (Python wrapper for Chipmunk2D)
- Scene: 800×600 pixels
- Fixed timestep: 1/60s
- Elasticity always < 1.0 (energy conservation, no Pymunk instability)
- Threading disabled (determinism)

## Generation

Generated using 22 CPU cores in ~29 minutes at ~578 scenes/sec.

```bash
python scripts/generate_scenarios_dataset.py --split all --workers 22
```

## File Organization

```
data_scenarios/
├── manifest.json # Split config, seen/unseen lists
├── train/
│ ├── avalanche/ # 37,500 scenes
│ ├── basketball/
│ ├── ... # 24 scenario type directories
│ └── wrecking_ball/
└── val/
├── angry_birds/ # 3,334 scenes (UNSEEN)
├── avalanche/
├── bowling/ # 3,334 scenes (UNSEEN)
├── ... # 30 scenario type directories
└── wind/
```

## Citation

Part of a research project on training LLMs to predict 2D rigid body physics.

This dataset contains 1,000,020 diverse 2D rigid body physics simulation scenes for training and evaluating LLMs on physics prediction tasks. It covers 30 distinct scenario types organized into 6 categories, including collisions, stacking, ramps, pendulums, constraints, and mini-game-inspired physics. Each scene is a 200-frame simulation generated using the Pymunk (Chipmunk2D) physics engine, exported in JSONL format with rich metadata. The dataset is split into a training set with 900,000 scenes covering 24 scenario types and a validation set with 100,020 scenes, including 6 unseen scenario types for evaluating model generalization. Key features include scenario diversity, difficulty scaling, deterministic generation, and rich text descriptions.

搜集汇总

背景与挑战

背景概述

该数据集包含1,000,020个多样化的2D刚体物理模拟场景，用于训练和评估大型语言模型在物理预测任务上的表现。它覆盖30种不同的场景类型，包括碰撞、堆叠、斜坡等，并分为训练集和验证集，其中验证集包含6种未见场景以测试模型的泛化能力。数据以JSONL格式提供，包含丰富的元数据和文本描述，支持物理模拟的详细分析。