TartanIMU platform-expert ensemble
This repository contains a self-contained, inference-only PyTorch ensemble for TartanIMU velocity estimation. It combines four base models with four experts for each platform (20 checkpoints total), a saved platform router, and the Test feature cache used for the historical submission. The historical submission has 30,644 rows and a user-reported Public score of 0.26571.
This is a custom PyTorch ensemble, not a Transformers checkpoint. Use the
bundled infer.py entry point; the Hugging Face inference widget cannot run it
automatically.
Repository layout
| Path | Contents |
|---|---|
weights/ |
4 base checkpoints, 16 platform-expert checkpoints, and router.joblib |
data/test.pt |
Whitelisted Test features and window mapping; no labels or platform truth |
runtime/ |
Minimal model and windowed inference implementation |
infer.py |
Verification, smoke test, and full reproduction CLI |
reference/ |
Sample submission and historical base prediction |
provenance/ |
Training configuration, audit records, routing analysis, and source excerpts |
METHOD.md |
Architecture, training recipe, routing, blending, and evaluation scope |
asset_manifest.json / SHA256SUMS |
Asset and package integrity records |
The four platform IDs are 0=car, 1=dog, 2=drone, and 3=human. The
router predicts a platform from IMU summary features. When its confidence
passes the platform threshold, the four matching experts are averaged and
blended with the four base predictions using B + 0.5 * (E - B); otherwise the
base ensemble is used.
Quick start
Python 3.10+ is recommended. Install the pinned runtime dependencies, then verify every bundled asset before loading a checkpoint:
python -m pip install -r requirements.txt
sha256sum -c SHA256SUMS
python infer.py --verify-only
python infer.py --smoke --device cpu
To reproduce a submission, use a GPU when available. Outputs are never overwritten:
python infer.py --device cuda:0 --output outputs/reproduced.csv
Use --frozen-base to preserve the historical base CSV text while recomputing
only the routed experts. Each output gets a sidecar .audit.json containing
the device, output hash, and numerical difference from the bundled historical
submission.
Upload to Hugging Face Hub
Create an empty model repository, install huggingface_hub, log in with
hf auth login, and upload this directory as-is:
hf upload your-user/tartanimu-platform-experts . --repo-type model
The .gitattributes file sends checkpoint and router binaries through Git LFS.
No conversion to transformers format is needed because this is a custom
PyTorch ensemble.
Evaluation and provenance
The reported Public score is a historical user report, not a score recomputed
by this repository. The fixed fold1 result for the separately trained experts
was Score 0.3487334649, Macro AVE 0.2695168333, and Macro ATE20
1.0042230308; its scope is
holdout_evaluation_with_unlabeled_test_adaptation. Final checkpoints were
trained on the official Train+Val set and must not be presented as unseen-data
generalization results.
The training process used unlabeled Test IMU distribution matching. It did
not read Test truth, Test platform labels, or fit normalization on Test, and it
did not perform supervised Test training. These details are retained in
provenance/ for auditability.
The package has been verified for strict loading of all 20 checkpoints, a real
feature CPU smoke forward, full router replay, byte-identical historical
prediction replay, and one complete CPU Test re-inference producing 30,644
rows. The CPU output is not byte-identical to the historical CUDA/BF16 output;
its maximum absolute difference was 0.009473085. A full GPU re-inference was
not completed on the source machine because its NVIDIA driver was unavailable;
outputs can vary with PyTorch, CUDA, BF16, and hardware versions.
License
Repository code and packaging files follow Apache-2.0; see LICENSE. Review
the provenance and any upstream dataset or checkpoint terms before
redistributing bundled artifacts.
This repository intentionally contains only the code, inference assets, and English upload documentation needed to run the model.