This document records the GeoFormerX-G8-D0-S0 recipe used by the final
2026-08-14 manuscript revision. The executable source of truth is
geoformerx_recipe.py, with the same values recorded
in configs/GeoFormerX_G8_D0_S0.yaml.
| Subset | Images | Permitted use |
|---|---|---|
train | 7,000 | Architecture screening and model fitting |
source_val | 1,000 | Architecture and checkpoint selection |
adaptation_pool | 1,000 | Reserved; not used in the reported study |
test | 1,000 | Final fixed-checkpoint comparison only |
The original 2,000-image validation split is divided with seed 2026 into the
disjoint source_val and adaptation_pool subsets. An earlier manuscript had
already reported results on an official test split, so the revised evaluation
is not described as historically unseen or fully blind.
| Item | Canonical setting |
|---|---|
| Optimizer | AdamW; weight decay 0.01 |
| Learning rates | New modules 3e-4; SAM mask decoder 7.5e-5 |
| Schedule | 1 warm-up + 32 hold + cosine decay; 50 epochs |
| Minimum learning rates | New modules 1e-5; decoder 2.5e-6 |
| Batch | 28 tiles/step; accumulation 1 |
| Precision | FP32; no AMP |
| Gradient control | Global norm clipping at 1.0 |
| EMA | Decay 0.995 from epoch 0 |
| Selection | Highest source-validation foreground macro Dice; earliest exact tie |
Training uses replacement weighted sampling, rare-presence and small-crack boosts, and a class-aware centered-crop probability of 0.65. No stochastic flip, rotation, or color-jitter augmentation is applied. Tile-coordinate jitter is a crop-location control and is not an image reflection or photometric augmentation.
The model predicts seven foreground logits. A deterministic zero-valued background channel is prepended before the eight-class loss is evaluated.
| Term | Canonical definition |
|---|---|
| Eight-class CE | Weight 1.0; batch-wise inverse-frequency weights clamped to 0.2-10.0; background scale 0.55; OHEM fraction 0.0625 |
| Foreground soft Dice | Weight 1.0; present-only; class weights 1:1.8, 2:1.5, 3:1.0, 4:1.1, 5:1.2, 6:1.3, 7:0.8 |
| Crack-sensitive | Focal-Tversky 0.12; boundary Dice 0.06; clDice 0.012 |
| Other rare classes | Focal-Tversky: Pothole 0.06, Patch 0.03, Road Marking 0.03, Expansion Joint 0.04; boundary Dice 0.02 each |
| Line-group CE | Three-class CE among Crack (1), Road Marking (5), and Expansion Joint (6), restricted to pixels with one of those labels; weight 0.10 |
| Surface-group CE | Two-class CE between Pothole (2) and Patch (4), restricted to pixels with one of those labels; weight 0.05 |
For a group with ordered class IDs (C=(c_0,\ldots,c_{m-1})), the implementation selects the matching channels directly from the eight-class semantic logits and remaps ground-truth class (c_j) to local target (j). It computes ordinary unweighted cross-entropy only on subset-valid pixels:
[ \mathcal{L}{\mathrm{group}} = \frac{1}{|\Omega_C|}\sum{x\in\Omega_C} -\log\frac{\exp z_{c_{j(x)}}(x)}{\sum_{c\in C}\exp z_c(x)}. ]
Background, out-of-subset classes, and ignore_index=255 do not contribute.
There is no independent group head, probability aggregation, OHEM, dynamic
class weighting, or background scaling in either group term. If a batch has no
subset-valid pixel, the implementation returns a differentiable zero.
The exact code is in
grouped_subset_ce_loss and the two terms are
added directly to the total loss with --line_group_ce_lambda 0.10 and
--surface_group_ce_lambda 0.05.
| Seed | Best epoch | Source-val FG mDice | Test FG mDice |
|---|---|---|---|
| 2026 | 48 | 0.7565 | 0.7693 |
| 2027 | 25 | 0.7547 | 0.7599 |
| 2028 | 26 | 0.7562 | 0.7605 |
| Mean +/- SD | - | 0.7558 +/- 0.0010 | 0.7633 +/- 0.0053 |
Seed 2028 is the prespecified primary paper model; no seed was selected from test performance.