FlowMo-WM: A World Model with Object Momentum and Hidden Ambient Drift

Code, simulation inputs, trained checkpoints, numerical results and figure sources for FlowMo-WM. The original preprint and the revised manuscript describe a predictor with a recent-history state, sparse longer-history context and zero-context residual dynamics. This repository contains the original FlowMo study and its completed eight-seed follow-up controls.

The ICRA 2027 submission draft was frozen on 2026-09-13 after clarifying velocity-probe terminology, task-specific success/stopping rules and planning initialization, and adding direct temporal/memory related work. These manuscript and documentation changes preserve all recorded experiments, checkpoints, tables and quantitative figures. The source and reviewed eight-page PDF are in paper/; the target definitions are in METRICS.md.

The matched H60 comparison supports lower error than Recent-8 and error close to Full-32 with 16 instead of 32 image encodings. Image-encoding count is not a measured end-to-end latency improvement. The LeWorldModel-, RSSM- and TD-MPC2-style comparisons are adaptations to the common supervised pose-prediction interface, not reproductions of complete agents.

Rebuild the paper materials

Download this repository with the Hugging Face CLI or Git LFS. Install the analysis dependencies and run:

python -m pip install -r requirements.txt
sh run.sh verify
sh run.sh figures --output outputs

The command recomputes both tables and the statistics underlying the four data-derived figure assets from the retained original records. It checks all 100 plotted eight-seed estimates, including confidence intervals, and counts initial planning successes directly from 32,000 individual inferred-context episodes. It does not train a model. Outputs go to a separate directory; supplied records remain unchanged.

With Tectonic or latexmk installed, one command also compiles the manuscript:

sh run.sh paper --output outputs --tex-engine /path/to/tectonic

The resulting manuscript is outputs/paper/main.pdf. The reviewed supplied PDF is in paper/. Figure 1 is editable PowerPoint artwork; Figure 2 is supplied environment artwork. Their reviewed exports are retained. Quantitative and rollout panels are regenerated by code. Panel fonts use Arial when available, then Liberation Sans or DejaVu Sans; a substitution can change image pixels while preserving the reported data and selection.

Inputs and provenance

data/manifest.json distinguishes three archived NPZs, two labeled NPZs restored exactly after neutral metadata normalization, and thirteen reconstructed simulation inputs generated from the recorded protocol. Every file has a release checksum and a provenance status. DATASETS.md describes their scope and validation.

The reconstructed inputs preserve the documented seeds, shapes, metadata, family counts and paired-condition design. Their original historical containers were not recovered, so equality to the original trajectories is not asserted. Archived evaluation records remain the source of published statistics; those records have not been replaced with evaluations on reconstructed inputs. The supplied original train/test and switching data are unchanged.

All simulation inputs are numerical states and commands. Clean 160-by-160 RGB observations are rendered online. Flow arrows, trajectories and goal overlays in the explanatory figures are not model inputs.

Evaluate the supplied checkpoints

The recorded Linux rebuttal runtime uses Python 3.12, PyTorch 2.12.0 with CUDA 13.0, NumPy 2.4.6, Pillow 12.2.0 and PyYAML 6.0.3. requirements-recorded-linux.txt records these components and the separately validated plotting dependency. A CUDA installation is required for the recorded GPU path.

python -m pip install -r requirements-recorded-linux.txt
sh run.sh verify --models
sh run.sh replay --suites core --output runs/core
sh run.sh replay --suites family switch interventions --output runs/additional
sh run.sh replay --suites magnitude frequency scaling --output runs/stress

Each receipt records the actual inputs, source version, runtime, seed coverage and differences from the archived measurements. --dry-run prints the selected jobs without running models. --seeds 1 selects one formal seed; --limit-jobs produces a receipt explicitly marked partial.

Numerical comparisons are diagnostic by default. The optional --strict-compare --rtol ... --atol ... makes a caller-selected tolerance an exit criterion. A tolerance is not an acceptance test for a scientific claim. In particular, reevaluations using reconstructed inputs should be read as new measurements under the recorded protocol. Cross-platform bitwise equality is not promised.

Train and run control experiments

The final-checkpoint rule and optimizer budgets are retained. No checkpoint selection uses evaluation results. Training writes to its own directory.

sh run.sh train --groups all --output runs/training --dry-run
sh run.sh train --groups core --output runs/training
sh run.sh replay --suites core --training-output runs/training --output runs/new_predictions
sh run.sh control --suite formal --training-output runs/training --output runs/new_control

all specifies 108 endpoints: 4 initial models, 40 core controls, 40 held-out-family controls and 24 smaller-training-set endpoints. Core seeds are 1-8. The 2,400-episode scaling point reuses the corresponding core model. Candidate pilots are not included in paper statistics.

For the supplied checkpoints, omit --training-output. The formal control protocol contains four methods, six twin-boat conditions, eight seeds and thirty episodes per condition, totaling 5,760 episodes. It retains the original CEM budget, per-condition environment seeds and per-episode planner reseeding.

Initial protocol

The original published source snapshot is preserved under protocols/initial/src/. The initial training, prediction and planning commands select this snapshot automatically:

sh run.sh train --groups initial --output runs/initial_training
sh run.sh replay --suites initial --output runs/initial_prediction
sh run.sh control --suite initial --output runs/initial_control

This matters for the initial batch-roll shuffled-context intervention and its planner random-number policy. The later rebuttal uses a cross-flow-instance context donor and explicit planner reseeding. These are distinct protocols, not interchangeable implementations of the same saved result. The later September deterministic reevaluation is retained as an earlier verification record and does not replace the August statistics used by this manuscript.

Generate new simulation inputs

sh run.sh generate-data --output runs/generated_inputs --dry-run
sh run.sh generate-data --output runs/generated_inputs
sh run.sh replay --suites core --data-root runs/generated_inputs/data --output runs/generated_data_evaluation

The generator invokes the recorded commands and never overwrites supplied input files. A generated file receives a new provenance record; its container checksum is not substituted into the historical experiment manifest.

Contents

Location	Material
data/	Original or explicitly reconstructed inputs and their manifest
experiments/	Rebuttal source, 108 final checkpoints, original numerical records and eight figure-used rollout GIFs
protocols/	Initial source snapshot, frozen data commands and protocol notes
paper/	Reviewed manuscript, references, tables and six figures
assets/	Editable PowerPoint architecture source
provenance/	Source mapping and verification summaries
MANIFEST.json	Checksums of the files in this release

Spatial errors are reported as 100 * error / workspace_width, with workspace width 10 simulator coordinates. Relative improvements use 100 * (reference - candidate) / reference. These denominators differ. Table I's energy and step counts are conditioned on successful episodes; final distance and success rate use all episodes. Table II reports mean and sample standard deviation across seeds 1-8. H60 is the primary prediction horizon and H120 is extrapolative. Additional definitions and panel mappings are in METRICS.md.

Redundant GIFs, intermediate checkpoints, caches, old manuscript drafts and development logs are omitted from this release tree. The earlier Hub commit remains available in history. No new license grant is added by this update.