v1

README.md

@@ -9,10 +9,25 @@ tags:
 
 # TTP-D solver weights
 
-Trained checkpoints for the Travelling Thief Problem with Drone (TTP-D) study.
-Benchmark instances and result tables live in the companion dataset repo
-[`Murjani/ttpd-benchmarks`](https://huggingface.co/datasets/Murjani/ttpd-benchmarks); the code is at
-https://github.com/Kcbir/ttpd.
+Trained policy checkpoints for the study *Fly, Pack, Drive: the Travelling Thief
+Problem with Drone*.
+
+A capacitated truck and a single-package drone operate from a common depot on a
+collection route. The truck's velocity decreases affinely with its accumulated
+load, so an early pickup penalises every subsequent arc. The drone launches from
+a node at which the truck is present, retrieves one item at an outlying
+customer, and rejoins the truck at a later rendezvous node; whichever vehicle
+arrives first waits, while the rental clock continues to run. The objective is
+to maximise collected profit net of a rental cost proportional to the makespan.
+
+These checkpoints are the learned construction policies: an encoder–decoder
+model that embeds the instance once and emits a composite action at each node
+the truck reaches, trained offline with Proximal Policy Optimisation under a
+POMO group baseline.
+
+Code: <https://github.com/corbit-lab/ttpd>. Benchmark instances, result tables,
+and behaviour-cloning datasets are in the companion dataset repository
+[`Murjani/ttpd-benchmarks`](https://huggingface.co/datasets/Murjani/ttpd-benchmarks).
 
 ## Layout
 
@@ -20,37 +35,65 @@ https://github.com/Kcbir/ttpd.
 <variant>/<model>/<family>/n<N>/best.pt
 ```
 
-- **variant** — `a280` (fixed drone endurance) or `ttd300` (endurance-conditioned)
-- **model** — `gat` (attention encoder), `mlp` (the encoder ablation), `lisa`
-  (behaviour cloning)
-- **family** — what the policy was trained on:
+**Variant** is `a280` (fixed drone endurance) or `ttd300` (endurance-conditioned).
+**Model** is `gat` (attention encoder), `mlp` (the encoder ablation), or `lisa`
+(behaviour cloning). **Family** denotes the distribution the policy was trained
+on, which determines its applicability:
 
-| family | trained on | use it for |
+| Family | Training distribution | Intended use |
 |---|---|---|
-| `benchmark-tuned/` | the five benchmark instances of that size | the headline results |
-| `sampled/` | randomly sampled a280 subsets | generalisation; warm start for the above |
-| `specialists/` | early small-n runs | the n<=20 rows using a dedicated small model |
+| `benchmark-tuned/` | The five benchmark instances of that size | The reported headline results |
+| `sampled/` | Randomly sampled a280 subsets | Generalisation; warm start for the above |
+| `specialists/` | Early small-N runs | The N ≤ 20 rows, using dedicated small models |
+
+The `benchmark-tuned` policies warm-start from `sampled/n20` of the same model
+family, as training from scratch does not converge within the budget at the
+larger sizes. Within a run, `best.pt` is the deliverable, selected by held-out
+beam evaluation; `last.pt` supports resumption; and `best_milp.pt` is selected
+by MILP gap rather than evaluation return.
 
-LISA weights live at `<variant>/lisa/bc/n<N>.pt`, with
-`a280/lisa/bc-initial/` and `a280/lisa/gat-n50/` kept for provenance.
+Behaviour-cloned policies are stored at
+`<variant>/lisa/behaviour_cloning/n<N>.pt`, with
+`a280/lisa/behaviour_cloning_initial/` and `a280/lisa/gat-n50/` retained for
+provenance.
 
-`best.pt` is the deliverable (best held-out beam evaluation); `last.pt` is a
-resume artifact; `best_milp.pt` is selected by MILP gap instead of eval return.
+## Deliverable checkpoint per model and size
+
+| Model and size | Checkpoint |
+|---|---|
+| a280 GAT, N = 5, 10 | `a280/gat/specialists/n5.pt`, `n10.pt` |
+| a280 GAT, N = 15, 20 | `a280/gat/sampled/n<N>/best.pt` |
+| a280 GAT, N = 30–100 | `a280/gat/benchmark-tuned/n<N>/best.pt` |
+| a280 MLP, N = 20 | `a280/mlp/sampled/n20/best.pt` |
+| a280 MLP, remaining sizes | `a280/mlp/benchmark-tuned/n<N>/best.pt` |
+| ttd300 GAT | `ttd300/gat/benchmark-tuned/n<N>/best.pt` |
+| LISA | `<variant>/lisa/behaviour_cloning/n<N>.pt` |
+
+The `benchmark-tuned` family also carries the smaller sizes so that a
+directory-based checkpoint argument resolves uniformly.
 
 ## Loading
 
-Checkpoints are `torch.save` payloads with a `"policy"` state-dict key:
+Checkpoints are `torch.save` payloads keyed under `"policy"`:
 
 ```python
 import torch
 from huggingface_hub import hf_hub_download
 
-path = hf_hub_download("Murjani/ttpd-weights", "a280/gat/bench-tuned/n30/best.pt")
+path = hf_hub_download("Murjani/ttpd-weights", "a280/gat/benchmark-tuned/n30/best.pt")
 payload = torch.load(path, map_location="cpu", weights_only=False)
 policy.load_state_dict(payload["policy"])
 ```
 
-The repo code resolves these automatically -- see `ttpd_hub.ensure_local`.
+The repository code resolves these paths automatically through
+`ttpd.hub.ensure_local`, which returns an existing local file unchanged and
+downloads otherwise, so a machine that already holds the tree performs no
+network access.
+
+`manifest.json` records, for every file, the path from which it was published
+together with its SHA-256 digest.
+
+## Citation
 
-`manifest.json` records, for every file, the path it was published from and its
-sha256.
+Please cite the accompanying paper. Reported results, including the comparison
+against the exact solver and the metaheuristics, are given there.