Upload IKTM model card and MIT-licensed checkpoint

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Max Amiri
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -1,3 +1,121 @@
 ---
+library_name: pytorch
 license: mit
+tags:
+- trajectory-generation
+- time-series
+- transformer
+- industrial-mobility
 ---
+
+# IKTM
+
+The Industrial Kinematic Trajectory Model (IKTM) generates autoregressive
+kinematic trajectories for industrial vehicles. It models speed and change in
+heading without absolute coordinates, so the model is location-invariant.
+
+This is a research release. It is not a `transformers` model and cannot be
+loaded with `transformers.from_pretrained`.
+
+## Files
+
+| File | Description |
+|---|---|
+| `iktm_model.pt` | Production probabilistic, duration-conditioned causal Transformer checkpoint. This is the best-validation checkpoint, not the epoch-30 final state. |
+| `scaling_stats.npy` | Speed-normalisation statistics from the Site A training split. |
+
+The checkpoint is a native PyTorch checkpoint rather than a Hugging Face
+Transformers model. It contains the model state and the configuration needed
+by the IKTM implementation, including the model dimensions, mixture sizes,
+duration conditioning flag, and speed mean and standard deviation.
+
+## Model
+
+- 30 training epochs; the retained checkpoint is the best-validation state
+  (epoch 24).
+- Decoder-only causal Transformer.
+- Probabilistic output: a Gaussian mixture for speed and a von Mises mixture
+  for change in heading, together with a stop probability.
+- Inputs: normalised speed, sine and cosine of heading change, a beginning-of-
+  sequence flag, and a remaining-duration feature.
+- Three Gaussian speed-mixture components and five von Mises heading-mixture
+  components.
+- 60-step maximum context and 128-dimensional hidden representation.
+
+## Intended use
+
+IKTM is intended for research on synthetic industrial-vehicle trajectory
+generation, kinematic simulation, and evaluation of cross-site transfer. It
+generates speed and heading-change sequences, not absolute positions, routes,
+or maps.
+
+## Training data and procedure
+
+The model was trained on anonymised Site A industrial-vehicle telematics. The
+data was cleaned and resampled to one-second kinematic time series. Training,
+validation, and test devices used a fixed 70/15/15 device-level split with
+seed 42; raw trajectories and site identifiers are confidential and are not
+included here.
+
+Training used AdamW with learning rate `1e-3`, weight decay `1e-4`, batch size
+128, and a cosine learning-rate schedule. The loss combines probabilistic
+speed and heading likelihoods, stop binary cross-entropy, and a duration-prior
+likelihood. The checkpoint contains the learned duration prior.
+
+## Evaluation
+
+The following values use the held-out test protocol and temperature `T=0.2`.
+Teacher-forced metrics are reported for the production checkpoint; rollout
+metrics use 100 samples from the beginning-of-sequence token with seed 42.
+
+| Site | Split | Speed RMSE, teacher-forced (m/s) | Heading RMSE, teacher-forced (degrees) | Turn-rate JSD, rollout (bits) |
+|---|---|---:|---:|---:|
+| Site A | ID test | 0.1178 | 21.3432 | 0.0390 |
+| Site B | zero-shot OOD | 0.1281 | 19.6080 | 0.0569 |
+| Site C | zero-shot OOD | 0.1413 | 20.7127 | 0.0310 |
+| Site D | zero-shot OOD | 0.1509 | 23.4554 | 0.0329 |
+
+All 100 Site A rollouts stopped naturally and matched their sampled target
+duration, with length error `+0.0 +/- 0.0` seconds. The rollout metrics are
+distributional diagnostics, not guarantees for an individual generated
+trajectory.
+
+## Limitations and responsible use
+
+- The model was trained on one industrial site and evaluated zero-shot on
+  three other sites. It may not represent other fleets, operating policies,
+  vehicle types, or environments.
+- It has no absolute-coordinate, road-network, obstacle, or route-intent
+  information. Generated sequences should not be interpreted as safe paths.
+- Do not use this checkpoint for real-time vehicle control, collision
+  avoidance, safety decisions, or operational planning without independent
+  validation and appropriate safety systems.
+- The training data contains industrial mobility patterns. The release omits
+  raw telematics and site identifiers to preserve confidentiality.
+
+## Loading
+
+The checkpoint requires the IKTM model implementation in `scripts/models.py`.
+For the full evaluation and generation workflow, use the project repository's
+`scripts/evaluate_generator.py` and point it at this checkpoint after placing
+it at the expected model path.
+
+```python
+import torch
+
+checkpoint = torch.load(
+    "iktm_model.pt",
+    map_location="cpu",
+    weights_only=False,
+)
+
+print(checkpoint.keys())
+print(checkpoint["speed_mean"], checkpoint["speed_std"])
+```
+
+The model is intended for research use with the accompanying IKTM code and
+evaluation protocol.
+
+## License
+
+This model is released under the [MIT License](LICENSE).

iktm_model.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:c4f8bb5b3282994207b48ba415950d96e1acf2260a8446d78590e9550ac1f7d1
+size 9743306

scaling_stats.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:35f1dc77f1014004e45b418a84011432ed450dfd72ad58f317cd602361aa020f
+size 321