> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lancedb.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Stable World Model

> Use Stable World Model with LanceDB-backed datasets for reproducible world model research, fast data loading, and compact storage.

export const PyFrameworksStableWorldmodelLoadLance = "dataset = swm.data.load_dataset(\"data/pusht_demo.lance\", num_steps=16)\n\nbatch = dataset[0]\nprint(batch.keys())\n";

export const PyFrameworksStableWorldmodelEvaluate = "from stable_worldmodel.policy import PlanConfig, WorldModelPolicy\nfrom stable_worldmodel.solver import CEMSolver\n\nsolver = CEMSolver(model=world_model, num_samples=300)\npolicy = WorldModelPolicy(solver=solver, config=PlanConfig(horizon=10))\n\nworld.set_policy(policy)\nresults = world.evaluate(episodes=50)\nprint(f\"Success Rate: {results['success_rate']:.1f}%\")\n";

export const PyFrameworksStableWorldmodelConvert = "swm.data.convert(\n    \"data/pusht_demo.lance\",\n    \"data/pusht_video\",\n    dest_format=\"video\",\n    fps=30,\n)\n";

export const PyFrameworksStableWorldmodelCollectLance = "import stable_worldmodel as swm\n\nworld = swm.World(\"swm/PushT-v1\", num_envs=8)\nworld.set_policy(your_expert_policy)\nworld.collect(\"data/pusht_demo.lance\", episodes=100, seed=0)\n";

[Stable World Model](https://github.com/galilai-group/stable-worldmodel) is a research platform for collecting data, training world models, and evaluating policies with model-predictive control across standardized environments.

The LanceDB integration is built into Stable World Model's data format registry. Lance is the default backend for collected datasets, so a path ending in `.lance` gives you an append-friendly LanceDB table with episode-contiguous rows and fast indexed reads.

Random access speed is the bottleneck for world model training, since the loop repeatedly samples temporal windows from high-dimensional observations, actions, and rewards. The faster those windows arrive, the more GPU time goes into training rather than waiting on the data loader.

## Install

```bash theme={"theme":{"light":"vitesse-light","dark":"catppuccin-mocha"}}
pip install stable-worldmodel
```

Datasets and checkpoints are stored under `$STABLEWM_HOME`, which defaults to `~/.stable_worldmodel/`.

## Collect data into Lance

Stable World Model uses Lance by default when you collect to a `.lance` path.
Replace `your_expert_policy` with the expert or scripted policy you use to collect demonstrations.

<CodeBlock filename="Python" language="Python" icon="python">
  {PyFrameworksStableWorldmodelCollectLance}
</CodeBlock>

Every writer accepts a `mode` argument such as `append`, `overwrite`, or `error`. The default is append, so re-running collection extends the existing dataset.

## Load a Lance dataset for training

The dataset loader autodetects the Lance format from the path.

<CodeBlock filename="Python" language="Python" icon="python">
  {PyFrameworksStableWorldmodelLoadLance}
</CodeBlock>

Your model code stays focused on the world model objective while LanceDB handles the storage layout and read path.

## Evaluate with model-predictive control

After training a world model on the Lance-backed dataset, Stable World Model can evaluate it with planning solvers such as CEM.
Replace `world_model` with the trained model object from your training loop.

<CodeBlock filename="Python" language="Python" icon="python">
  {PyFrameworksStableWorldmodelEvaluate}
</CodeBlock>

## Convert between formats

Stable World Model can convert between registered dataset formats. A common workflow is to collect in Lance for fast training reads, then export to the video layout for compact inspection artifacts.

<CodeBlock filename="Python" language="Python" icon="python">
  {PyFrameworksStableWorldmodelConvert}
</CodeBlock>

## Throughput

The Stable World Model README reports the following PushT benchmark results from `scripts/benchmark/compare_h5_lance.py`:

| Format  | Source | Cache    | samples/s | ms/step |
| :------ | :----- | :------- | --------: | ------: |
| HDF5    | local  | no-cache |   1,416.1 |    45.2 |
| HDF5    | local  | cached   |   1,474.0 |    43.4 |
| LanceDB | local  | no-cache |   4,814.8 |    13.3 |
| LanceDB | local  | cached   |   4,431.3 |    14.4 |
| Video   | local  | -        |   1,330.6 |    48.1 |
| LanceDB | s3     | no-cache |   3,183.7 |    20.1 |
| LanceDB | s3     | cached   |   3,253.2 |    19.7 |
| HDF5    | s3     | no-cache |       9.1 | 7,032.5 |
| HDF5    | s3     | cached   |     756.5 |    84.6 |

In that benchmark, local LanceDB reached about **3.4x** the no-cache throughput of local HDF5, while S3-backed LanceDB reached about **350x** the no-cache throughput of S3-backed HDF5. Even with cache enabled, S3-backed LanceDB was about **4.3x** faster than S3-backed HDF5.

These numbers come from the Stable World Model project's own benchmark setup, so they're best read as a reproducible directional baseline that may shift across environments, models, and storage configurations.

## Storage

The same README reports these local storage sizes for the benchmark dataset:

| Format  | Local size |
| :------ | ---------: |
| HDF5    |   43.12 GB |
| LanceDB |   13.31 GB |
| Video   |  496.29 MB |

LanceDB used about **69% less local storage than HDF5** in the reported benchmark, while preserving a table interface built for fast training reads and append-heavy collection.

## More resources

<CardGroup cols={2}>
  <Card title="Stable World Model README" href="https://github.com/galilai-group/stable-worldmodel/blob/main/README.md">
    Installation, quick start, supported formats, benchmarks, environments, solvers, and citation.
  </Card>

  <Card title="Stable World Model docs" href="https://galilai-group.github.io/stable-worldmodel/">
    Full upstream documentation with tutorials, API references, and guides.
  </Card>
</CardGroup>