TL;DR. For a 2–3 layer baroclinic QG double-gyre at 128²–256² resolution on a ~5000 km basin, the literature spans 2 years (demo-quality) to 40+ years (low-frequency variability studies). There is no single canonical number. somax ships 3 years as the default, with a documented ladder for production (10 yr) and publication-grade (40 yr) work.
The “spinup duration” is the length of integration that is discarded before analysis begins, to let transients from the initial conditions die out. Choosing it wrong means either:
The right choice depends on what you’re trying to measure. somax provides a default that’s defensible for general-purpose use and a ladder for users with stricter scientific requirements.
For a baroclinic QG double-gyre with basin width $L \sim 5000$ km, mid-latitude $f_0 \approx 10^{-4}~\text{s}^{-1}$, and first baroclinic deformation radius $R_d \sim 30$ km, the relevant adjustment timescales are:
| Process | Timescale | Order of magnitude |
|---|---|---|
| Inertial period $2\pi/f_0$ | hours | hours |
| Barotropic Rossby wave crossing $L/c_{0}$ | days–weeks | days |
| First baroclinic Rossby wave crossing $\tau_R = L/c_1$ | months–years | ~3 yr for $c_1 \approx 2~\text{m/s}$ |
| Eddy-mean flow equilibration | years | ~5–10 yr |
| Decadal intrinsic variability modes | decades | 5–20 yr |
The first-baroclinic Rossby wave crossing time $\tau_R$ is the physical floor for any meaningful spinup. Anything less than $2$–$3 \tau_R$ leaves the basin in a state where the slowest large-scale waves haven’t even propagated across it once.
A typical baroclinic QG double-gyre, started from rest with a fixed wind forcing, passes through these phases:
Concrete spinup durations from the canonical references and recent open-source implementations:
| Reference | Layers / grid / basin | Spinup discarded | Total run | Notes |
|---|---|---|---|---|
| Holland (1978) | 2L, ~20 km, 1000 km | informal, ~last few yr | multi-year | Original wind-driven 2-layer gyre |
| Berloff & McWilliams (1999) | 1.5–2L, eddy-permitting | ~10 yr | 40–100 yr | Low-frequency variability |
| Hogg, Dewar et al. (2003) | 3L, ~10 km (Q-GCM) | 10–20 yr | 50–100+ yr | Q-GCM coupled model |
| Hogg et al. (2005) | 3L, ~10 km | 10–20 yr | 50+ yr | Decadal mode quantization |
| Berloff, Hogg & Dewar (2007) | 3L, ~7.5 km, 3840 km | 40 yr | 200 yr | “Turbulent oscillator” |
| Karabasov, Berloff & Goloviznin (2009) | 3L, 7.5–3.75 km | ~10 yr | multi-decadal | CABARET benchmark |
| Thiry et al. (2024 JAMES) | 3L, 256², 5120 km | 40 yr | 60 yr | 20 yr analysis |
| MQGeometry-1.0 (Thiry et al. 2024 GMD) | 3L, 256², 5120 km | 10 yr | 50 yr | Closest direct analog |
| louity/qgsw-pytorch | 3L, 256², 5120 km | 2 yr | 10 yr | Other direct analog |
The two analog repos that match somax’s target configuration most closely (MQGeometry and qgsw-pytorch, both 3-layer, 256², 5120 km basin) bracket the practical range: 2 years on the short end, 10 years on the long end. The Berloff/Hogg variability papers go to 40 years because they’re after intrinsic decadal modes that no shorter run can resolve.
The QG community typically monitors convergence via:
There is no universal quantitative threshold. “5% running-mean drift per year” is a common informal criterion in QG papers but is rarely stated explicitly.
somax ships configs at three tiers:
| Tier | spinup_duration_years |
Use case | Wallclock at 128² | Justification |
|---|---|---|---|---|
| Default (CI / demo) | 3 | Smoke test, “show me a turbulent jet”, reference pipeline | minutes | Just clears the baroclinic Rossby adjustment time $\tau_R \approx 3$ yr; produces a post-WBC-formation state with the first generation of eddies. |
| Production | 10 | “Looks scientifically reasonable”; matches MQGeometry’s n_steps_save = 10 yr; used by qgsw-pytorch’s higher-end recommendation. |
tens of minutes | Approaches statistical equilibrium of mean flow + EKE. |
| Publication | 40 | Required for decadal variability statistics (Berloff/Hogg conventions, Thiry et al. 2024). | hours | Captures intrinsic 5–20 yr modes. |
The default of 3 years is chosen because:
For any work beyond demonstration, users should override to 10 or 40 years. The override mechanism is documented in the simulation pipeline guide.
There is no single canonical number. The 2–40 year spread in the literature reflects two genuinely different scientific goals:
For a general-purpose open-source reference config, 3 years is the shortest defensible minimum, 10 years is the community mode for routine work, and 40 years is publication-grade for variability studies.
If you are using somax for research that depends on the absolute level of spinup, you should run a convergence study at your specific resolution and parameter set, not rely on the default.