Generates synthetic datasets for the communicating vessels physics task. The agent must simulate fluid equalization across two or more connected vessels — the liquid columns flow through the connected base until all surfaces reach a common equilibrium height (Pascal's principle in the static limit).
Each sample pairs a task (first frame + prompt describing what needs to happen) with its ground truth solution (final frame showing the result + video demonstrating how to achieve it). This structure enables both model evaluation and training.
| Property | Value |
|---|---|
| Task ID | Multi-31 |
| Task | Communicating Vessels Equilibration |
| Category | Continuous Physics |
| Resolution | 1024×1024 px |
| FPS | 16 fps |
| Duration | varies |
| Output | PNG images + MP4 video |
# 1. Clone the repository
git clone https://github.com/VBVR-DataFactory/Multi-31_fluid_communicating_vessels_data-generator.git
cd Multi-31_fluid_communicating_vessels_data-generator
# 2. Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate # On Windows: venv\Scripts\activate
# 3. Install dependencies
pip install --upgrade pip
pip install -r requirements.txt
pip install -e .# Generate 50 samples
python examples/generate.py --num-samples 50
# Reproducible generation with seed
python examples/generate.py --num-samples 50 --seed 42
# Custom output directory
python examples/generate.py --num-samples 100 --output data/my_dataset
# Without videos (faster, images only)
python examples/generate.py --num-samples 50 --no-videos| Argument | Description |
|---|---|
--num-samples |
Number of tasks to generate (required) |
--output |
Output directory (default: data/questions) |
--seed |
Random seed for reproducibility |
--no-videos |
Skip video generation (images only) |
[Scenario] A system of communicating vessels with 4 vertical tubes is filled with yellow liquid. The initial liquid levels are uneven ([21, 37, 36, 2] cm), indicating an unstable state.
[Rules]
1. Fluid flows between the connected sections driven by gravity.
2. The liquid will continue to flow until it equalizes to a common height across all tubes.
[Task] Generate a video showing the liquid settling process. Simulate how the yellow liquid flows through the connected base, governed by gravity and the specific damping value (k=3.14) shown in the first frame, until it reaches a stable hydrostatic equilibrium. Hold the final frame.
 |
 |
 |
| Initial Frame Connected vessels with different liquid columns |
Animation Liquid flows through the base, oscillating then damping |
Final Frame All columns at common equilibrium height |
Simulate the temporal equalization of liquid columns in a communicating-vessel apparatus, where fluid flows through the shared base, oscillates around equilibrium with viscous damping, and ultimately settles at a common height determined by mass conservation.
- Vessels: Two or more vertical tubes connected at the bottom by a horizontal channel.
- Initial state: Each vessel starts with a different liquid column height.
- Equilibrium height: Computed from conservation of total volume across all vessels.
- Dynamics: Damped oscillation toward the equilibrium height, governed by a damping coefficient.
- Animation: Frame-by-frame interface heights tracked over time.
- Continuous-time physics: Unlike discrete-grid puzzles, this requires continuous spatiotemporal reasoning.
- Conservation law as bottleneck: The final state is fully determined by initial conditions via conservation of liquid volume — error in early prediction propagates to wrong equilibrium.
- Damped oscillatory transient: Models must capture both the overshoot/oscillation and the asymptotic settling — neither is trivial from initial frame alone.
- Visual fluid surfaces: Each frame shows continuous interface heights, supporting per-frame regression evaluation.
data/questions/Multi-31_fluid_communicating_vessels_data-generator_task/Multi-31_fluid_communicating_vessels_data-generator_00000000/
├── first_frame.png # Initial column heights
├── final_frame.png # Equilibrium state
├── prompt.txt # Task instruction
├── ground_truth.mp4 # Animation of equalization
└── question_metadata.json # Standardized VBVR task metadata
File specifications:
- Images: 1024×1024 PNG format
- Video: MP4 format, 16 fps, H.264 + yuv420p
- Metadata: VBVR canonical schema with
task_id,vbvr_task_code,media,parameters
fluid-dynamics communicating-vessels pascal-principle equilibrium continuous-physics damped-oscillation multi-step-reasoning
Part of the 36-Task Long-Horizon Multi-Step Reasoning Benchmark.