NatureV2-500: weights only; the code lives on PyPI

LICENSE

@@ -1,203 +0,0 @@
-Copyright 2018- The Hugging Face team. All rights reserved.
-
-                                 Apache License
-                           Version 2.0, January 2004
-                        http://www.apache.org/licenses/
-
-   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
-
-   1. Definitions.
-
-      "License" shall mean the terms and conditions for use, reproduction,
-      and distribution as defined by Sections 1 through 9 of this document.
-
-      "Licensor" shall mean the copyright owner or entity authorized by
-      the copyright owner that is granting the License.
-
-      "Legal Entity" shall mean the union of the acting entity and all
-      other entities that control, are controlled by, or are under common
-      control with that entity. For the purposes of this definition,
-      "control" means (i) the power, direct or indirect, to cause the
-      direction or management of such entity, whether by contract or
-      otherwise, or (ii) ownership of fifty percent (50%) or more of the
-      outstanding shares, or (iii) beneficial ownership of such entity.
-
-      "You" (or "Your") shall mean an individual or Legal Entity
-      exercising permissions granted by this License.
-
-      "Source" form shall mean the preferred form for making modifications,
-      including but not limited to software source code, documentation
-      source, and configuration files.
-
-      "Object" form shall mean any form resulting from mechanical
-      transformation or translation of a Source form, including but
-      not limited to compiled object code, generated documentation,
-      and conversions to other media types.
-
-      "Work" shall mean the work of authorship, whether in Source or
-      Object form, made available under the License, as indicated by a
-      copyright notice that is included in or attached to the work
-      (an example is provided in the Appendix below).
-
-      "Derivative Works" shall mean any work, whether in Source or Object
-      form, that is based on (or derived from) the Work and for which the
-      editorial revisions, annotations, elaborations, or other modifications
-      represent, as a whole, an original work of authorship. For the purposes
-      of this License, Derivative Works shall not include works that remain
-      separable from, or merely link (or bind by name) to the interfaces of,
-      the Work and Derivative Works thereof.
-
-      "Contribution" shall mean any work of authorship, including
-      the original version of the Work and any modifications or additions
-      to that Work or Derivative Works thereof, that is intentionally
-      submitted to Licensor for inclusion in the Work by the copyright owner
-      or by an individual or Legal Entity authorized to submit on behalf of
-      the copyright owner. For the purposes of this definition, "submitted"
-      means any form of electronic, verbal, or written communication sent
-      to the Licensor or its representatives, including but not limited to
-      communication on electronic mailing lists, source code control systems,
-      and issue tracking systems that are managed by, or on behalf of, the
-      Licensor for the purpose of discussing and improving the Work, but
-      excluding communication that is conspicuously marked or otherwise
-      designated in writing by the copyright owner as "Not a Contribution."
-
-      "Contributor" shall mean Licensor and any individual or Legal Entity
-      on behalf of whom a Contribution has been received by Licensor and
-      subsequently incorporated within the Work.
-
-   2. Grant of Copyright License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      copyright license to reproduce, prepare Derivative Works of,
-      publicly display, publicly perform, sublicense, and distribute the
-      Work and such Derivative Works in Source or Object form.
-
-   3. Grant of Patent License. Subject to the terms and conditions of
-      this License, each Contributor hereby grants to You a perpetual,
-      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
-      (except as stated in this section) patent license to make, have made,
-      use, offer to sell, sell, import, and otherwise transfer the Work,
-      where such license applies only to those patent claims licensable
-      by such Contributor that are necessarily infringed by their
-      Contribution(s) alone or by combination of their Contribution(s)
-      with the Work to which such Contribution(s) was submitted. If You
-      institute patent litigation against any entity (including a
-      cross-claim or counterclaim in a lawsuit) alleging that the Work
-      or a Contribution incorporated within the Work constitutes direct
-      or contributory patent infringement, then any patent licenses
-      granted to You under this License for that Work shall terminate
-      as of the date such litigation is filed.
-
-   4. Redistribution. You may reproduce and distribute copies of the
-      Work or Derivative Works thereof in any medium, with or without
-      modifications, and in Source or Object form, provided that You
-      meet the following conditions:
-
-      (a) You must give any other recipients of the Work or
-          Derivative Works a copy of this License; and
-
-      (b) You must cause any modified files to carry prominent notices
-          stating that You changed the files; and
-
-      (c) You must retain, in the Source form of any Derivative Works
-          that You distribute, all copyright, patent, trademark, and
-          attribution notices from the Source form of the Work,
-          excluding those notices that do not pertain to any part of
-          the Derivative Works; and
-
-      (d) If the Work includes a "NOTICE" text file as part of its
-          distribution, then any Derivative Works that You distribute must
-          include a readable copy of the attribution notices contained
-          within such NOTICE file, excluding those notices that do not
-          pertain to any part of the Derivative Works, in at least one
-          of the following places: within a NOTICE text file distributed
-          as part of the Derivative Works; within the Source form or
-          documentation, if provided along with the Derivative Works; or,
-          within a display generated by the Derivative Works, if and
-          wherever such third-party notices normally appear. The contents
-          of the NOTICE file are for informational purposes only and
-          do not modify the License. You may add Your own attribution
-          notices within Derivative Works that You distribute, alongside
-          or as an addendum to the NOTICE text from the Work, provided
-          that such additional attribution notices cannot be construed
-          as modifying the License.
-
-      You may add Your own copyright statement to Your modifications and
-      may provide additional or different license terms and conditions
-      for use, reproduction, or distribution of Your modifications, or
-      for any such Derivative Works as a whole, provided Your use,
-      reproduction, and distribution of the Work otherwise complies with
-      the conditions stated in this License.
-
-   5. Submission of Contributions. Unless You explicitly state otherwise,
-      any Contribution intentionally submitted for inclusion in the Work
-      by You to the Licensor shall be under the terms and conditions of
-      this License, without any additional terms or conditions.
-      Notwithstanding the above, nothing herein shall supersede or modify
-      the terms of any separate license agreement you may have executed
-      with Licensor regarding such Contributions.
-
-   6. Trademarks. This License does not grant permission to use the trade
-      names, trademarks, service marks, or product names of the Licensor,
-      except as required for reasonable and customary use in describing the
-      origin of the Work and reproducing the content of the NOTICE file.
-
-   7. Disclaimer of Warranty. Unless required by applicable law or
-      agreed to in writing, Licensor provides the Work (and each
-      Contributor provides its Contributions) on an "AS IS" BASIS,
-      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
-      implied, including, without limitation, any warranties or conditions
-      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
-      PARTICULAR PURPOSE. You are solely responsible for determining the
-      appropriateness of using or redistributing the Work and assume any
-      risks associated with Your exercise of permissions under this License.
-
-   8. Limitation of Liability. In no event and under no legal theory,
-      whether in tort (including negligence), contract, or otherwise,
-      unless required by applicable law (such as deliberate and grossly
-      negligent acts) or agreed to in writing, shall any Contributor be
-      liable to You for damages, including any direct, indirect, special,
-      incidental, or consequential damages of any character arising as a
-      result of this License or out of the use or inability to use the
-      Work (including but not limited to damages for loss of goodwill,
-      work stoppage, computer failure or malfunction, or any and all
-      other commercial damages or losses), even if such Contributor
-      has been advised of the possibility of such damages.
-
-   9. Accepting Warranty or Additional Liability. While redistributing
-      the Work or Derivative Works thereof, You may choose to offer,
-      and charge a fee for, acceptance of support, warranty, indemnity,
-      or other liability obligations and/or rights consistent with this
-      License. However, in accepting such obligations, You may act only
-      on Your own behalf and on Your sole responsibility, not on behalf
-      of any other Contributor, and only if You agree to indemnify,
-      defend, and hold each Contributor harmless for any liability
-      incurred by, or claims asserted against, such Contributor by reason
-      of your accepting any such warranty or additional liability.
-
-   END OF TERMS AND CONDITIONS
-
-   APPENDIX: How to apply the Apache License to your work.
-
-      To apply the Apache License to your work, attach the following
-      boilerplate notice, with the fields enclosed by brackets "[]"
-      replaced with your own identifying information. (Don't include
-      the brackets!)  The text should be enclosed in the appropriate
-      comment syntax for the file format. We also recommend that a
-      file or class name and description of purpose be included on the
-      same "printed page" as the copyright notice for easier
-      identification within third-party archives.
-
-   Copyright [yyyy] [name of copyright owner]
-
-   Licensed under the Apache License, Version 2.0 (the "License");
-   you may not use this file except in compliance with the License.
-   You may obtain a copy of the License at
-
-       http://www.apache.org/licenses/LICENSE-2.0
-
-   Unless required by applicable law or agreed to in writing, software
-   distributed under the License is distributed on an "AS IS" BASIS,
-   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-   See the License for the specific language governing permissions and
-   limitations under the License.

NOTICE

@@ -1,11 +0,0 @@
-naturev1
-Copyright 2026 Nathan
-
-Licensed under the Apache License, Version 2.0. See LICENSE.
-
-Builds on `ihelix` (Apache-2.0), which in turn carries kernels from `helix-lm`
-and ultimately from HuggingFace Transformers (Apache-2.0).
-
-Data sources referenced by this package are public: NOAA GOES ABI imagery on
-AWS Open Data, and NOAA HURDAT2 best-track archives. This package is not
-affiliated with or endorsed by NOAA, NESDIS or the National Hurricane Center.

README.md

@@ -5,44 +5,15 @@ tags:
 - weather
 - tropical-cyclone
 - hurricane
-- satellite
-- ihelix
 pipeline_tag: other
 ---
 
 # NatureV2-500
 
-The next model of the CorxLabs hurricane engine. It starts from the NatureV1-500 **stage-1 checkpoint**
-(`checkpoints/stage1/latest.pt`, with its `config.json`, `normalizer.json` and the storm banks, copied here from
-[CorxLabs/NatureV1-500](https://huggingface.co/CorxLabs/NatureV1-500)) and carries the complete `naturev1` 0.16 code base,
-so that the fine-tuning of the satellite encoder and the new features can start from one place.
+Base weights for the next CorxLabs model: the NatureV1-500 stage-1 checkpoint (`checkpoints/stage1/latest.pt`) with
+its `config.json`, `normalizer.json`, `training_record.json` and the storm banks, copied from
+[CorxLabs/NatureV1-500](https://huggingface.co/CorxLabs/NatureV1-500). NatureV2 is a new architecture built on this
+backbone: the satellite encoder enabled and new storm features added. The code is the `naturev1` package on PyPI
+(`pip install "naturev1[swarm,hub]"`); nothing else is kept here.
 
-## What is here
-
-* `checkpoints/stage1/latest.pt`, `config.json`, `normalizer.json`, `training_record.json`, `checkpoints/storm_bank_*.pt`
-  -- the base to fine-tune from (the global atmosphere at 1.5 degrees after stage 1; the storm banks for the storm heads).
-* `naturev1/`, `pyproject.toml`, `tests/` -- the 0.16 code base: the model and its training stages (`model.py`,
-  `train.py`, `sattrain.py`, `satstage.py`, the satellite readers `stormsat.py` / `satellite.py`), the hurricane physics
-  engine (`cyclone/`), the swarm, impacts, landfall, the live path and the NHC guidance layer (`swarm/`).
-  `pip install "naturev1[swarm,hub]"` installs the same code from PyPI (0.16.0).
-* `RESULTS_0.16.md` -- the complete record of the results and of what was built, with every held-out table.
-* `ROADMAP_0.16.md` -- the deficit matrix, what shipped and what was rejected. `NatureV1_model_card.md` -- the NatureV1
-  card (sections 4.12-4.17 carry the verification of every release). `naturev1_README.md` -- the package README.
-* `molab_swarm_cell.py` -- the operational cell (one marimo cell: the live path, the parishes, the cycle record;
-  `TRAIN_SATELLITE = True` runs the satellite stage on the GPU from `checkpoints/stage1`). `b300_naturev1.py`,
-  `molab_naturev1.py`, `colab_naturev1.py` -- the training cells of the earlier stages.
-
-## The plan
-
-1. **The satellite encoder.** Fine-tune the band-13 path (SatNet-Storm 2.0 and the global satellite retrieval of 0.12)
-   from the stage-1 weights on storm-centred GridSat / HURSAT / GOES imagery (`naturev1.satstage` stages it,
-   `naturev1.sattrain` trains it; the cell wires both).
-2. **New features.** The infrared structure diagnostics and their trend (`naturev1.swarm.infrared`), lightning, and the
-   ocean heat feed, as inputs to the storm heads and to the rapid-intensification probability -- the explosive cases
-   are still tail events to every mean forecast, and the satellite is where the next predictor is.
-3. **Verification before use.** Every new number is scored on the same held-out seasons (2018, 2020-2022) and the same
-   benchmark table (`benchmark_heldout_atlantic_2018_2020_2022.csv.gz` on the NatureV1-500 repository) before it
-   changes anything in the operational path.
-
-Research model, not an operational forecast. For decisions, follow your national meteorological service and the
-National Hurricane Center.
+Research model, not an operational forecast.

RESULTS_0.16.md

@@ -1,208 +0,0 @@
-# NatureV1 0.16 -- the results, and the record of what was built
-
-CorxLabs, Westmoreland, Jamaica. October 2026. This is the complete account of the hurricane engine as it stands at
-0.16.0: what the architecture is, how every number was earned, what was tried and rejected, what shipped, and where it
-is published. Every figure here comes from the held-out seasons unless it says otherwise; nothing was tuned on them.
-
-## 1. What the system is
-
-NatureV1 is a weather model with a hurricane engine around it. Three layers:
-
-1. **iHELIX**, the engine: attention over physical space on the sphere (conservative regrid, spherical convolution,
-   binning), the kernels the model is built from (`ihelix`, on PyPI).
-2. **NatureV1-500**, the model: the global atmosphere at 1.5 degrees with storm heads (track, intensity, rapid
-   intensification, eyewall, landfall), every output a distribution, trained in stages (stage 1 the atmosphere,
-   stage 2 the storm heads on the storm bank, stage 3 the satellite path: SatNet-Storm 2.0 and the global satellite
-   retrieval on GridSat/HURSAT/GOES band 13), published at `CorxLabs/NatureV1-500` with its checkpoints
-   (`checkpoints/stage1`, `stage2`, `rollout`, the storm banks), config and normaliser.
-3. **The hurricane physics engine** (`naturev1.cyclone`, `naturev1.swarm`; versions 0.13 to 0.16), which is what
-   this document is about. It is deterministic physics plus fitted tables, no network in the loop, and it is the part
-   verified against every archived reference:
-   * **Track.** A consensus of physics members (extrapolation, CLIPER rebuilt, beta-and-advection steering from the
-     analysis at several depths, an analog member, the forecast-flow member that follows the dynamical model's own
-     steering), simplex weights per lead; blended with the mean track of the live models (GFS, ECMWF IFS and AIFS,
-     GraphCast-GFS, the GEFS mean, each followed at native resolution); the previous cycle's error fed back; and
-     since 0.16 the NHC's operational aids blended in (section 4).
-   * **Cone and swarm.** A flow-dependent cone (Goerss-style regression of the blend's error on member spread, model
-     disagreement, speed, latitude, intensity) and a particle-filter swarm of up to a million worlds, each world
-     steered by one model's flow, filtered on every satellite, recon and radar centre fix, sized to the cone,
-     re-weighted by fixes that arrive after the analysis. It gives scenario probabilities (stall, loop, recurve,
-     steady), strike probabilities and the parish impacts.
-   * **Intensity.** SHIFOR, decay-SHIFOR, a SHIPS-style statistical-dynamical member, LGEM, a trend member and the
-     models' own deepening, in a simplex consensus with a rapid-intensification regime; a 17-feature logistic P(RI);
-     the RI path as a branch beside the mean; ocean heat content and 26 C isotherm depth from the World Ocean Atlas
-     under the storm; peak probabilities P(peak >= 64/96/113/137 kt), calibrated peak quantiles and E[peak | RI];
-     category probabilities per lead; since 0.16 the NHC intensity aids blended in.
-   * **Impacts.** A parametric asymmetric wind field sized to the observed 34-kt radius, land decay, gusts, arrival
-     times; rain from R-CLIPER reshaped against gauge-corrected radar with an orographic term, and since 0.16 the
-     GFS's own precipitation travelling with every world; painted onto every parish, province and district of the
-     Caribbean with terrain; the landfall report (when, where first, how strong, each parish's numbers, the
-     arrival-time window).
-   * **Operations.** One call from an NHC storm id (`naturev1.swarm.live.forecast_storm`), live or replayed as it was
-     known; every cycle saved as JSON and a parish CSV; the previous cycle found again automatically; GOES band-13
-     read quantitatively; the molab cell that runs all of it and keeps watching NHC.
-
-**The protocol that every number obeys.** Fitted on the tuning seasons 2016, 2017 and 2019. Scored once on the
-held-out seasons 2018, 2020, 2021 and 2022 (the Atlantic where the NHC guidance exists; all basins for the physics).
-Significance by a storm-block bootstrap (a star marks a whole 90% interval above zero). Shipped only if it helped
-held-out, reported either way. The coefficients module records the provenance of every table.
-
-## 2. Where it stands against the references (held-out)
-
-**Track, km, Atlantic 2018 / 2020-2022, homogeneous (749 / 703 / 626 / 554 / 490 / 374 / 281 / 206 cases at
-6 / 12 / 24 / 36 / 48 / 72 / 96 / 120 h, 79 storms).**
-
-| | 6 h | 12 h | 24 h | 36 h | 48 h | 72 h | 96 h | 120 h |
-|---|---|---|---|---|---|---|---|---|
-| NatureV1 0.14 blend (physics + live models) | 22.1 | 40.1 | 62.2 | 82.3 | 95.5 | 168.7 | 260.5 | 365.1 |
-| NatureV1 0.16, mean with HCCA | 21.5 | 35.7 | 54.1 | 72.5 | 89.4 | 149.6 | 227.7 | 318.7 |
-| **NatureV1 0.16 shipped (earned split + outlier gate)** | **22** | **36** | **53** | **72** | **89** | **149** | **225** | **317** |
-| HCCA (HFIP corrected consensus) | 29.9 | 40.7 | 60.3 | 80.7 | 104.6 | 170.5 | 253.8 | 363.9 |
-| TVCN (track consensus) | 29.8 | 41.8 | 62.7 | 84.5 | 109.5 | 170.0 | 248.8 | 346.5 |
-| NHC official forecast (OFCL) | 27.6 | 42.4 | 64.1 | 84.9 | 109.2 | 169.4 | 241.6 | 334.4 |
-
-The 0.16 blend is 11-13% under 0.14 at 12-120 h (every lead significant) and 12-22% under the official forecast at
-6-72 h, 5-6% at 96-120 h. The aids' 6 h values are interpolations between their analysis and their 12 h point, so
-read the aids from 12 h on.
-
-**Track against the archived models, all basins (from 4.16 of the model card; each reference on its own cases).**
-NatureV1 beats HRES (+18% at 24 h, +24% at 72 h), Pangu (+9%, +8%), GraphCast (+4%, +11%), Aurora (+6%, +16%) at
-every lead to day 5, is level with FuXi past 24 h, and trails FGN (WeatherNext 2) by 5-7% from 24 h on its 787
-cases. Against the single dynamical models in the a-deck (GFS, HWRF, HMON, COAMPS-TC, the GEFS mean) it is better at
-every lead by 6-39%.
-
-**Intensity, kt mean absolute error, Atlantic held-out, homogeneous with the official forecast.**
-
-| | 6 h | 12 h | 24 h | 36 h | 48 h | 72 h | 96 h | 120 h |
-|---|---|---|---|---|---|---|---|---|
-| persistence / SHIFOR (0.15's own references) | -- | -- | 0.15 is 16-33% better than persistence and 5-16% better than SHIFOR at every lead | | | | | |
-| NatureV1 0.15 consensus | 3.4 | 6.0 | 9.6 | 12.2 | 13.9 | 16.2 | 18.4 | 18.8 |
-| **NatureV1 0.16 (0.15 + the aids)** | **3.3** | **5.4** | **7.1** | **8.5** | **9.5** | **10.5** | **12.5** | **12.8** |
-| IVCN (intensity consensus) | 4.3 | 5.5 | 7.2 | 8.5 | 9.4 | 10.7 | 12.7 | 13.8 |
-| HCCA | 4.3 | 5.5 | 7.2 | 8.7 | 9.6 | 11.1 | 12.5 | 13.0 |
-| HWRF (HWFI) | 4.6 | 6.2 | 8.0 | 9.4 | 10.6 | 13.3 | 15.3 | 16.3 |
-| SHIPS with decay (DSHP) | 4.5 | 6.1 | 8.4 | 10.2 | 11.6 | 13.4 | 16.3 | 18.3 |
-| LGEM | 4.5 | 6.4 | 9.0 | 11.1 | 12.2 | 13.3 | 15.8 | 17.5 |
-| NHC official forecast | 3.6 | 5.0 | 7.4 | 8.8 | 10.1 | 11.2 | 12.4 | 13.4 |
-
-0.16 is 26-35% under 0.15 from 24 h on (every tuning season agreed in leave-one-season-out, 13-28% at 24-96 h) and
-4-6% under the official forecast at 24-72 h, level at 96-120 h. The official forecast is itself written from this
-guidance three hours later: read it as a product comparison.
-
-**Rapid intensification, P(+30 kt in 24 h).** Our logistic (17 predictors: the SHIPS-style set, the models' deepening,
-ocean heat content and 26 C depth, the gale radius): held-out Brier skill 0.154, AUC 0.864 (0.14: 0.122, 0.840). On the
-2020-2022 cases where the NHC e-deck carries RI rows (there are none in the archive before 2020): ours 0.125, the
-SHIPS-RII consensus 0.068, the deterministic SHIPS-RII 0.020, the logistic -0.070, the Bayesian 0.074, DTOPS 0.171;
-the equal-weight mean of ours and DTOPS 0.199. That mean is reported beside ours, not as the headline, because it
-could not be chosen on a tuning season.
-
-**Peak intensity.** P(peak within 5 days >= 64 / 96 / 113 / 137 kt): held-out Brier skill 0.32 / 0.31 / 0.28 / 0.28
-against 0.26 / 0.22 / 0.15 / 0.16 for the best per-lead category probability. Calibrated peak quantiles: coverage
-0.53 / 0.77 / 0.91 / 0.95 at the 50 / 75 / 90 / 95% levels; the 90% quantile sits +4 kt above the true peak of the
->= 137 kt storms where the consensus maximum sits -37 kt. E[peak | RI]: +0.6 kt bias, 13 kt MAE on the storms that went
-rapid. The bias that remains is conditional: -21 kt at 24 h on the storms that intensify rapidly (0.15: -23; the
-official forecast: -19), +14 kt on those that weaken fast.
-
-**Cone and swarm.** The flow-dependent cone replaces the climatological one; the swarm's raw worlds were 1.4-3.2 times
-too wide (the truth inside the nominal 67% radius 81-99% of the time); sized to the cone, 396 held-out forecasts put
-the truth inside the 50 / 67 / 90% radii 50-63 / 64-75 / 85-90% of the time.
-
-**Rain.** R-CLIPER along the observed track of 24 US landfalls against NOAA MRMS gauge-corrected radar delivered half
-the observed rain. The reshaped profile (multiplier 1.19, radial tail x1.5, front-right asymmetry 0.3) lifts the
-held-out threat score for 100 mm to 0.296 and for 250 mm from 0.12 to 0.348, and brings the strong storms' area
->= 250 mm from 3.2x observed to 1.7x. The GFS's accumulated precipitation moved with each world, at half weight:
-Ida 23 vs 45 mm mean error, Nicholas 17 vs 55, Fred 21 vs 36, Ian level.
-
-**Timing.** No systematic along-track bias (+1 / +4 / +5 / +2 / -1 km at 6-48 h). Arrival-time error 3.6 h at 24 h,
-7.3 h for storms under 3 m/s: reported as a window in the landfall report, nothing corrected. The previous cycle's
-error fed back into the track: +1.1-1.2% at 12-24 h, nothing past 48 h.
-
-## 3. The 0.16 work, item by item
-
-The release started from six named deficits (the roadmap matrix) and ended with eight rows, each with a state.
-
-| deficit | what the archive said | what shipped / what was rejected |
-|---|---|---|
-| explosive peak gap (forecast peak 25-37 kt under category-5 peaks) | regression to the mean under RI uncertainty, not a loss artefact; any weight toward the RI path costs the 94% that do not explode | **shipped**: calibrated peak quantiles, E[peak \| RI]; the aids take 26-35% off the intensity error but move the RI-case bias only -23 -> -21 kt |
-| track 2-7% behind FGN past 12 h | an equal-weight mean diluted by weaker members; no FGN live | **shipped**: the NHC aids (HCCA) as a member, -11-13%; **rejected**: dynamic per-storm model weighting (~0), NNLS member weights (+0.3-1.1%, noise) |
-| light-rain bloat | a per-storm scale error from wetter tuning storms, not a radial-tail problem | **shipped**: the reshaped profile and the GFS rain member; **rejected**: every nonlinear transform, a 115-kt saturation, a speed factor |
-| terrain and moisture | no moisture flux in a parametric profile | **partly**: east of Melissa right since the reshape; the QPF member is the moisture term; IVT orography needs a calibration set |
-| stalls over water held too strong | the sign of the stall residual flips between seasons | **rejected**: the fixed rule is 45-122% worse on the stall cases; Melissa stalled over 120 m of 26 C water and intensified |
-| landfall timing 3-4 h early | no along-track bias; the error is a spread, largest for slow movers | **measured, reported as a window**, nothing nudged |
-| the operational guidance was not in the room | the a-deck carries every aid minutes after the cycle | **shipped**: `naturev1.swarm.adeck` + `naturev1.cyclone.aids`, two fitted tables, stand-ins by lineage (HAFS for HWRF/HMON, TVCN for HCCA) |
-| the NHC RI guidance was not in the room | the SHIPS text carries five schemes live | **shown beside ours** with the equal-weight mean and the no-tuning-sample caveat |
-
-**The averaging penalty**, raised on the Melissa 26 Oct 12 UTC cycle (ours 15 km at 24 h, HCCA 70, the mean 42), taken
-to the archive:
-
-| held-out cases | n | ours alone | HCCA | TVCN | 50/50 mean | ours closer than HCCA | ours the outlier against TVCN |
-|---|---|---|---|---|---|---|---|
-| all with HCCA | 641 | 62 km | 60 | 63 | 54 | -- | -- |
-| the 20% that disagree most (>= 92 km apart at 24 h) | 159 | 133 | 93 | 95 | 94 | 31% | 97% |
-| the 10% that disagree most (>= 128 km apart) | 80 | 220 | 101 | 106 | 138 | 16% | 100% |
-
-When the two disagree strongly, our standalone is the one that is wrong two times in three. Rejected on the tuning
-seasons: ours 2/3, a gate toward ours, the median and the trimmed mean of ours/HCCA/TVCN. Shipped: (1) **weights earned
-from the previous cycle** -- the previous forecasts of ours and of HCCA verified against the position just analysed,
-`sigmoid(0.5 log(e_HCCA / e_ours))` within 25-75% at 6-24 h; (2) **the outlier gate** -- beyond 1.5 cone radii of
-disagreement up to 10% of the pair's weight moves away from whichever member is further from TVCN, from 12 h on.
-Together on held-out: 1.4 / 2.5 / 1.1 / 0.7 / 1.0 / 1.9 / 2.3% lower error at 12 / 24 / 36 / 48 / 72 / 96 / 120 h, every
-lead significant. The disagreement is reported per lead and both tracks are in the record.
-
-**Also built in 0.16:** the GOES band-13 diagnostics with trend (`infrared.py`); the cycle record and history
-(`bulletin.py`); `forecast_storm(previous="auto", guidance=True)`; the molab cell rewritten with the watch loop; audit
-fixes (dateline-safe swarm rescale, caller's leads for the 24/48 h indices, silent fallbacks leave a note, NHC-only
-ids, the previous analysis position as the first feedback knot); the benchmark table.
-
-## 4. Melissa (AL13 2025), replayed with what was known at the time
-
-| forecast from | before landfall | P(landfall, Jamaica) | centre ashore, median (10-90%) | consensus landfall | intensity then (10-90%) | RI branch (its probability) | P(peak >= cat 4 / cat 5) | track error 24 / 48 / 72 h: 0.16 (own; official) |
-|---|---|---|---|---|---|---|---|---|
-| 26 Oct 00 UTC | 65 h | 72% | 28 Oct 09 UTC (27 Oct 21 -> 28 Oct 21) | 28 Oct 06 UTC, Clarendon | 96 kt (64-132) | 124 kt, peak 130 (23%) | 62% / 28% | 44 / 121 / 195 km (42 / 158 / 277; 34 / 123 / 124) |
-| 26 Oct 12 UTC | 53 h | 83% | 28 Oct 12 UTC (06 -> 21) | 28 Oct 11 UTC, St Elizabeth | 101 kt (71-136) | 151 kt, peak 152 (19%) | 100% / 31% | 42 / 72 / 147 km (15 / 53 / 161; 40 / 54 / 73) |
-| 27 Oct 00 UTC | 41 h | 83% | 28 Oct 15 UTC (09 -> 21) | 28 Oct 14 UTC, St Elizabeth, 18.06N 77.72W | 98 kt (78-121) | 149 kt, peak 160 (8%) | 100% / 23% | 54 / 71 / 212 km (38 / 69 / 215; 79 / 79 / 164) |
-
-Actual: landfall near New Hope, St Elizabeth (18.09N 77.97W) about 17 UTC on 28 October at 160 kt; peak 165 kt. Right:
-the landfall point and probability, the parish ranking (St Elizabeth 77%, Manchester 69%, Westmoreland 60%, Clarendon
-54%; the east 10-15%), the far-west rain (Westmoreland 413 mm if hit against the 309 mm gauge where 0.15 said 689;
-Manchester 584 / 865 against 817; St Catherine 468 / 666 against 668). Wrong, said plainly: the intensity -- the aids
-were all low on this storm and pulled the 48 h intensity to 85-100 kt against 105-165; the explosive case stayed a tail
-event (the 95% peak quantile 133-140 kt against 165), as it did for the official forecast (140 kt at 24 h against 155);
-parish timing about four hours early.
-
-## 5. Published
-
-* **PyPI**: `naturev1` 0.16.0 (wheel and sdist; install verified from the index). `pip install "naturev1[swarm,hub]"`.
-* **Hugging Face** `CorxLabs/NatureV1-500`: the model card (section 4.17 carries the 0.16 tables), `melissa_landfall.png`,
-  `melissa_jamaica.png`, `benchmark_heldout_atlantic_2018_2020_2022.csv.gz` (849 cases, 120,472 rows: the truth and
-  every reference's forecast or error at every lead; `naturev1.cyclone.verify.compare` scores a new model on it).
-* **Git**, branch `claude/linear-context-architecture-a35c6h` of `Wisk-inc/transformers`, `natureweather/`: commits
-  `ed86e0e` (rain shape, operations layer, infrared, audit), `5eae22b` (peak quantiles, arrival window, QPF member,
-  cell, roadmap), `b3d5a09` (the guidance layer), `4a5917b` (Melissa), `4ac6e53` (earned weights), `45e92bd` (the
-  outlier gate). Tests: 403 passed, 1 skipped, plus the 0.16 additions (`tests/test_adeck.py`, `test_peak.py`,
-  `test_operational.py`).
-* **The cell**: `molab_swarm_cell.py`, one marimo cell, live or replay.
-
-## 6. Limits that remain, and the next steps
-
-* The explosive cases are tail events to every mean forecast here, ours and the NHC's; the answer stays in the
-  distribution (quantiles, the RI branch) until a predictor that separates them exists. The 0.12 satellite path is the
-  candidate: GOES structure and lightning as RI predictors need an archive of storm-centred imagery to fit.
-* The guidance tables were fitted on Atlantic storms; an eastern Pacific storm gets the same weights, unverified there.
-  HWRF and HMON appear in about half the 2026 cycles; the blend renormalises and the record says what it used.
-* The cone is sized for the track before the aids; with the aids the error is 11-13% smaller, so coverage runs a
-  little above nominal. A refit on the blended track is straightforward.
-* The RI blend with the NHC schemes needs a tuning sample: build 2023-2025 as a new tuning set.
-* A split swarm when ours and HCCA disagree beyond the cone (half the worlds on each track) would show both scenarios
-  in the threat map instead of a midpoint neither predicts; it needs a swarm re-verification on the 396 cases.
-* Real-time data still to bring in: NESDIS ocean heat content, ECMWF ENS tracks (IFS-ENS, AIFS-ENS), HAFS-A/B tracks,
-  CIMSS ADT/SATCON/AiDT, NHC wind-speed probabilities, STOFS and SLOSH for surge.
-
-## 7. NatureV2-500
-
-`CorxLabs/NatureV2-500` starts from the NatureV1-500 stage-1 checkpoint (`checkpoints/stage1/latest.pt`, with its
-`config.json` and `normalizer.json`) and carries this code base. The plan: fine-tune the satellite encoder (the
-GOES/GridSat band-13 path of 0.12, SatNet-Storm 2.0 and the global retrieval) on the storm-centred imagery, add the
-new features the 0.16 verification asked for (infrared structure and its trend, lightning, the ocean heat feed) as
-inputs to the storm heads and to the RI probability, and verify them on the same held-out seasons with the same
-benchmark table before any of it changes a number in the operational path.

ROADMAP_0.16.md

@@ -1,55 +0,0 @@
-# naturev1 0.16: the engineering roadmap, closed out
-
-The six deficits of 0.15, what the archive said causes each, the experiment that decided each fix, and where it ended.
-Every item was held to the same rule as everything before it: fitted on the tuning seasons (2016, 2017, 2019), scored
-once on the held-out seasons (2018, 2020-2022), shipped only if it helped there, and reported either way. "Held-out"
-below always means those seasons. The matrix the user supplied is kept, with the mechanics corrected where the archive
-said otherwise -- a roadmap built on the wrong cause fixes the wrong thing.
-
-| # | deficit | what the data say causes it | fix | state |
-|---|---|---|---|---|
-| 1 | explosive peak gap: forecast peak 25-37 kt under the true peak of category-5 storms | not a loss-function artefact (the intensity is a simplex-weighted consensus, no network); it is regression to the mean under rapid-intensification uncertainty -- any weight that moves the mean toward the RI path costs the 94% of cases that do not explode | close it in the **distribution**, not the mean: calibrated peak quantiles (50/75/90/95%) and E[peak \| RI]; then the operational guidance as members | **shipped** (`peak_quantiles`, `peak_if_ri`): held-out q90 sits +4 kt above the true peak of the >=137 kt storms where the consensus max sits -37 kt; coverage 0.53/0.77/0.91/0.95; E[peak \| RI] +0.6 kt bias on the storms that went rapid. The a-deck blend (row 7) takes 26-35% off the intensity error at 24-120 h but moves the RI-case bias at 24 h only from -23 to -21 kt (the official forecast: -19): the gap is a property of every mean forecast, which is why the distribution products stay the answer |
-| 2 | track: 2-7% behind FGN past 12 h | an equal-weight mean is diluted by weaker members; the live set has no FGN at all | dynamic per-storm model weighting from the last cycles' errors (tested: ~0); NNLS member weights (+0.3-1.1%, not shipped); the NHC a-deck's consensus aids as live members | **shipped** (row 7): the plain mean of our blend and HCCA, chosen on the tuning seasons, lowers the held-out Atlantic track error 11-13% at 12-120 h and beats the official forecast by 12-22% at 6-72 h |
-| 3 | light-rain bloat from the rain multiplier | the tuning storms are wetter than the held-out ones (obs/forecast 1.9 vs 1.5), so a pooled multiplier runs high in the periphery; it is a per-storm scale error, largest in the cores of slow movers, not a radial-tail problem | profile reshaped (tail x1.5, front-right asymmetry 0.3, multiplier 1.19); the model's own rain as a member | **shipped**: reshape (held-out CSI 250 mm 0.295 -> 0.348, strong storms' area >=250 mm 3.2x -> 1.7x) and the GFS accumulated precipitation travelling with every world as half of its rain (radar check on US landfalls: Ida 23 vs 45 mm MAE, Nicholas 17 vs 55, Fred 21 vs 36, Ian level). Rejected on the tuning storms: every nonlinear heavy-favouring transform, a 115-kt saturation, a translation-speed factor |
-| 4 | terrain and moisture: rain under the wind, not where two days of easterlies fed the Blue Mountains | a parametric profile has no moisture flux and no outer bands; the orographic term is a slope x wind product without moisture; the multiplier was calibrated on flat ground | reshaped profile; the model-QPF member, which carries the model's moisture and its own orography | **partly**: east of Melissa's track right since the reshape (Portland 470 vs 536 mm, St Catherine 624 vs 668, Kingston 447 vs 567); the QPF member is the moisture term; an integrated-vapour-transport orographic scheme needs a calibration set that does not exist yet |
-| 5 | stalls over water held too strong | the continuous depth-aware cooling lost on the tuning seasons (15.3 -> 15.4-15.6 kt); a stall rule (speed < 3 kt for > 12 h, D26 < 50 m, -5 to -15 kt) was tested rather than assumed | penalty fitted on stall cases, with the deep-water sign check | **rejected**: the sign of the stall residual flips between the tuning and the held-out seasons, and the fixed rule is 45-122% worse on the stall cases themselves; Melissa stalled over 120 m of 26 C water and intensified. Nothing shipped; the wake cooling already in the SHIPS-style members stands |
-| 6 | landfall timing 3-4 h early | hypothesis was a missing coastal slowdown; measured instead as along-track bias by speed, lead and distance to land | along/cross decomposition, speed-dependent correction, arrival-time check | **measured, no correction**: no systematic along-track bias (+1/+4/+5/+2/-1 km at 6-48 h); the arrival-time error is 3.6 h at 24 h overall and 7.3 h for storms moving under 3 m/s -- so the error is reported as a window (`ARRIVAL_TIME_ERROR`, in the landfall report) and nothing is nudged |
-| 6b | the averaging penalty: a fixed 50/50 mean with HCCA drags a forecast that caught the turn toward a member that did not (Melissa 26 Oct 12 UTC: ours 15 km, HCCA 70, the mean 42) | on held-out, when the two disagree most it is our standalone that is wrong two times in three (24 h: ours 133 km, HCCA 93, the mean 94; in the extreme tenth ours 220, HCCA 101), so trusting the standalone in a disagreement loses on average | weights earned from the previous cycle's verified errors; an outlier gate with TVCN as tie-breaker; rules that favour ours, the median and trimmed mean of three | **shipped** (`ADECK_TRACK["adaptive"]`, `["gate"]`): earned split at 6-24 h (b 0.5, within 25-75%) and up to 10% of the pair away from the member that stands alone beyond 1.5 cone radii from 12 h -- together 1.4-2.5% lower held-out error at 12-36 h, 1-2% at 48-120 h, every lead significant; the disagreement reported per lead with both tracks in the record. **Rejected**: ours 2/3, a gate toward ours, the median and trimmed mean of ours/HCCA/TVCN (all lost on the tuning seasons) |
-| 7 | the operational guidance was not in the room | the NHC a-deck carries every aid's track and intensity minutes after each cycle; nothing read it | `naturev1.swarm.adeck` reads the public a-deck (live and archive); `naturev1.cyclone.aids` blends the aids in with tables fitted on the tuning seasons | **shipped**: intensity -- simplex weights over our consensus, IVCN, HWRF, HMON, SHIPS, LGEM, GFS and HCCA (leave-one-season-out gains 13-28% at 24-96 h in every tuning season; held-out 26-35% at 24-120 h, 4-6% ahead of the official forecast at 24-72 h); track -- the mean with HCCA (row 2). HAFS-A/B stand in for HWRF/HMON and TVCN for HCCA when those are absent (lineage stand-ins, reported as such) |
-| 8 | the NHC's rapid-intensification guidance was not in the room | the SHIPS text carries the SHIPS-RII, logistic, Bayesian, DTOPS and consensus probabilities live; the e-deck carries them after the fact | read both; verify against ours on the archive | **shown beside ours, not the headline**: the archive's e-decks carry no RI rows before 2020, so nothing could be chosen on the tuning seasons; on 2020-2022 (453 cases, 24 events) ours has Brier skill 0.13, the SHIPS-RII consensus 0.07, DTOPS 0.17 and the equal-weight mean of ours and DTOPS 0.20 -- that mean is reported in the record and the cell as `ri_probability_combined`, with this caveat attached |
-
-## Shipped in 0.16
-
-* **The NHC guidance as members** -- `naturev1.swarm.adeck` (a-deck, e-deck, SHIPS text), `naturev1.cyclone.aids`, `coefficients.ADECK_TRACK` / `ADECK_INTENSITY`; `forecast_storm(guidance=True)` by default; `track_ours` / `intensity_ours` keep our own forecast beside the blend; the official forecast and the RI guidance in `run["guidance"]` and the cycle record.
-* **The averaging penalty answered** -- the ours/HCCA split earned from the previous cycle and gated away from the outlier against TVCN; the disagreement per lead in `aids_track`.
-* **Rain** -- `RAIN_SCALE = {multiplier 1.19, tail 1.5, asymmetry 0.3 front-right}`; orographic cap 2; the GFS QPF member (`models.fetch_qpf`, `qpf_weight` 0.5).
-* **Peak quantiles and E[peak | RI]** -- `coefficients.PEAK_QUANTILES`, `PEAK_IF_RI`; in the landfall report ("plan for the 90% figure").
-* **Arrival-time window** -- `coefficients.ARRIVAL_TIME_ERROR`; in the landfall report.
-* **Operations layer** -- `naturev1.swarm.bulletin` (every cycle saved as JSON + parish CSV; the previous cycle found again and fed back automatically), `naturev1.swarm.infrared` (GOES band-13 structure diagnostics with trend), `forecast_storm(previous="auto")`, the molab cell with its watch loop.
-* **Audit fixes** -- missing physics context reported, swarm rescale keeps the longitude frame across the dateline, 24/48 h indices follow the caller's leads, silent fallbacks leave `intensity_note`, NHC-only ids, previous analysis position as the first feedback knot.
-* **The swarm sized to the flow-dependent cone** (0.15.0, verified on 396 held-out forecasts).
-
-## Tried and rejected (kept here so nobody tries them again without new evidence)
-
-Stall penalty (row 5); translation-speed rain factor and 115-kt saturation; nonlinear rain transforms; dynamic per-storm
-model weighting; NNLS physics-member weights (+0.3-1.1%, inside the noise); the RI-path mixture into the mean; the
-continuous depth-aware wake cooling; CHIRPS as rain truth (too coarse at the parish scale); the fitted simplex over
-the track aids (within 0.2% of the plain mean on the tuning seasons, so the mean ships).
-
-## Real-time data still to bring in (each needs a reader and a verification before it changes a number)
-
-* NESDIS ocean heat content (26 C depth, TCHP) on CoastWatch ERDDAP, daily -- replaces the climatology under the storm.
-* ECMWF open-data TC-track BUFR for IFS-ENS, AIFS-single and AIFS-ENS (51 + 51 member tracks and intensities).
-* HAFS-A/B tracks (3-hourly to 126 h, with radii) on NOMADS -- the a-deck already carries their interpolated runs.
-* CIMSS ADT / SATCON / AiDT / D-MINT text feeds (30-minute satellite intensity, radii) and STAR SAR winds -- fixes with intensity for the particle filter.
-* GLM lightning and GOES band-13 structure as RI predictors (an archive of storm-centred imagery is needed to fit them).
-* NHC wind-speed probabilities and arrival-time grids, STOFS-2D water levels and the Jamaica SLOSH MOM layer for a surge pillar.
-
-## The benchmark we publish: the answer key
-
-`benchmark_heldout_atlantic_2018_2020_2022.csv.gz` on the model repository: the 849 held-out Atlantic cases (storm,
-time, position, intensity) with the best-track truth at every lead and every reference's forecast or error on it --
-NatureV1 0.14/0.16 tracks and 0.15/0.16 intensities, the NHC official forecast and its aids (HCCA, TVCN, IVCN, HWRF,
-HMON, SHIPS, LGEM, GFS, GEFS mean), the archived models' track errors (HRES, Pangu, GraphCast, FuXi, Aurora, FGN),
-CLIPER and extrapolation. `naturev1.cyclone.verify.compare` scores any new forecast against it on the same storms,
-with the storm-block bootstrap, so that a claim about a hurricane model can be checked rather than believed.

b300_naturev1.py

@@ -1,151 +0,0 @@
-# ═══════════════════════════════════════════════════════════════════════════════════════════════════
-#  NatureV1 0.12 on 8x NVIDIA B300 -- the satellite path, then every basin.
-#
-#  Cells for JupyterLab or VS Code ("# %%"), or run top to bottom as a script. Every long step runs as
-#  its own detached process with a log under DATA/logs: closing the notebook or losing the connection
-#  never stops it, and running the same cell again reattaches to it instead of starting it twice.
-#
-#  What happens, and roughly how long it takes on 8x B300 with a fast NVMe array and a fast network:
-#
-#    1  install, preflight                     minutes   checks GPUs, disks, network, HF token; measures a step
-#    2  base model + statistics from the Hub   minutes   the trained 0.10/0.11 release is the starting point
-#    3  labels                                 minutes   IBTrACS since 1980, every basin: ~230,000 storm fixes
-#    4  stage the record (two jobs at once)    1-4 h     ERA5 1980-2021 (~0.33 TB) and GridSat-B1 1980-2021
-#                                                        (~4-6 TB read, ~0.8 TB of training shards written)
-#    5  stage A, 3 h: both satellite networks  3 h       GPUs 0-3: the storm network; GPUs 4-7: the retrieval
-#    6  stage B: heads + backbone tail         2 h + ~1  every basin, satellites in the loop; then banks with
-#                                                        rollout members, consensus, calibration, test scores
-#    7  publish                                minutes   only replaces the release if it beat the old one
-#
-#  Every checkpoint of every run is pushed to HF_REPO as it is written (checkpoints/<run>/latest.pt, and
-#  the weights of each one under checkpoints/<run>/history/), so a dead machine resumes on a new one.
-#
-#  The training time is the GPU budget you set (STAGE_A_HOURS, STAGE_B_HOURS); staging is separate and
-#  bound by network and disk, not by the GPUs. Nothing here has been run on a B300 by its author -- the
-#  code is tested end to end on CPU (including real two-process data parallelism); the preflight is the
-#  first thing that touches your hardware, and it says so if anything is wrong.
-# ═══════════════════════════════════════════════════════════════════════════════════════════════════
-
-# %% [0] settings ──────────────────────────────────────────────────────────────────────────────────────
-HF_REPO        = "CorxLabs/NatureV1-500"
-HF_TOKEN       = ""            # paste a WRITE token here for this session, then clear it afterwards
-DATA           = "/data/naturev1"   # the NVMe array: >= 2 TB free (staged shards + ERA5 + working space)
-FIRST_YEAR     = 1980          # GridSat-B1 begins 1980
-LAST_YEAR      = 2021          # WeatherBench 2's 1.5-degree ERA5 ends 2021-12-31
-SAT_RESOLUTION = 0.25          # degrees of the staged global frames (0.1 writes ~4 TB of shards instead of ~0.8)
-STAGE_A_HOURS  = 3.0           # both satellite networks, side by side, four GPUs each
-STAGE_B_HOURS  = 2.0           # storm heads + backbone tail on all eight GPUs (banks and scoring come after)
-TAIL_BLOCKS    = 4             # backbone blocks fine-tuned in stage B (of 17)
-ROTATIONS      = 4             # test-time rotation ensemble kept in the banks (1: off); used only if it helps
-STAGING_WORKERS = None         # None: all CPUs but 16
-KEEP_RAW       = False         # keep the raw GridSat files (4-6 TB) after staging
-BRANCH         = "claude/linear-context-architecture-a35c6h"
-
-# %% [1] install and preflight ──────────────────────────────────────────────────────────────────────────
-import os, subprocess, sys
-from pathlib import Path
-
-REPO_URL = "git+https://github.com/Wisk-inc/transformers@" + BRANCH
-subprocess.run([sys.executable, "-m", "pip", "install", "-q", "--upgrade",
-                f"ihelix @ {REPO_URL}#subdirectory=ihelix",
-                f"naturev1[all] @ {REPO_URL}#subdirectory=natureweather",
-                "safetensors", "netCDF4", "h5netcdf"], check=True)
-if HF_TOKEN.strip():
-    os.environ["HF_TOKEN"] = HF_TOKEN.strip()       # inherited by every job below; never written to disk
-os.environ.setdefault("HF_HUB_ENABLE_HF_TRANSFER", "0")
-DATA = Path(DATA)
-LOGS, SAT, CKPT = DATA / "logs", DATA / "satellite", DATA / "runs"
-for folder in (LOGS, SAT, CKPT):
-    folder.mkdir(parents=True, exist_ok=True)
-
-import naturev1
-from naturev1.hardware import hardware_preflight
-
-print(f"naturev1 {naturev1.__version__}")
-READY = hardware_preflight(DATA, HF_REPO, need_tb=1.6 if SAT_RESOLUTION >= 0.25 else 5.0, hours=STAGE_A_HOURS)
-assert READY, "fix the lines marked !! above before spending GPU hours"
-
-# %% [2] the starting model and its statistics, from the Hub ───────────────────────────────────────────
-import shutil
-import torch
-from huggingface_hub import hf_hub_download
-
-BASE = DATA / "base.pt"
-if not BASE.exists():
-    for tag in ("stage3", "stage2"):                 # the newest released stage
-        try:
-            shutil.copy2(hf_hub_download(HF_REPO, f"checkpoints/{tag}/latest.pt"), BASE)
-            print(f"starting from checkpoints/{tag}/latest.pt")
-            break
-        except Exception as error:
-            print(f"no {tag} on the Hub ({type(error).__name__})")
-STATS = DATA / "stats.json"
-if not STATS.exists():
-    shutil.copy2(hf_hub_download(HF_REPO, "staging/stats.json"), STATS)
-base = torch.load(BASE, map_location="cpu", weights_only=False)
-print("base config:", {k: base["config"][k] for k in ("hidden_size", "num_layers", "analysis_channels", "state_channels")})
-ANALYSIS_CHANNELS = base["config"]["analysis_channels"]
-TENDENCY = DATA / "tendency.pt"
-recorded = base["model"].get("state_tendency")
-if recorded is not None and float(recorded.abs().sum()) > 0:
-    torch.save(recorded.float(), TENDENCY)
-    print("tendency scale: recorded in the checkpoint")
-del base
-
-# %% [3] labels: every basin since 1980 ────────────────────────────────────────────────────────────────
-import numpy as np
-from naturev1.ibtracs import describe_table, fetch_ibtracs, parse_ibtracs, storm_label_table
-
-IBTRACS = fetch_ibtracs(DATA)
-LABELS = SAT / "labels.npz"
-if not LABELS.exists():
-    np.savez(LABELS, **storm_label_table(parse_ibtracs(IBTRACS, since=FIRST_YEAR, until=LAST_YEAR)))
-print(describe_table(dict(np.load(LABELS))))
-
-# %% [4] stage the record: ERA5 and GridSat, as two detached jobs ──────────────────────────────────────
-from naturev1.b300 import follow, start_job
-from naturev1.satstage import staging_plan
-
-print(staging_plan(range(FIRST_YEAR, LAST_YEAR + 1), SAT_RESOLUTION, len(np.load(LABELS)["time"])))
-ERA5 = DATA / f"era5_{FIRST_YEAR}_{LAST_YEAR}.npy"
-start_job("era5", [sys.executable, "-c",
-                   f"from naturev1.b300 import stage_era5_record; "
-                   f"stage_era5_record({str(DATA)!r}, {FIRST_YEAR}, {LAST_YEAR}, {str(STATS)!r}, workers=32)"], LOGS)
-workers = STAGING_WORKERS or max((os.cpu_count() or 32) - 16, 4)
-start_job("gridsat", [sys.executable, "-m", "naturev1.satstage", "--root", str(SAT), "--ibtracs", str(IBTRACS),
-                      "--years", f"{FIRST_YEAR}-{LAST_YEAR}", "--workers", str(workers),
-                      "--resolution", str(SAT_RESOLUTION)] + (["--keep-raw", "--raw-dir", str(DATA / "gridsat_raw")]
-                                                              if KEEP_RAW else []), LOGS)
-follow(LOGS, ["era5", "gridsat"])
-
-# %% [5] stage A: the storm network on GPUs 0-3, the retrieval on GPUs 4-7, side by side ─────────────────
-if not TENDENCY.exists():                    # a checkpoint from before 0.11 does not record it: measure it
-    from naturev1.b300 import memmap_tendency
-
-    torch.save(memmap_tendency(ERA5, ANALYSIS_CHANNELS), TENDENCY)
-common = ["--checkpoint", str(BASE), "--root", str(SAT), "--table", str(LABELS), "--output", str(CKPT),
-          "--hours", str(STAGE_A_HOURS), "--hub-repo", HF_REPO]
-start_job("stage-a-satnet", ["-m", "naturev1.sattrain", "satnet", *common, "--workers", "12"], LOGS,
-          gpus=[0, 1, 2, 3])
-start_job("stage-a-retrieval", ["-m", "naturev1.sattrain", "retrieval", *common, "--era5", str(ERA5),
-                                "--tendency", str(TENDENCY), "--workers", "10"], LOGS, gpus=[4, 5, 6, 7])
-follow(LOGS, ["stage-a-satnet", "stage-a-retrieval"])
-
-# %% [6] stage B: storm heads + the backbone's last blocks, every basin, satellites in the loop ───────────
-start_job("stage-b", ["-m", "naturev1.stormtrain", "--base", str(BASE),
-                      "--satnet", str(CKPT / "stage-a-satnet" / "latest.pt"),
-                      "--retrieval", str(CKPT / "stage-a-retrieval" / "latest.pt"),
-                      "--era5", str(ERA5), "--tendency", str(TENDENCY), "--ibtracs", str(IBTRACS),
-                      "--table", str(LABELS), "--root", str(SAT), "--output", str(CKPT),
-                      "--hours", str(STAGE_B_HOURS), "--tail", str(TAIL_BLOCKS), "--rotations", str(ROTATIONS),
-                      "--hub-repo", HF_REPO], LOGS,
-          gpus=list(range(8)))
-follow(LOGS, ["stage-b"])
-print((CKPT / "stage-b" / "report.txt").read_text() if (CKPT / "stage-b" / "report.txt").exists() else "no report yet")
-
-# %% [7] publish: the release only if it beat the model it started from ──────────────────────────────────
-from naturev1.b300 import publish_release
-
-where = publish_release(CKPT / "stage-b" / "latest.pt", STATS, HF_REPO, DATA / "release",
-                        comparison=CKPT / "comparison.json", report=CKPT / "stage-b" / "report.txt")
-print("published to", where, "-- now clear HF_TOKEN in cell [0]")

colab_naturev1.py

@@ -1,766 +0,0 @@
-# ═══════════════════════════════════════════════════════════════════════════════════════════════════
-#  NatureV1 0.11.0 — the whole thing in one cell. Pure Python: marimo, Colab, Jupyter or a plain script.
-#
-#  Paste and run. It installs what it needs, stages the data, builds the 89M-parameter model, trains it
-#  in stages, scores itself against persistence and climatology, and only publishes if it earned it.
-#
-#  With BACKGROUND = True (the default) the run happens in a supervised process on the machine itself:
-#  it keeps going if the wifi drops or the notebook closes, and it restarts itself from its last
-#  checkpoint if it crashes, runs out of GPU memory, or stalls. The cell then stays running as a live
-#  window on it -- every log line as it happens, a proof-of-life line every minute when the run is
-#  quiet, a status line every ten minutes -- until the run finishes (WATCH_SECONDS = None). Stopping the
-#  cell stops only the window; the run never depends on it. Run the cell again any time to reopen it.
-#
-#  If it stops for any reason -- a crash, a reboot, naturev1.stop(), the supervisor giving up -- just run
-#  this cell again: every stage continues from its last checkpoint (saved every minute, a snapshot every
-#  30 minutes, and a second copy in BACKUP_DIR). naturev1.progress() shows where it will continue from.
-#
-#  ON A HOSTED NOTEBOOK (molab, Colab): the run survives the notebook, but not the machine. molab ends a
-#  session after 12 hours, or after 90 idle minutes, and wipes its disk. So, with HF_TOKEN set, everything
-#  expensive is mirrored to HF_REPO as soon as it exists: the staged ERA5 (once, in the background), the
-#  checkpoints (every 10 minutes, and once more when the session is told to stop), the storm feature
-#  banks, the remembered batch size. A new session pulls them back in minutes instead of rebuilding them:
-#  the download does not start over, training resumes where the last session stopped. On molab: set
-#  HF_TOKEN, keep this tab open (the cell staying active is what keeps the notebook from being idle), and
-#  when the 12 hours are up, open a new session and run this cell again.
-#
-#  0.9: the hurricane heads read the storm's physical environment -- deep-layer steering, 200-850 hPa
-#  shear, mid-level moisture, ocean temperature -- computed from the model's own atmosphere, plus a
-#  wider 1000 km pool. The track head predicts the residual from a physics-only steering track, and the
-#  forecast is a multi-model consensus of learned track, steering track and extrapolation, weighted per
-#  lead on held-out seasons. The scorecard shows every member, so you can see which one earns its place.
-#
-#  0.11: stage three -- what the satellite sees. Storm-centred infrared (HURSAT-B1 to 2016, GridSat-B1
-#  after, GOES band 13 live) feeds a small branch into the hurricane heads, aimed at intensity, which a
-#  1.5-degree reanalysis cannot see. It is fine-tuned with the backbone frozen and can never end worse on
-#  held-out storms than the model it started from. Then, from the red team: landfall and rapid-
-#  intensification probabilities are calibrated on held-out seasons, an input monitor marks forecasts
-#  from inputs unlike training as untrustworthy, the forecast can no longer state impossible structure,
-#  and the rollout's tendency statistics ship with the weights. Stages already trained are loaded, not
-#  redone: a finished 0.10 run goes straight to stage three.
-# ═══════════════════════════════════════════════════════════════════════════════════════════════════
-
-BACKGROUND    = True      # supervised background run: survives disconnects, restarts on crash or stall
-STALL_MINUTES = 30        # background: restart a run that shows no progress for this long (12 while downloading)
-WATCH_SECONDS = None      # None: this cell stays running as a live window until the run finishes; or seconds
-MIRROR        = True      # mirror staged data, checkpoints and banks to HF_REPO (needs HF_TOKEN); see above
-
-RUN_PRETRAIN  = True      # stage one: every channel at every lead, on ERA5 reanalysis
-RUN_ROLLOUT   = True      # stage 1b: the whole atmosphere rolled forward 12 steps, CRPS ensemble
-RUN_STORMS    = True      # stage two: hurricane heads on HURDAT2, backbone frozen
-RETRAIN_STORMS = False    # stage two: train the heads again even if a stage-two checkpoint exists
-RUN_SATELLITE = True      # stage three: storm-centred infrared satellite, then calibration and the monitor
-RETRAIN_SATELLITE = False # stage three: train again even if a stage-three checkpoint exists
-RUN_SCORE     = True      # WeatherBench-style scorecards against persistence and climatology
-RUN_HINDCAST  = True      # forecast a held-out hurricane from its real analysis; compare with truth
-RUN_PUBLISH   = False     # push to the Hub -- only if it beats persistence somewhere
-RUN_FORECAST  = False     # live GOES forecast (refused while the satellite path is untrained)
-RUN_WATCHER   = False     # then re-forecast every hour
-
-STAGE_YEARS   = 5         # training years staged to local disk, ~7.5 GB each at 89 channels
-VAL_YEARS     = 1         # held-out years staged too, so validation and scoring are not network-bound
-EPOCHS        = 8         # passes over the staged years in stage one
-BATCH         = None      # None: find the largest batch that fits once, then remember it; or a number
-MAX_BATCH     = 16        # ceiling on the batch search: host RAM, not VRAM, is the limit above this
-WORKERS       = 4         # data-loading processes
-ROLLOUT_STEPS = 12        # longest rollout trained: 12 x 6 h = 72 h, GraphCast's curriculum
-ROLLOUT_TRAIN = 4_000     # optimizer steps of rollout training (the log prints the time per step)
-MEMBERS       = 2         # CRPS ensemble members; 1 = deterministic Gaussian training
-STORM_FIRST_SEASON = 1979 # the satellite era; earlier best-track intensities are much less reliable
-HINDCAST      = ("DORIAN", 2019)       # a held-out storm: 2019 is never trained on
-STORM         = (24.6, -78.2)          # live forecast: current storm centre (lat, lon)
-CITY          = (25.77, -80.19)        # live forecast: somewhere you want a local forecast
-HF_REPO       = "CorxLabs/NatureV1-500"
-HF_TOKEN      = ""        # a write token, to publish and mirror checkpoints; or set the HF_TOKEN env var
-DATA_DIR      = None      # None: /content on Colab, ~/naturev1_data elsewhere; or any folder with room
-BACKUP_DIR    = None      # second copy of every checkpoint. None: ~/naturev1_backup; best on another disk;
-                          # "" turns it off
-
-# ═══ 0 ═══ install ═════════════════════════════════════════════════════════════════════════════════
-# Standard library only, before numpy or torch are imported: pip may upgrade numpy while satisfying
-# zarr or gcsfs, and a numpy that changes under an imported torch fails far from here.
-import importlib
-import importlib.metadata
-import importlib.util
-import os
-import shutil
-import subprocess
-import sys
-
-os.environ.setdefault("GRPC_VERBOSITY", "ERROR")   # the cloud client logs every DataLoader fork otherwise
-# Let the GPU allocator grow segments instead of fragmenting them. Training at batch 8 fills a 96 GB card
-# to within ~130 MB, and without this the allocator has to flush and retry. Only takes effect if torch
-# has not touched the GPU yet in this kernel -- restart the kernel for it to apply.
-os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF", "expandable_segments:True")
-
-
-def _halt(message, kind="danger"):
-    """
-    End the cell here, on purpose. Only kind="danger" is an error. marimo shows the message as a
-    coloured note instead of a traceback, Jupyter and Colab show it without one, and a plain script
-    exits with status 0 for "success" and 1 for anything else -- which is what the supervisor of a
-    background run reads, so a run stopped part-way is resumed and a finished one is not.
-    """
-    marimo = sys.modules.get("marimo")
-    if marimo is not None and getattr(marimo, "running_in_notebook", lambda: False)():
-        try:
-            note = marimo.callout(marimo.plain_text(message), kind=kind)
-        except Exception:
-            note = None
-            print(message)
-        marimo.stop(True, note)
-    ipython = sys.modules.get("IPython")
-    if kind != "danger" and ipython is not None and getattr(ipython, "get_ipython", lambda: None)() is not None:
-        class Halted(Exception):
-            def _render_traceback_(self):
-                return []                         # the message printed above, and no traceback
-        print(message)
-        raise Halted("the cell stopped here on purpose -- the message is above")
-    if kind == "success":
-        print(message)
-        raise SystemExit(0)
-    raise SystemExit(message)
-
-
-# 0.11 is installed from the project's GitHub branch until it is on PyPI.
-_NEEDED = {"naturev1": ("naturev1[all] @ git+https://github.com/Wisk-inc/transformers"
-                        "@claude/linear-context-architecture-a35c6h#subdirectory=natureweather", (0, 11, 0)),
-           "ihelix": ("ihelix>=0.5.1", (0, 5, 1))}
-
-
-def _version(module):
-    try:
-        return tuple(int(p) for p in importlib.metadata.version(module).split(".")[:3])
-    except Exception:
-        return None
-
-
-_missing = [req for mod, (req, low) in _NEEDED.items()
-            if importlib.util.find_spec(mod) is None or (_version(mod) or (0,)) < low]
-if _missing:
-    print(f"installing: {' '.join(_missing)}")
-    _loaded = {name: getattr(sys.modules.get(name), "__version__", None) for name in ("numpy", "torch")}
-    _tries = ([("uv", ["uv", "pip", "install", "--python", sys.executable, "--upgrade", *_missing])]
-              if shutil.which("uv") else [])
-    _pip = [sys.executable, "-m", "pip", "install", "--upgrade"]
-    _tries += [("pip, fresh index", [*_pip, "--no-cache-dir", "--index-url", "https://pypi.org/simple", *_missing]),
-               ("pip, no cache", [*_pip, "--no-cache-dir", *_missing]),
-               ("pip", [*_pip, *_missing])]
-    for _label, _command in _tries:
-        try:
-            subprocess.check_call(_command)
-            print(f"installed via {_label}")
-            break
-        except (subprocess.CalledProcessError, FileNotFoundError):
-            print(f"  {_label} failed, trying the next way")
-    else:
-        _halt("could not install; add these in your package manager, then re-run: " + " ".join(_missing))
-    importlib.invalidate_caches()
-    # A restart is needed only if an old copy is already in memory, or pip moved numpy/torch under us.
-    _stale = [m for m in _NEEDED if m in sys.modules]
-    for _name, _was in _loaded.items():
-        try:
-            if _was and importlib.metadata.version(_name) != _was:
-                _stale.append(f"{_name} {_was}")
-        except importlib.metadata.PackageNotFoundError:
-            pass
-    if _stale:
-        _halt(f"installed. {', '.join(_stale)} was already loaded in this kernel: RESTART THE KERNEL, then run "
-              "this cell again. (A background run that is already training is not affected.)", kind="warn")
-
-if HF_TOKEN:
-    os.environ["HF_TOKEN"] = HF_TOKEN
-# Every checkpoint is also copied here, so losing or damaging the data folder does not lose the run.
-os.environ["NATUREV1_BACKUP_DIR"] = (os.path.expanduser("~/naturev1_backup") if BACKUP_DIR is None
-                                     else os.path.expanduser(BACKUP_DIR))
-
-if BACKGROUND and not os.environ.get("NATUREV1_BACKGROUND_CHILD"):
-    # Hand this same pipeline, with these settings, to a supervised process on this machine, and stop
-    # here: the notebook only starts and watches it. The GPU is never touched from the notebook.
-    # Imported under a private name: marimo lets a name be defined by only one cell, and this way any
-    # other cell can still `import naturev1` to call naturev1.follow() or naturev1.stop().
-    import naturev1 as _naturev1
-
-    _SETTINGS = {name: globals()[name] for name in (
-        "RUN_PRETRAIN", "RUN_ROLLOUT", "RUN_STORMS", "RETRAIN_STORMS", "RUN_SATELLITE", "RETRAIN_SATELLITE",
-        "RUN_SCORE", "RUN_HINDCAST", "RUN_PUBLISH",
-        "RUN_FORECAST", "RUN_WATCHER", "STAGE_YEARS", "VAL_YEARS", "EPOCHS", "BATCH", "MAX_BATCH", "WORKERS",
-        "ROLLOUT_STEPS", "ROLLOUT_TRAIN", "MEMBERS", "STORM_FIRST_SEASON", "HINDCAST", "STORM", "CITY",
-        "HF_REPO", "HF_TOKEN", "DATA_DIR", "BACKUP_DIR", "MIRROR")}
-    _was_running = _naturev1.status(DATA_DIR) is not None
-    _naturev1.launch(directory=DATA_DIR, stall_minutes=STALL_MINUTES, **_SETTINGS)
-    if _was_running:
-        _naturev1.progress(DATA_DIR)                 # what the run that is already going has done so far
-    # A fresh run: wait for its first lines. Then show the log live for a while, so the cell ends with
-    # the run visibly moving rather than with a snapshot that looks frozen.
-    _naturev1.follow(lines=25, directory=DATA_DIR, wait=90, watch=WATCH_SECONDS)
-    if _naturev1.status(DATA_DIR) is None:
-        _naturev1.progress(DATA_DIR)
-        _halt("The run has ended -- the last lines above say whether it finished or stopped. If it finished, "
-              "the scorecards and the hindcast are above. If it stopped, run this cell again: it continues "
-              "from the last checkpoint, pulling data, checkpoints and banks back from the Hub mirror if this "
-              "machine's disk was wiped.", kind="success")
-    _halt("NatureV1 is running in the background; this cell was its window and has closed -- the run has "
-          "NOT stopped. Nothing in this notebook can stop it except naturev1.stop().\n"
-          "To reopen the window: run this cell again (it will not start a second run), or in any cell\n"
-          "    import naturev1; naturev1.follow(watch=None)\n"
-          "If the run ever does stop, run this cell again: it continues from the last checkpoint, pulling "
-          "data, checkpoints and banks back from the Hub mirror if this machine's disk was wiped.\n"
-          "naturev1.progress() shows each stage's checkpoint, its age, and its backup.",
-          kind="success")
-
-# ═══ 1 ═══ imports, paths, hardware ════════════════════════════════════════════════════════════════
-import datetime as dt
-import json
-
-import numpy as np
-import torch
-from ihelix import FieldGrid, Geometry, fibonacci_sphere
-from naturev1 import (HEADLINE_STATE_FIELDS, CachedERA5, CheckpointManager, ERA5Window, HubMirror, NatureConfig,
-                      NatureV1, RolloutSchedule, StateStepper, Trainer, TrainSettings, autotune_batch_size,
-                      benchmark_steps, build_climatology, build_forecast, calendar_features, catalogue,
-                      channel_loss_weights, check_forecast, check_grid_alignment, check_normalization,
-                      check_weights, corpus_scale, describe_environment, device_report, era5_loader,
-                      era5_source_grid, era5_splits, expand_variables, extrapolation_track, fetch_latest,
-                      format_pairing, format_plan, format_preflight, lead_offsets, masked_gaussian_nll,
-                      materialise, normalize_channels, open_weatherbench_levels, pair_tracks_with_reanalysis,
-                      parse_hurdat2, preflight, push_to_hub, rapid_intensification, resolve_all,
-                      responds_to_input, scene_from_netcdf, score_model, score_state, scoring_fields,
-                      split_by_storm, spread_skill_ratio, state_forecast, steering_track, storm_environment,
-                      storm_feature_bank, storm_scorecard, storm_state_vector, train_state_rollout,
-                      train_storm_heads, training_plan, upper_air_report, watch)
-from naturev1.besttrack import download
-from naturev1.checkpoint import TrainingState
-from naturev1.era5 import _target_index
-from naturev1.storms import calibration_report, fit_feature_monitor, fit_probability_calibration
-from naturev1.stormsat import (IBTRACS_NA_URL, GridSatArchive, HursatArchive, describe_patch, encode_bt,
-                               ibtracs_atcf_map, satellite_bank)
-from naturev1.safeio import atomic_write_text, read_json
-
-DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
-COLAB_DRIVE = "/content/drive/MyDrive"
-DATA_DIR = DATA_DIR or ("/content" if os.path.isdir("/content") else os.path.expanduser("~/naturev1_data"))
-CKPT_DIR = (f"{COLAB_DRIVE}/naturev1_ckpt" if os.path.isdir(COLAB_DRIVE)       # Drive outlives the VM
-            else os.path.join(DATA_DIR, "naturev1_ckpt"))
-os.makedirs(DATA_DIR, exist_ok=True)
-os.makedirs(CKPT_DIR, exist_ok=True)
-CACHE, VAL_CACHE, STATS = (os.path.join(DATA_DIR, name) for name in ("era5.npy", "era5_val.npy", "stats.json"))
-# Everything expensive goes to the Hub as soon as it exists and comes back at the start of a new session,
-# so a wiped disk costs minutes, not hours. Off without a repo or token; see the header.
-mirror = HubMirror(HF_REPO if MIRROR else None, token=HF_TOKEN or None)
-
-
-def banner(text):
-    print(f"\n{'═' * 99}\n  {text}\n{'═' * 99}")
-
-
-banner("HARDWARE")
-print(device_report())
-print(f"data {DATA_DIR} | checkpoints {CKPT_DIR}\n{mirror.describe()}")
-
-# ═══ 2 ═══ data: 13 pressure levels + surface + static, resolved against this machine ══════════════
-banner("DATA — ERA5 (WeatherBench 2), surface and 13 pressure levels")
-ERA5, SURFACE, UPPER = open_weatherbench_levels()
-LEVELS = [int(x) for x in ERA5.level.values]
-SRC, LAT, LON = era5_source_grid(ERA5)
-plan = resolve_all(ERA5, tuple(SURFACE) + tuple(UPPER), LEVELS, STAGE_YEARS + VAL_YEARS, SRC.num_points,
-                   layers=17, batch=MAX_BATCH, precision="bf16", path=DATA_DIR,
-                   staged=(CACHE, VAL_CACHE))      # data already on disk counts as room, not as used
-print(plan.summary())
-R = plan.resolved
-CHANNELS = expand_variables(ERA5, R["variables"], R["levels"])
-WIDTH = len(CHANNELS) + 7                         # room for observation-mask channels, zero-padded
-print(f"\n{upper_air_report(SURFACE, UPPER, LEVELS)}")
-assert not check_weights(SRC), check_weights(SRC)  # poles present, not deleted by cos(latitude)
-
-OFFSETS, SPLITS = lead_offsets((6, 12, 18, 24, 36, 48, 72, 96, 120)), era5_splits(ERA5)
-TRAIN_STEPS = max(R["years"] - VAL_YEARS, 1) * 1460
-VAL_STEPS = VAL_YEARS * 1460
-common = dict(history=6, lead_steps=OFFSETS, variables=tuple(R["variables"]), levels=R["levels"], channels=WIDTH)
-for name, index in SPLITS.items():
-    print(f"  {name:5} {str(ERA5.time.values[index[0]])[:10]} -> {str(ERA5.time.values[index[-1]])[:10]}")
-print("split by TIME: weather is autocorrelated for days, so a random split leaks the answer.")
-
-mirror.pull(STATS, "staging/stats.json")             # the normalisation statistics, from an earlier session
-stream = ERA5Window(ERA5, indices=SPLITS["train"], stats_cache=STATS, **common)
-mirror.push(STATS, "staging/stats.json")
-print(f"\n{stream.normalizer.report()}")
-print(f"\n{corpus_scale(ERA5, tuple(R['variables']))}\n\n{catalogue()}")
-
-if R["streaming"]:
-    print("\nnot enough disk to stage: streaming from the network (~100x slower per window)")
-    train_ds, roll_ds = stream, ERA5Window(ERA5, indices=SPLITS["train"], stats_cache=STATS,
-                                           state_steps=ROLLOUT_STEPS, **common)
-    val_ds = ERA5Window(ERA5, indices=SPLITS["val"], augment=False, stats_cache=STATS,
-                        state_steps=ROLLOUT_STEPS, **common)
-else:
-    # Always called, and never downloads twice: it returns at once when what is on disk already covers
-    # the request, copies from disk what it can when the request grows, and resumes a download that died.
-    TRAIN_SPAN, VAL_SPAN = SPLITS["train"][-TRAIN_STEPS:], SPLITS["val"][:VAL_STEPS]
-    # A staging an earlier session already made comes back from the Hub in minutes; it is pushed there,
-    # in the background, the first time it is complete. Then materialise() reuses, grows or resumes it.
-    mirror.pull_staging(CACHE, "staging/era5", CHANNELS, TRAIN_SPAN)
-    mirror.pull_staging(VAL_CACHE, "staging/era5_val", CHANNELS, VAL_SPAN)
-    materialise(ERA5, TRAIN_SPAN, CACHE, variables=tuple(R["variables"]),
-                levels=R["levels"], normalizer=stream.normalizer, workers=8)
-    materialise(ERA5, VAL_SPAN, VAL_CACHE, variables=tuple(R["variables"]),
-                levels=R["levels"], normalizer=stream.normalizer, workers=8)
-    mirror.push_staging(CACHE, "staging/era5")
-    mirror.push_staging(VAL_CACHE, "staging/era5_val")
-    train_ds = CachedERA5(CACHE, history=6, lead_steps=OFFSETS, channels=WIDTH, augment=True,
-                          restrict_to=TRAIN_SPAN)
-    roll_ds = CachedERA5(CACHE, history=6, lead_steps=OFFSETS, channels=WIDTH, augment=True,
-                         state_steps=ROLLOUT_STEPS, restrict_to=TRAIN_SPAN)
-    val_ds = CachedERA5(VAL_CACHE, history=6, lead_steps=OFFSETS, channels=WIDTH, augment=False,
-                        state_steps=ROLLOUT_STEPS, restrict_to=VAL_SPAN)
-print(f"\ntrain {len(train_ds):,} windows | validate on {len(val_ds):,} held-out windows")
-
-sample = train_ds[0]["analysis"]
-for problem in (check_grid_alignment(SRC, sample[-1, :, train_ds.variables.index("2m_temperature")])
-                + check_normalization(sample, "analysis")):
-    _halt(f"DATA PROBLEM: {problem}")
-print("data ok: samples land where the grid says, no spike channels")
-
-# ═══ 3 ═══ what each channel IS — decides what a rollout does with it ══════════════════════════════
-stepper = StateStepper.build(roll_ds, input_channels=WIDTH, grid=SRC, samples=64)
-print(f"\nchannel roles:\n{stepper.roles.describe()}")
-WEIGHTS = channel_loss_weights(train_ds.variables, WIDTH)
-
-# ═══ 4 ═══ the model ═══════════════════════════════════════════════════════════════════════════════
-banner("MODEL")
-CFG = NatureConfig(
-    analysis_channels=WIDTH, satellite_channels=6, environment_channels=8,
-    hidden_size=512, num_layers=17, num_heads=8, num_kv_heads=4, head_dim=64, intermediate_size=2048,
-    latent_points=4096, min_radius_km=120.0, max_radius_km=1600.0, history_frames=6,
-    lead_times_hours=(6, 12, 18, 24, 36, 48, 72, 96, 120), track_modes=6,
-    state_channels=stepper.roles.num_prognostic,        # predict and evolve the whole atmosphere
-    noise_dim=32 if MEMBERS > 1 else 0)                 # per-member noise for the CRPS ensemble
-model = NatureV1(CFG, fibonacci_sphere(CFG.latent_points, num_neighbours=CFG.latent_neighbours,
-                                       cluster_size=CFG.latent_cluster)).to(DEVICE)
-model.gradient_checkpointing_enable(True)
-stepper.grid = SRC.to(DEVICE)
-print(f"NatureV1 {model.num_parameters()/1e6:.2f}M parameters on {DEVICE}; state head over "
-      f"{CFG.state_channels} channels; {MEMBERS}-member ensemble")
-print(format_preflight(preflight(model=model, dataset=train_ds, grid=SRC, strict=True)))
-
-
-def restore(*stages):
-    """Load the newest checkpoint of the first stage that has one -- locally, else from the Hub."""
-    for stage in stages:
-        manager = CheckpointManager(f"{CKPT_DIR}/{stage}", repo_id=HF_REPO)
-        manager.fetch_from_hub()
-        if manager.load(model, map_location=DEVICE) is not None:
-            return stage
-    return None
-
-
-# ═══ 5 ═══ the largest batch that fits, and what the run costs ═════════════════════════════════════
-banner("BENCHMARK — largest batch that fits, and what the run costs")
-
-
-def make_step(batch_size):
-    items = [train_ds[i] for i in range(batch_size)]
-    batch = {k: torch.stack([x[k] for x in items]).to(DEVICE) for k in ("analysis", "calendar", "field_target", "field_mask")}
-
-    def step():
-        with torch.autocast(DEVICE, dtype=torch.bfloat16, enabled=DEVICE == "cuda"):
-            out = model(analysis=batch["analysis"], analysis_grid=SRC, calendar=batch["calendar"], output_grid=SRC)
-            loss = masked_gaussian_nll(out["field_mean"], out["field_log_var"],
-                                       torch.where(batch["field_mask"] > 0, batch["field_target"], torch.nan))
-        loss.backward()
-        model.zero_grad(set_to_none=True)
-    return step
-
-
-# The search is done once and remembered: repeating it on every restart costs minutes, pushes the card
-# to the edge of its memory each time, and could pick a different batch -- a different run -- each time.
-BATCH_FILE = os.path.join(CKPT_DIR, "batch.json")
-mirror.pull(BATCH_FILE, "staging/batch.json")
-REMEMBERED = read_json(BATCH_FILE, default={}) if BATCH is None else {}   # a damaged file is searched again
-if REMEMBERED.get("batch"):
-    BATCH, SPEED = int(REMEMBERED["batch"]), float(REMEMBERED.get("samples_per_second", 0.0))
-    print(f"batch {BATCH}, found on an earlier run (delete {BATCH_FILE} to search again)")
-else:
-    if BATCH is None:
-        BATCH = min(autotune_batch_size(make_step, start=1, target_fraction=0.85), MAX_BATCH)
-    MARK = benchmark_steps(make_step(BATCH), BATCH, warmup=1, iterations=10, gradient_checkpointing=True)
-    SPEED = MARK.samples_per_second
-    atomic_write_text(BATCH_FILE, json.dumps({"batch": BATCH, "samples_per_second": SPEED}))
-    mirror.push(BATCH_FILE, "staging/batch.json")
-    print(f"batch {BATCH} | {MARK}")
-if SPEED:
-    print(format_plan(training_plan(SPEED, corpus_samples=len(train_ds), epochs=EPOCHS,
-                                    watts=600.0, electricity_per_kwh=0.15, cloud_per_hour=2.50)))
-if DEVICE == "cuda":
-    torch.cuda.empty_cache()                      # hand back what the search held before training starts
-loader = era5_loader(train_ds, batch_size=BATCH, num_workers=WORKERS, analysis_grid=SRC, output_grid=SRC,
-                     prefetch_factor=2)
-val_loader = era5_loader(val_ds, batch_size=BATCH, num_workers=WORKERS, shuffle=False, analysis_grid=SRC,
-                         output_grid=SRC, prefetch_factor=2)
-
-# ═══ 6 ═══ stage one — every channel, every lead ═══════════════════════════════════════════════════
-if RUN_PRETRAIN:
-    banner("STAGE ONE — pretraining on reanalysis")
-    trainer = Trainer(model, TrainSettings(
-        stage="pretrain", learning_rate=3e-4, warmup_steps=1000,
-        precision=R["precision"], max_steps=int(len(train_ds) * EPOCHS / BATCH),
-        checkpoint_dir=f"{CKPT_DIR}/stage1", checkpoint_seconds=60, hub_repo=HF_REPO, hub_push_seconds=600,
-        ema_decay=0.0, log_every=5, val_every=500, val_batches=32), device=DEVICE)
-    trainer.resume()
-    trainer.fit(loader, epochs=EPOCHS, val_loader=val_loader)
-    if trainer.interrupted:
-        # Stopped part-way: checkpointed, and the next stage must not start from a half-trained model.
-        _halt("stage one stopped and checkpointed -- run again to resume it where it left off", kind="warn")
-    print("held-out falling = learning; held-out rising while training falls = memorising.")
-
-# ═══ 7 ═══ stage 1b — the whole atmosphere, rolled forward on its own forecasts ════════════════════
-if RUN_ROLLOUT:
-    banner(f"ROLLOUT — {ROLLOUT_STEPS}-step full-state training, {MEMBERS}-member CRPS ensemble")
-    if not RUN_PRETRAIN and restore("stage1") is None:
-        print("!! no stage-one checkpoint: rolling out an untrained backbone. Set RUN_PRETRAIN = True.")
-    steps = ROLLOUT_TRAIN
-    roll_loader = era5_loader(roll_ds, batch_size=max(BATCH // 2, 1), num_workers=WORKERS,
-                              analysis_grid=SRC, output_grid=SRC, prefetch_factor=2)
-    train_state_rollout(
-        model, roll_loader, stepper, max_steps=steps,
-        schedule=RolloutSchedule(start_step=max(steps // 10, 1), ramp_steps=max(steps // 2, 1),
-                                 max_steps=ROLLOUT_STEPS),
-        channel_weights=WEIGHTS, members=MEMBERS, precision=R["precision"],
-        checkpoint_dir=f"{CKPT_DIR}/rollout", hub_repo=HF_REPO, log_every=25)
-
-# ═══ 8 ═══ stage two — hurricane heads, on the frozen backbone ═════════════════════════════════════
-banner("STAGE TWO — HURDAT2 best tracks")
-tracks = parse_hurdat2(download("https://www.nhc.noaa.gov/data/hurdat/hurdat2-1851-2024-040425.txt",
-                                os.path.join(DATA_DIR, "hurdat2.txt")))
-print(f"HURDAT2: {len(tracks):,} storms, {sum(len(t) for t in tracks):,} points, "
-      f"{sum(int(t.landfall.sum()) for t in tracks):,} landfalls")
-walk = rapid_intensification(tracks, threshold_kt=30.0)
-print(f"rapid intensification: {walk['positives']:,} of {walk['eligible']:,} eligible = "
-      f"{100 * walk['base_rate']:.2f}%  (an always-'no' classifier scores {100 - 100 * walk['base_rate']:.0f}%)")
-GROUPS = split_by_storm([t for t in tracks if t.year >= STORM_FIRST_SEASON])
-STORE_TIMES = ERA5.time.values.astype("datetime64[s]").astype(np.int64)
-
-
-def paired(which):
-    starts, targets, report = pair_tracks_with_reanalysis(GROUPS[which], STORE_TIMES, OFFSETS, history=6)
-    return starts, targets, report
-
-
-def storm_banks():
-    """The frozen backbone's features for every storm sample: built once, cached, mirrored."""
-    (tr_starts, tr_targets, tr_report), (va_starts, va_targets, va_report) = paired("train"), paired("validation")
-    print(f"\n{format_pairing(tr_report)}")
-    print(f"validation: {va_report['paired']:,} samples from {va_report['storms']} unseen storms "
-          f"(seasons 2017/2019/2021)")
-    print("\nreading each storm's reanalysis once and running the frozen backbone over it "
-          "(cached; resumes if interrupted):")
-    for _name in ("storm_bank_train", "storm_bank_val"):
-        mirror.pull(f"{CKPT_DIR}/{_name}.pt", f"checkpoints/{_name}.pt")   # rebuilt anyway if the backbone changed
-    train = storm_feature_bank(model, ERA5, stream, tr_starts, tr_targets, SRC,
-                               cache=f"{CKPT_DIR}/storm_bank_train.pt", precision=R["precision"])
-    val = storm_feature_bank(model, ERA5, stream, va_starts, va_targets, SRC,
-                             cache=f"{CKPT_DIR}/storm_bank_val.pt", precision=R["precision"])
-    for _name in ("storm_bank_train", "storm_bank_val"):
-        mirror.push(f"{CKPT_DIR}/{_name}.pt", f"checkpoints/{_name}.pt")
-    return train, val, tr_targets, va_targets
-
-
-bank_train = bank_val = None
-if RUN_STORMS:
-    # A finished stage two is loaded *before* the banks are built: its backbone is the one they were
-    # built with, so they are reused rather than rebuilt from whatever checkpoint the Hub has for 1b.
-    resumed = None if RETRAIN_STORMS else restore("stage2")
-    if resumed is None and not (RUN_PRETRAIN or RUN_ROLLOUT) and restore("rollout", "stage1") is None:
-        _halt("no pretrained backbone found. Freezing an untrained one would fine-tune the storm "
-              "heads on noise -- set RUN_PRETRAIN = True.")
-    bank_train, bank_val, tr_targets, va_targets = storm_banks()
-    if resumed is not None:
-        print("\nstage two is already trained: its checkpoint is loaded (RETRAIN_STORMS = True trains it again)")
-    else:
-        history = train_storm_heads(model, bank_train, bank_val, epochs=300,
-                                    patience=25, checkpoint_dir=f"{CKPT_DIR}/stage2", hub_repo=HF_REPO)
-        best = min(history, key=lambda h: h["val"])
-        banner("SCOREBOARD — is it generalising, or memorising?")
-        print(f"best epoch {best['epoch']}: held-out {best['val']:.4f}  training {best['train']:.4f}  "
-              f"gap {best['val'] - best['train']:+.4f}   (a large positive gap = memorised the training storms)")
-    print(f"\nheld-out storms, seasons never trained on:\n{storm_scorecard(model, bank_val, CFG.lead_times_hours)}")
-
-# ═══ 8b ═══ stage three — what the satellite sees ══════════════════════════════════════════════════
-if RUN_SATELLITE:
-    banner("STAGE THREE — storm-centred infrared (HURSAT-B1 to 2016, GridSat-B1 after)")
-    loaded = None if RETRAIN_SATELLITE else restore("stage3")
-    if loaded is None and not RUN_STORMS and restore("stage2") is None:
-        _halt("no trained hurricane heads to build on -- run with RUN_STORMS = True first")
-    if bank_train is None:
-        bank_train, bank_val, tr_targets, va_targets = storm_banks()
-    print("\nstorm-centred infrared for every sample, now and six hours earlier (cached; mirrored):")
-    hursat = HursatArchive(os.path.join(DATA_DIR, "hursat"),
-                           ibtracs_atcf_map(download(IBTRACS_NA_URL, os.path.join(DATA_DIR, "ibtracs.NA.csv"))))
-    gridsat = GridSatArchive()
-    for _name in ("satellite_bank_train", "satellite_bank_val"):
-        mirror.pull(f"{CKPT_DIR}/{_name}.pt", f"checkpoints/{_name}.pt")
-    sat_train = satellite_bank(tr_targets, f"{CKPT_DIR}/satellite_bank_train.pt", hursat, gridsat)
-    sat_val = satellite_bank(va_targets, f"{CKPT_DIR}/satellite_bank_val.pt", hursat, gridsat)
-    for _name in ("satellite_bank_train", "satellite_bank_val"):
-        mirror.push(f"{CKPT_DIR}/{_name}.pt", f"checkpoints/{_name}.pt")
-    shutil.rmtree(os.path.join(DATA_DIR, "hursat"), ignore_errors=True)    # the patches are kept; the archives are not
-    plain_val = dict(bank_val)
-    bank_train["satellite"], bank_val["satellite"] = sat_train, sat_val
-    coverage = float(sat_val["available"][:, 0].float().mean())
-    # The model as it arrives -- stage two, no satellite -- scored first: that is what stage three must beat.
-    before = None if loaded is not None else storm_scorecard(model, plain_val, CFG.lead_times_hours)
-    if loaded is not None:
-        print("\nstage three is already trained: its checkpoint is loaded (RETRAIN_SATELLITE = True trains it again)")
-    elif coverage < 0.3:
-        print(f"\nonly {coverage:.0%} of held-out samples have an image: too few to judge the satellite branch, "
-              "so it is not trained. Calibration and the input monitor still are.")
-    else:
-        history = train_storm_heads(model, bank_train, bank_val, epochs=80, batch_size=128, learning_rate=2e-4,
-                                    satellite_learning_rate=1e-3, augment=True, keep_if_no_better=True,
-                                    patience=15, log_every=5)
-    banner("CALIBRATION, INPUT MONITOR, ROLLOUT STATISTICS")
-    print("probabilities on held-out seasons, each season calibrated without itself:\n"
-          + calibration_report(model, bank_val))
-    fit_probability_calibration(model, bank_val)
-    print(f"\ninput monitor fitted on the training storms: limit {fit_feature_monitor(model, bank_train):.2f}")
-    model.state_tendency.copy_(stepper.tendency.to(model.state_tendency.device))
-    _stage3 = CheckpointManager(f"{CKPT_DIR}/stage3", repo_id=HF_REPO)
-    _stage3.save(model, None, state=TrainingState(step=int(model.trained_heads()["storm_satellite"])),
-                 config=model.config.to_dict(), force=True)
-    _stage3.push_now(TrainingState(step=int(model.trained_heads()["storm_satellite"])))
-    banner("SCOREBOARD — what the satellite adds, on held-out storms")
-    if before is not None:
-        print(f"stage two, before the satellite (the score to beat):\n{before}")
-    else:
-        print(f"stage three with the images withheld:\n{storm_scorecard(model, plain_val, CFG.lead_times_hours)}")
-    print(f"\nstage three, with the satellite ({coverage:.0%} of held-out samples have an image):\n"
-          f"{storm_scorecard(model, bank_val, CFG.lead_times_hours)}")
-
-# ═══ 9 ═══ did it learn? scorecards against persistence and climatology ════════════════════════════
-if not (RUN_PRETRAIN or RUN_ROLLOUT or RUN_STORMS or RUN_SATELLITE):
-    print(f"loaded: {restore('stage3', 'stage2', 'rollout', 'stage1') or 'nothing -- untrained'}")
-print(f"\ntraining record (steps per output; 0 = never trained, never shown as a forecast):\n"
-      f"  {model.trained_heads()}")
-
-_probe_stream = iter(val_loader)
-
-
-def _probe():
-    batch = next(_probe_stream)
-    return {"analysis": batch["analysis"].to(DEVICE), "calendar": batch["calendar"].to(DEVICE)}
-
-
-responds, spread = responds_to_input(model, _probe, SRC)
-print(f"\nresponds to the weather: {responds}  (spread {spread:.2e})")
-
-card = state_card = None
-if RUN_SCORE:
-    banner("SCORECARDS — area-weighted, physical units, identical batches for every baseline")
-    climo = build_climatology(train_ds, np.arange(len(train_ds)), WIDTH, SRC.num_points,
-                              samples=200)
-    batches = 32
-    card = score_model(model, val_loader, SRC, LAT, len(LON), CFG.lead_times_hours,
-                       fields=scoring_fields(train_ds.variables, _target_index(train_ds.variables)),
-                       normalizer=train_ds.normalizer, climatology=climo, max_batches=batches, device=DEVICE)
-    print("surface heads, direct multi-lead:\n" + card.table() + "\n" + card.verdict())
-    state_card = score_state(model, val_loader, stepper, HEADLINE_STATE_FIELDS,
-                             steps=ROLLOUT_STEPS, climatology=climo,
-                             max_batches=batches, precision=R["precision"])
-    print("\nfull-state rollout (Z500 in m2/s2, as WeatherBench 2 reports it):\n"
-          + state_card.table() + "\n" + state_card.verdict())
-    if MEMBERS > 1 and "geopotential@500" in train_ds.variables:
-        batch = {k: (v.to(DEVICE) if torch.is_tensor(v) else v) for k, v in next(iter(val_loader)).items()}
-        lead = min(4, batch["state_target"].shape[1])
-        ensemble = state_forecast(model, batch, stepper, steps=lead, members=max(MEMBERS, 4),
-                                  precision=R["precision"])
-        z500 = train_ds.variables.index("geopotential@500")
-        ratio = spread_skill_ratio(ensemble[:, -1, ..., z500], batch["state_target"][:, lead - 1, :, z500])
-        print(f"\nZ500 +{6 * lead}h ensemble spread/skill {ratio:.2f}   (1.0 calibrated, <1 overconfident)")
-        if ratio < 0.05:
-            print("  no spread yet: the noise path starts at exactly zero and CRPS training grows it.")
-
-# ═══ 10 ═══ hindcast — a held-out hurricane, from its real analysis ════════════════════════════════
-if RUN_HINDCAST:
-    banner(f"HINDCAST — {HINDCAST[0].title()} {HINDCAST[1]}, a season the model never trained on")
-    storm = next((t for t in tracks if t.name.strip().upper() == HINDCAST[0] and t.year == HINDCAST[1]), None)
-    starts, targets, _ = (pair_tracks_with_reanalysis([storm], STORE_TIMES, OFFSETS, history=6)
-                          if storm is not None else ([], [], None))
-    if not len(starts):
-        print("that storm is not in the reanalysis window (1959-2021); pick another in HINDCAST")
-    else:
-        peak = int(np.nanargmax(storm.max_wind_kt))
-        choice = min(range(len(targets)), key=lambda i: abs(targets[i].point - max(peak - 8, 0)))   # ~48 h before peak
-        target = targets[choice].build()
-        window = ERA5Window(ERA5, indices=starts[choice:choice + 1], augment=False, stats_cache=STATS, **common)[0]
-        issued = dt.datetime.fromtimestamp(float(window["valid_time"]), tz=dt.timezone.utc)
-        centre = target["storm_center"].tolist()
-        here = target["storm_center"][None].to(DEVICE)
-        # The storm's environment and the physics-only steering track, from the analysis "now".
-        now = window["analysis"][-1][None].to(DEVICE)
-        environment = storm_environment(now, train_ds.variables, train_ds.normalizer, SRC, here)
-        steer = steering_track(now, train_ds.variables, train_ds.normalizer, SRC, here, CFG.lead_times_hours)
-        print(describe_environment(environment[0]))
-        # The satellite view at issue time and six hours earlier, if stage three has trained that branch.
-        seen = None
-        if model.trained_heads()["storm_satellite"] > 0:
-            from naturev1.stormsat import _earlier_position
-            earlier = _earlier_position(targets[choice])
-            when = np.datetime64(issued.replace(tzinfo=None), "m")
-            wanted = [(when, tuple(centre))] + ([earlier] if earlier is not None else [])
-            images = GridSatArchive().patches(wanted, progress=False)
-            if images[0] is not None:
-                codes = np.zeros((1, 2, *images[0].shape), np.uint8)
-                codes[0, 0] = encode_bt(images[0])
-                if len(images) > 1 and images[1] is not None:
-                    codes[0, 1] = encode_bt(images[1])
-                seen = (torch.from_numpy(codes).to(DEVICE),
-                        torch.tensor([[True, len(images) > 1 and images[1] is not None]], device=DEVICE))
-                print("satellite (GridSat-B1): " + describe_patch(images[0]))
-        with torch.no_grad(), torch.autocast(DEVICE, dtype=torch.bfloat16, enabled=DEVICE == "cuda"):
-            out = model.eval()(analysis=window["analysis"][None].to(DEVICE), analysis_grid=SRC,
-                               calendar=window["calendar"][None].to(DEVICE), output_grid=SRC,
-                               storm_center=here, storm_state=target["storm_state"][None].to(DEVICE),
-                               storm_environment=environment,
-                               track_prior=steer if model.uses_track_prior() else None,
-                               storm_satellite=seen)
-        out = {k: v.float().cpu() for k, v in out.items()}
-        out.setdefault("track_prior", steer.float().cpu())
-        # A second physics member: the storm carried by the atmosphere the model *forecasts*, step by
-        # step, rather than by today's flow held steady. Only once the state head has been trained.
-        rolled = None
-        if model.trained_heads()["state"] > 0:
-            with torch.no_grad():
-                future = state_forecast(model, {"analysis": window["analysis"][None].to(DEVICE),
-                                                "calendar": window["calendar"][None].to(DEVICE),
-                                                "valid_time": window["valid_time"].view(1)},
-                                        stepper, steps=ROLLOUT_STEPS, precision=R["precision"])[0]
-            rolled = steering_track(torch.cat([now[None], future.to(DEVICE)]), train_ds.variables,
-                                    train_ds.normalizer, SRC, here, CFG.lead_times_hours).float().cpu()
-        fc = build_forecast(out, CFG.lead_times_hours, issued, storm_center=centre,
-                            normalizer=train_ds.normalizer, trained=model.trained_heads(), inputs=("analysis",),
-                            consensus={"weights": model.track_consensus.cpu(), "storm_state": target["storm_state"]})
-        print(f"issued {issued:%Y-%m-%d %H:%M}Z at {centre[0]:.1f}N {-centre[1]:.1f}W, "
-              f"{float(target['current_wind_kt']):.0f} kt now")
-
-        def km_off(d_lat, d_lon, lead):
-            lat = centre[0] + float(target["track_target"][lead, 0])
-            lon = centre[1] + float(target["track_target"][lead, 1])
-            return 111.2 * np.hypot(centre[0] + float(d_lat) - lat,
-                                    (centre[1] + float(d_lon) - lon) * np.cos(np.radians(lat)))
-
-        members = {"steering": steer[0].cpu(), "extrap.": extrapolation_track(target["storm_state"][None],
-                                                                              CFG.lead_times_hours)[0]}
-        if rolled is not None:
-            members["rollout-steer"] = rolled[0]
-        if isinstance(fc["track_scenarios"], list):
-            top = fc["track_scenarios"][0]
-            members = {f"model ({top['probability']:.0%})": torch.tensor(
-                [[p["latitude"] - centre[0], p["longitude"] - centre[1]] for p in top["track"]]), **members}
-        if "track_consensus" in fc:
-            members["consensus"] = torch.tensor([[p["latitude"] - centre[0], p["longitude"] - centre[1]]
-                                                 for p in fc["track_consensus"]["track"]])
-        print("track error vs what happened, km, by member -- the physics members need no training:")
-        print("  " + f"{'lead':>6}" + "".join(f"{name:>16}" for name in members) + f"{'wind fcst/actual':>20}")
-        for lead, hours in enumerate(CFG.lead_times_hours):
-            if target["track_valid"][lead] > 0:
-                row = "".join(f"{km_off(*member[lead], lead):>13.0f} km" for member in members.values())
-                wind = ""
-                if isinstance(fc["intensity"], list):
-                    wind = f"{fc['intensity'][lead]['max_wind_ms'] * 1.94384:5.0f}"
-                    if target["intensity_mask"][lead, 0] > 0:
-                        wind += f" / {float(target['intensity_target'][lead, 0]) * 1.94384:3.0f} kt"
-                print(f"  +{hours:4d}h {row}{wind:>20}")
-        if not isinstance(fc["track_scenarios"], list):
-            print("track head untrained -- run RUN_STORMS first; the physics members above still stand")
-        problems = check_forecast(fc)
-        print("forecast checks: " + ("pass" if not problems else "; ".join(problems)))
-
-# ═══ 11 ═══ publish only if it earned it ═══════════════════════════════════════════════════════════
-if RUN_PUBLISH:
-    cards = [c for c in (state_card, card) if c is not None]
-    beats = [s for c in cards for s in c.scores if s.beats_persistence]
-    if not cards:
-        print("\nnot publishing: nothing was scored (set RUN_SCORE = True).")
-    elif not responds:
-        print("\nnot publishing: the model gives the same answer whatever weather it is shown.")
-    elif not beats:
-        print("\nnot publishing: it loses to persistence at every field and lead.")
-    else:
-        url = push_to_hub(model, HF_REPO, normalizer=train_ds.normalizer, scorecard=cards[0], name="NatureV1",
-                          author="Nathan", token=HF_TOKEN or None,
-                          training_data=f"ERA5 (WeatherBench 2), {len(CHANNELS)} channels, {R['years']} years; "
-                                        f"full-state {ROLLOUT_STEPS}-step rollout, {MEMBERS}-member CRPS; "
-                                        f"HURDAT2 {STORM_FIRST_SEASON}+ for the storm heads.")
-        print(f"\npublished: {url}  (beats persistence on {len(beats)} field-lead pairs)")
-
-# ═══ 12 ═══ live forecast from GOES — only once that input path is trained ═════════════════════════
-def load_scene(paths, center, half_width_deg=9.0, stride=4):
-    """Geolocated samples plus true pixel footprints, cropped to a real box on the planet."""
-    scene = scene_from_netcdf({c: str(p) for c, p in paths.items()}, stride=stride,
-                              bounds=(center[0] - half_width_deg, center[0] + half_width_deg,
-                                      center[1] - half_width_deg, center[1] + half_width_deg))
-    coords = torch.tensor(np.stack([np.radians(scene.latitude), np.radians(scene.longitude) % (2 * np.pi)], -1),
-                          dtype=torch.float64)
-    grid = FieldGrid.from_points(coords, Geometry.globe(), num_neighbours=16, cluster_size=64,
-                                 weights=torch.tensor(scene.area_km2, dtype=torch.float64))
-    values = torch.tensor(normalize_channels(scene.values, scene.channels), dtype=torch.float32)
-    if CFG.satellite_channels > values.shape[-1]:
-        values = torch.cat([values, torch.zeros(values.shape[0], CFG.satellite_channels - values.shape[-1])], -1)
-    return grid, values, scene
-
-
-@torch.no_grad()
-def forecast_now(storm=STORM, city=CITY):
-    paths = fetch_latest(os.path.join(DATA_DIR, "goes"), ("C13", "C09"), satellite="east", product="conus")
-    grid, values, scene = load_scene(paths, storm)
-    print(scene)
-    frames = CFG.history_frames
-    out_grid = fibonacci_sphere(2000, num_neighbours=16, cluster_size=50)
-    out = model.eval()(satellite=values[None, None].expand(1, frames, -1, -1).contiguous().to(DEVICE),
-                       satellite_grid=grid, output_grid=out_grid, neighbours=12,
-                       calendar=calendar_features(torch.full((1, frames), scene.timestamp.timestamp())).to(DEVICE),
-                       storm_center=torch.tensor([storm], dtype=torch.float32, device=DEVICE))
-    return build_forecast({k: v.float().cpu() for k, v in out.items()}, CFG.lead_times_hours, scene.timestamp,
-                          storm_center=storm, output_grid=out_grid, point_of_interest=city,
-                          normalizer=train_ds.normalizer, trained=model.trained_heads(), inputs=("satellite",))
-
-
-def show(fc):
-    print(f"\nissued {fc['issued']}   trustworthy: {fc['trustworthy']}")
-    for key in ("warning", "note"):
-        if key in fc:
-            print(f"  !! {fc[key]}")
-    for section in ("enso", "landfall", "track_scenarios", "eyewall", "rapid_intensification"):
-        value = fc.get(section)
-        if isinstance(value, dict) and value.get("available") is False:
-            print(f"  {section}: not available -- {value['reason']}")
-    if isinstance(fc.get("track_scenarios"), list):
-        for s in fc["track_scenarios"][:4]:
-            p = s["track"][5]
-            print(f"  {s['probability']:>5.0%} -> +{p['lead_hours']}h {p['latitude']:6.2f},{p['longitude']:7.2f}"
-                  f"  95% cone {p['cone_radius_km_95']:.0f} km")
-    print("  checks: " + ("pass" if not check_forecast(fc) else "; ".join(check_forecast(fc))))
-
-
-if RUN_FORECAST or RUN_WATCHER:
-    if model.trained_heads()["satellite_encoder"] == 0:
-        print("\nlive GOES forecast refused: no training stage has ever fed this model satellite imagery, so "
-              "its satellite encoder is at initialisation and every number it produced would be noise shaped "
-              "like a forecast. Use the HINDCAST section, which runs from the analysis the model was trained on.")
-    elif RUN_FORECAST:
-        banner("LIVE FORECAST — newest GOES scene")
-        show(forecast_now())
-
-
-def on_new_scene(paths):
-    result = forecast_now()
-    os.makedirs(os.path.join(DATA_DIR, "forecasts"), exist_ok=True)
-    stamp = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M")
-    with open(os.path.join(DATA_DIR, "forecasts", f"forecast_{stamp}.json"), "w") as handle:
-        json.dump(result, handle, indent=2)
-    show(result)
-
-
-if RUN_WATCHER and model.trained_heads()["satellite_encoder"] > 0:
-    banner("WATCHING — a new forecast every hour")
-    watch(on_new_scene, interval_seconds=3600, directory=os.path.join(DATA_DIR, "goes"), channels=("C13", "C09"))

docs/ARCHITECTURE.md

@@ -1,282 +0,0 @@
-# How iHELIX and NatureV1 work
-
-This is the detailed version. The short version: **most models reach a grid by flattening it and hoping a
-positional encoding puts the geometry back.** iHELIX does the opposite — you declare what your axes are,
-and everything downstream works in a space where the geometry is already correct.
-
----
-
-## 1. The problem with flattening
-
-Take a 240×121 latitude/longitude grid and flatten it row-major. Three things break:
-
-| | what the model sees | what is true |
-|---|---|---|
-| **Vertical neighbours** | 240 positions apart | adjacent |
-| **The date line** | 359.9° and 0.1° are 239 positions apart | adjacent |
-| **The poles** | ordinary interior points | all 240 entries are one place |
-
-A positional encoding gives the model an index. Nothing in an index says that cell 12,240 is directly
-above cell 12,000, or that the last column touches the first. So the model has to *learn spherical
-topology from data* — spending capacity rediscovering something you already knew.
-
-And it never quite succeeds, because the errors are worst exactly where the data is sparsest: near the
-poles, where meridians converge and grid cells shrink to nothing.
-
----
-
-## 2. Geometry: what replaces "position in a sequence"
-
-You declare axes. Each one says what kind of thing it is:
-
-```python
-Geometry([Axis("linear"), Axis("linear")])                          # an image
-Geometry([Axis("linear")] * 3)                                      # a volume or point cloud
-Geometry([Axis("periodic", period=L)] * 2 + [Axis("linear")])       # a channel-flow box
-Geometry.globe()                                                    # the Earth's surface
-Geometry.atmosphere()                                               # Earth + pressure
-```
-
-Each axis maps into a Euclidean space where **straight-line distance already is the distance you care
-about**:
-
-- **spherical** — `(latitude, longitude)` → a point on a sphere in 3-D. Chordal distance there is a
-  monotone function of great-circle distance. The poles stop being special. The date line **stops
-  existing**: 359.9° and 0.1° are near each other because they *are* near each other.
-- **periodic** — → a circle. Same trick, for a wind-tunnel box.
-- **log** — pressure. The model thinks in *factors* of pressure, not hectopascals, so equal ratios are
-  equal distances.
-- **linear** — passes through, scaled.
-
-Every axis carries a `scale` in real units (km, say). That's how you declare that a kilometre upward is
-not meteorologically the same as a kilometre sideways.
-
-### Local frames — the part that actually kills polar distortion
-
-At every point, the geometry provides an orthonormal frame: **east, north, up**. Neighbour offsets are
-expressed in *that point's own frame*.
-
-So "300 km east" produces the **same input vector** at the equator and at 80°N. The distortion isn't
-corrected by a factor — it is never introduced, because the representation never had it.
-
-> Measured: frames orthonormal to 1.11e-16 at the poles. Date-line distance 22 km, not 12,742 km.
-
----
-
-## 3. The grid: data, not architecture
-
-A `FieldGrid` holds two structures, computed once from the sample positions:
-
-**Neighbour graph** — for each point, its nearest neighbours *in metric space*. A point beside the date
-line gets neighbours on both sides of it. A polar point gets the ones physically close, not the ones the
-array happens to list adjacently.
-
-**Hierarchy** — a tree of nested spatial clusters, built by recursive splitting. The split is along the
-**principal axis** (`torch.linalg.eigh` of the covariance), not the widest coordinate axis — coordinate
-axes are an arbitrary choice of frame, so splitting on them would make the tree depend on how the domain
-happens to be oriented.
-
-The model takes the grid **as an argument**. Swap in a finer grid and the same weights run unchanged.
-That is the entire answer to resolution: the model never sees a grid shape, a resolution, or a
-dimensionality. It sees points, distances and weights.
-
----
-
-## 4. The three strands
-
-Every block braids three mixers. This is the core of the architecture.
-
-### Strand I — Geodesic attention (short range)
-
-Each sample attends to its nearest neighbours in metric space. Three things are added to the logits:
-
-1. **A learned geometric bias** from the displacement in the query's own frame, plus log-distance, plus
-   how much the neighbour's frame is rotated relative to the query's (which on a curved manifold is what
-   you need to parallel-transport a direction).
-2. **A per-head physical window.** Each head has its own radius — a *length*, not a count. At 88M the
-   eight heads sit on a geometric ladder: **120, 174, 252, 364, 527, 763, 1105, 1600 km**. One layer sees
-   eight scales at once, and those scales mean the same thing when the sampling changes.
-3. **Quadrature weights** — how much of the domain each sample stands for.
-
-That third term is what makes attention a discretization of a continuous operator:
-
-```
-out(x) = ∫ a(x,y) v(y) dμ(y) / ∫ a(x,y) dμ(y)
-```
-
-Refine the grid and the estimate **converges** instead of drifting.
-
-> Measured convergence: 0.455% → 0.174% → 0.090% → 0.034% as the grid refines.
-
-**The window has compact support** — exactly zero past 3σ, not merely small. This is not cosmetic. It's
-what makes the invariances hold *to the last bit* rather than to a few decimals. An early version
-truncated at K neighbours instead, and the permutation error was 3.0e-2; with compact support it is
-**exactly 0**.
-
-### Strand II — Index attention (long range)
-
-Local attention reaches 1,600 km. A teleconnection reaches across an ocean.
-
-The domain is summarized bottom-up into a tree of nested regions. Each query region computes a routing
-vector, descends the tree keeping a beam, and ends up attending over the samples of the `topk` regions it
-selected — which may be **anywhere, at any distance**.
-
-This is the part a fixed mesh cannot do. Message passing on a multi-mesh (GraphCast) couples regions by
-distance along fixed edges, so reaching the far side costs hops and the route is decided in advance.
-Here the route is **content-addressed and learned**: a ridge over the Atlantic can read the Pacific in one
-step, and nothing in the wiring had to anticipate it.
-
-**Making a discrete top-k differentiable.** Selection is argmax — no gradient. So the routing score is
-accumulated down the descent path and fed back as an additive bias on the retrieved logits, via
-`logsigmoid(path_score)`. Gradient reaches every level of the tree. (An early version didn't accumulate,
-and the node pooler received no gradient at all.)
-
-8 of the 17 layers carry the index strand, interleaved every other layer.
-
-### Strand III — Temporal (the gated delta rule)
-
-**Space has no order, so nothing recurrent runs across it.** Time does, and this is the only place a
-recurrence runs.
-
-State is a **matrix per head per sample** whose size does not depend on how many frames have passed. A
-rollout costs the same at frame 1000 as at frame 1 — which is what makes long autoregressive integrations
-affordable. Training uses a chunkwise-parallel UT transform, so it parallelizes rather than stepping.
-
-A per-sample, per-head gate mixes strand I and strand II. Then a feed-forward, with RMSNorm and residuals
-throughout.
-
----
-
-## 5. Encode → process → decode
-
-```
-satellite (2 km)   ─┐
-analysis  (25 km)  ─┼─► cross-attention ─► Fibonacci mesh (4,096 pts) ─► 17 blocks ─► cross-attention ─► any output grid
-environment        ─┘
-```
-
-Each source has **its own input projection and its own read radius** — a satellite scene at 2 km and an
-analysis field at 25 km are not the same kind of measurement and shouldn't pretend to be. What they share
-is the mesh they're read onto, which makes fusing them a **sum** rather than a resampling.
-
-Each encoder carries a learned `absent` vector, so a mesh point with no coverage (the far side of the
-planet from a geostationary satellite) produces a clean absence rather than attending to noise.
-
-The mesh is a **Fibonacci sphere** — near-equal-area, so there's no pole to distort and no seam to cross.
-
----
-
-## 6. Why this beats a ViT/CNN on satellite imagery
-
-| | ViT / CNN | iHELIX |
-|---|---|---|
-| Pixel size | assumed constant | **measured**: a GOES limb pixel covers 64× the ground of a nadir pixel |
-| Location | `image[400, 1200]` says nothing | every sample carries lat/lon + true footprint area |
-| Values | normalized to 0–1, physics erased | brightness temperature stays in kelvin |
-| Two sources | resample one onto the other, lose information | read both onto one mesh, add |
-
-The projection is solved per-pixel from GOES-R PUG Vol 3 §5.1.2.8.1 — validated against the file's own
-metadata at 2.07 km at nadir where nominal C13 resolution is 2 km.
-
----
-
-## 7. Parameter budget (88M)
-
-```
-blocks                84.67M   95.1%   ← the 17 braided blocks
-analysis_encoder       0.80M    0.9%
-environment_encoder    0.79M    0.9%
-satellite_encoder      0.79M    0.9%
-decoder                0.79M    0.9%
-ri_head                0.40M    0.4%
-summary_pool           0.26M    0.3%
-track_head             0.14M    0.2%
-eyewall_head           0.13M    0.1%
-field_head             0.07M    0.1%
-...
-```
-
-95% of the model is the shared processor. The heads are almost free — which is exactly what makes freezing
-the backbone and fine-tuning on 24,585 storm points viable: **0.96M trainable, 1.1%**.
-
----
-
-## 8. Every output is a distribution
-
-- **Track** — weighted scenarios, each a full trajectory with a *tilting* uncertainty ellipse (two sigmas
-  and a correlation, so the ellipse can align with the direction of travel). Reads as "62% recurves
-  offshore, 26% tracks the coast, 12% inland" rather than an average track through somewhere the storm was
-  never going. *Measured: collapsing to one line scores 116 under the mixture likelihood where keeping both
-  branches scores 8.2.*
-- **Fields** — per-point mean and variance, per lead time.
-- **Eyewall** — peak wind, RMW, and 34/50/64 kt radii per quadrant, each with intervals.
-- **RI** — probability per threshold, plus expected 24 h change and likeliest onset.
-- **Landfall** — probability per lead time.
-
-Heads start at **Atlantic climatology**, not zero: 65 ± 30 kt peak wind, 985 hPa, RI at the measured 4.11%
-base rate, track spread growing 0.6°→12° with lead. Without that, the intensity term alone was 119,191 of
-a 60,565 total loss.
-
----
-
-## 9. The guarantees, and their one precondition
-
-| Property | Status |
-|---|---|
-| Sample order doesn't matter | **exact** (atol=0) |
-| Spinning the globe in longitude | **exact** for the local strand (atol=1e-6) |
-| Refining the grid converges | 0.455% → 0.034% |
-| Time is causal, space is not | enforced |
-| Temporal state doesn't grow | constant |
-
-**The one precondition:** each head's neighbour list must reach 3× its widest radius. `coverage()` reports
-whether it does, and the model warns at construction if not. At coverage 1.0 the samples beyond a head's
-window contribute *exactly* nothing and the invariances are exact.
-
-**One honest limit:** the index strand is *not* rotation-equivariant, because carving a domain into
-regions is a discretization and no finite partition of a sphere commutes with arbitrary rotation. A fixed
-icosahedral mesh has the same property. Sub-regions aren't isotropic, so every split below the first is
-well determined.
-
----
-
-## 10. What 0.8 added, and why each one helps accuracy
-
-**Full-state residual prediction.** A `state_head` predicts the 6-hour *change* of every prognostic
-channel — all 86 of them, including all 13 pressure levels — rather than seven surface fields. Before
-this, a 12-step rollout froze 84 of 89 channels: Z500 never moved. The head is zero-initialised, so an
-untrained model is *exactly* persistence and training can only move it from the strongest trivial
-baseline. Changes are scaled by each channel's own 6-hour tendency spread (0.067σ for Z500, 1.08σ for
-ω@500), so no channel dominates the gradient by being volatile.
-
-**Channel roles.** Every input channel is prognostic (predicted), forcing (recomputed) or static
-(carried). Top-of-atmosphere solar radiation is computed from orbital geometry at each step's valid time,
-matching ERA5 at correlation 1.00000; it rotates with an augmented globe.
-
-**Physical constraints.** Mass conservation removes any change in the area-weighted mean surface pressure
-each step. Pressure levels are weighted in proportion to pressure (GraphCast), and every loss is
-area-weighted — the same weighting the WeatherBench score uses.
-
-**Fair-CRPS ensembles.** Per-member noise enters before the processor; a fair CRPS over members trains
-sharp members with calibrated spread. A model trained on squared error learns the conditional mean, and
-the mean of all the ways a hurricane could go is a weak, smeared vortex — the documented intensity low
-bias of deterministic AI models.
-
-**Storm-centred heads.** Storm heads used to read a mean over the whole planet, so two storms at the same
-hour got identical answers. They now pool the mesh around the storm (Gaussian, 500 km), and are told
-where it is and what it is doing: current intensity and 12-hour motion — the predictors every operational
-intensity scheme starts from, and exactly what a 1.5° reanalysis cannot show.
-
-**A training record.** Every output counts its optimizer steps, saved with the weights. Forecasts show a
-section only if its head was trained, and refuse outright when the input path (e.g. GOES imagery) never
-was.
-
-## 11. What is not claimed
-
-**No weights here have been trained.** The architecture, losses, ingest and training loop are complete and
-exercised end to end on real data, but no accuracy has been measured, and nothing here should inform a
-decision about a real storm. The National Hurricane Center is the authoritative source.
-
-The next honest step is baselines: score against **persistence** ("tomorrow = today") and **climatology**
-on the same held-out batches. A model that ties climatology has learned nothing; likelihoods alone can't
-tell you which.

molab_swarm_cell.py

@@ -1,311 +0,0 @@
-# NatureV1 0.16 -- the operational cell: the satellite path, the swarm, the parishes, the cycle record, in ONE marimo cell
-# (molab, 1 GPU; runs on a CPU box too, smaller).
-#
-# Paste this whole file into one marimo cell and run it. What it does:
-#   1. installs naturev1 0.16 with the swarm extras (GRIB decoder, terrain tiles, maps, the Hub client)
-#   2. builds the map of the whole Caribbean -- every parish / province / district of every country and territory,
-#      with terrain -- and the full-consensus inputs (climatology + analog database), once, cached under DATA
-#   3. for every active NHC storm (or a replay, e.g. Melissa 2025): the best track + every satellite / recon / radar
-#      centre fix from NHC, the GFS analysis AND the forecasts of five models -- GFS, ECMWF IFS, ECMWF AIFS,
-#      GraphCast-GFS, the GEFS mean -- read from their public buckets; the NatureV1 consensus blended with the models'
-#      mean track and fed the previous cycle's error; a cone sized for this forecast and a swarm sized to it; the
-#      intensity consensus with its rapid-intensification branch, the chance the storm peaks at each category and the
-#      calibrated peak quantiles (plan for the 90% figure); the swarm's worlds filtered minute by minute on the fixes
-#      and painted onto the parishes: peak wind if hit, gusts, rain if hit and the wettest cell, when tropical-storm
-#      and hurricane force arrive, the landfall report for LANDFALL_COUNTRIES
-#   4. the satellite, quantitatively: the newest GOES band-13 scene shown, and read -- coldest tops, the cold share of
-#      the 50-200 km annulus, ring symmetry, an eye, and their trend since the previous cycle (diagnostics beside
-#      the forecast; not yet inside the probabilities)
-#   5. the operations desk's record: every cycle saved under DATA/runs/<storm>/ as JSON plus the parish table as CSV;
-#      the previous cycle found again automatically; what changed since it; optionally keeps watching NHC and
-#      re-issues when a new 6-hourly cycle appears (WATCH_MINUTES)
-#   6. optionally (TRAIN_SATELLITE) trains the satellite networks of the 0.12 satellite path on this GPU
-#
-# Research model, not an operational forecast: for decisions, follow your national meteorological service and the
-# National Hurricane Center.
-import datetime as dt
-import os
-import subprocess
-import sys
-import time
-
-subprocess.run([sys.executable, "-m", "pip", "install", "-q", "--upgrade", "naturev1[swarm,hub]>=0.16.0", "ihelix>=0.6.0"],
-               check=True)
-
-from pathlib import Path
-
-import marimo as mo
-import numpy as np
-import torch
-
-# ── settings ──────────────────────────────────────────────────────────────────────────────────────────────────────
-STORM = None                   # None: every active NHC storm. Or an NHC id, e.g. "al132025" (Melissa 2025)
-REPLAY_TIME = None             # with STORM: replay what was known then, e.g. "2025-10-27T00" (fixes after it unused)
-LANDFALL_COUNTRIES = ("Jamaica",)   # one landfall report per country: when, where first, how strong, every parish's numbers
-GPU = torch.cuda.is_available()
-PARTICLES = 1_000_000 if GPU else 50_000          # worlds in the swarm
-IMPACT_WORLDS = 40_000 if GPU else 2_000          # worlds painted onto the map (the map is the costly part)
-FULL_CONSENSUS = True          # 13-member consensus: builds a 2.5 GB climatology + analog database once (~20-30 min)
-SHOW_GOES = True               # the newest GOES-19 / GOES-18 infrared image around each live storm, shown and read
-FORECAST_FLOW = True           # the models' forecast steering + their tracks as members (~150 MB per model, cached)
-MODELS = ("gfs", "ifs", "aifs", "graphcastgfs", "gefs")   # any that is not yet published for the cycle is skipped
-PREVIOUS_CYCLE = "auto"        # the previous cycle's error feeds the new track ("auto": from the saved records; None: off)
-WATCH_MINUTES = 0              # 0: issue once and stop. 20: keep watching NHC, re-issue when a new 6-hourly cycle appears
-TRAIN_SATELLITE = False        # the 0.12 satellite networks on this GPU (needs ~1 TB disk for the staged GridSat)
-HF_REPO, HF_TOKEN = "CorxLabs/NatureV1-500", ""   # only for TRAIN_SATELLITE pushes; paste a token, clear it after
-DATA = Path(os.environ.get("NATUREV1_DATA", "/data/naturev1" if Path("/data").exists() else Path.home() / "naturev1"))
-DATA.mkdir(parents=True, exist_ok=True)
-RUNS = DATA / "runs"                                # the cycle records: <storm>/<time>.json + <time>_parishes.csv
-DEVICE = "cuda" if GPU else "cpu"
-
-import naturev1
-from naturev1.satellite import SatelliteScene
-from naturev1.swarm.bulletin import history, load_previous, write_bulletin
-from naturev1.swarm.fixes import active_storms, fetch_deck, parse_bdeck
-from naturev1.swarm.geography import CARIBBEAN, RegionMap
-from naturev1.swarm.infrared import ir_metrics
-from naturev1.swarm.landfall import format_landfall, landfall_summary
-from naturev1.swarm.live import consensus_inputs, forecast_storm, goes_scene
-from naturev1.swarm.plot import impact_figure, landfall_figure
-
-print(f"naturev1 {naturev1.__version__} on {DEVICE}" + (f" ({torch.cuda.get_device_name(0)})" if GPU else ""))
-
-# ── the ground: the whole Caribbean, parish by parish, with terrain (downloaded once) ─────────────────────────────
-region_file = DATA / "caribbean_region.npz"
-if not region_file.exists():
-    RegionMap.build(CARIBBEAN, cache=DATA / "region").save(region_file)
-region = RegionMap.load(region_file)
-print(f"map: {len(region.names)} administrative units, {int(region.land.sum()):,} land cells")
-
-climatology = analogs = None
-if FULL_CONSENSUS:
-    climatology, analogs = consensus_inputs(DATA)
-
-
-# ── helpers ───────────────────────────────────────────────────────────────────────────────────────────────────────
-def newest_cycle(storm_id):
-    """The newest 6-hourly best-track time NHC has posted for a storm (what a new issue would be based on)."""
-    best = parse_bdeck(fetch_deck(storm_id, "b", False))
-    synoptic = [f.time for f in best if int(str(f.time)[11:13]) % 6 == 0 and str(f.time)[14:16] == "00"]
-    return max(synoptic) if synoptic else None
-
-
-def goes_and_infrared(case, storm_id):
-    """The newest GOES scene around the storm and its infrared diagnostics, with the trend since the scene kept last time."""
-    scene = goes_scene(case.lat, case.lon, DATA / "goes")
-    keep = DATA / "goes" / f"{storm_id}_previous.npz"
-    previous, hours = None, None
-    if keep.exists():
-        try:
-            z = np.load(keep)
-            when = dt.datetime.fromisoformat(str(z["time"]))
-            hours = (scene.timestamp - when).total_seconds() / 3600.0
-            previous = SatelliteScene(latitude=z["lat"], longitude=z["lon"], values=z["bt"][:, None], area_km2=z["area"],
-                                      channels=("C13",), timestamp=when, satellite=str(z["satellite"]))
-        except Exception:
-            previous, hours = None, None
-    ir = ir_metrics(scene, case.lat, case.lon, previous=previous if hours and 0.5 <= hours <= 12.0 else None, previous_hours=hours)
-    np.savez(keep, lat=scene.latitude, lon=scene.longitude, bt=scene.values[:, 0], area=scene.area_km2,
-             time=str(scene.timestamp), satellite=str(scene.satellite))
-    return scene, ir
-
-
-def since_previous(storm_id, run, summary):
-    """One line on what moved since the previous saved cycle: landfall probability and time, intensity, the ceiling."""
-    prev = load_previous(RUNS, storm_id, run["analysis_time"])
-    if prev is None:
-        return ""
-    rec = prev["record"]
-    bits = [f"since the {str(prev['time'])[5:16]}Z cycle:"]
-    lf = rec.get("landfall") or {}
-    if summary and lf:
-        bits.append(f"landfall probability {lf.get('p_landfall', float('nan')):.0%} -> {summary['p_landfall']:.0%}")
-        if lf.get("consensus", {}).get("time") and summary.get("consensus", {}).get("time"):
-            bits.append(f"consensus landfall {lf['consensus']['time'][5:16]} -> {summary['consensus']['time'][5:16]}")
-    fc = rec.get("forecast", {})
-    if fc.get("intensity") and len(fc["intensity"]) > 2 and fc["intensity"][2] is not None:
-        bits.append(f"24 h intensity {fc['intensity'][2]:.0f} -> {run['result']['intensity'][2]:.0f} kt")
-    pq_old, pq_new = fc.get("peak_quantiles"), run["result"].get("peak_quantiles")
-    if pq_old and pq_new:
-        bits.append(f"90% peak ceiling {pq_old['peak_kt'][2]:.0f} -> {pq_new['peak_kt'][2]:.0f} kt")
-    return "  \n**" + " ".join(bits[:1]) + "** " + "; ".join(bits[1:])
-
-
-def issue(storm_id, name, when):
-    """One cycle for one storm: the forecast, the panels, the record. Returns (panel, analysis time)."""
-    run = forecast_storm(storm_id, when=when, archive=when is not None, particles=PARTICLES, device=DEVICE, region=region,
-                         climatology=climatology, analogs=analogs, impact_particles=IMPACT_WORLDS, cache=DATA, name=name,
-                         forecast_flow=FORECAST_FLOW, models=MODELS, previous=PREVIOUS_CYCLE, save_runs=True)
-    case, result, impact = run["case"], run["result"], run["impact"]
-    scene, ir = None, None
-    if SHOW_GOES and when is None:
-        try:
-            scene, ir = goes_and_infrared(case, storm_id)
-        except Exception as error:
-            print(f"GOES: {error}")
-    fig = impact_figure(run, scene=scene)
-    landfall_panels, main_summary = [], None
-    if impact is not None:
-        for country in LANDFALL_COUNTRIES:
-            summary = landfall_summary(region, result, case, impact, country, analysis_time=run["analysis_time"])
-            main_summary = main_summary or summary
-            if summary["p_landfall"] >= 0.02:
-                landfall_panels += [landfall_figure(run, summary, country), mo.plain_text(format_landfall(summary, top=14))]
-            else:
-                landfall_panels.append(mo.md(f"**{country}:** the centre reaches it in {summary['p_landfall']:.0%} of worlds within 5 days."))
-    record = write_bulletin(run, main_summary, RUNS, storm_id)                      # the full record (replaces the bare one)
-    sw = result["swarm"]
-    scen = ", ".join(f"{k} {v['probability']:.0%}" for k, v in sw["scenarios"].items())
-    filt = sw["filter"]
-    sources = sorted({h.get("source", "best track") for h in filt})
-    ess_after = f"; re-weighted by {len(run['fixes_after'])} newer fixes (ESS {run['ess_after']:.2f})" if run["ess_after"] else ""
-    track = "  ".join(f"{h} h {la:.1f}N {abs(lo):.1f}{'W' if lo < 0 else 'E'}"
-                      for h, (la, lo) in zip(result["leads"], result["track"]) if np.isfinite(la))
-    intensity = "  ".join(f"{h} h {v:.0f} kt" for h, v in zip(result["leads"], result["intensity"]) if np.isfinite(v))
-    p_ri = result.get("ri_probability")
-    ri = f"  \n**Rapid intensification (+30 kt in 24 h):** {p_ri:.0%} ({result.get('intensity_regime')} weights)" if p_ri is not None else ""
-    names = {64: "hurricane", 96: "major", 113: "Cat 4", 137: "Cat 5"}
-    pk = result.get("peak_probability")
-    if pk:
-        ri += "  \n**Chance the storm peaks at or above (next 5 days):** " + "; ".join(f"{names.get(int(t), f'{t:.0f} kt')} {p:.0%}" for t, p in zip(pk["thresholds_kt"], pk["probability"]))
-    pq = result.get("peak_quantiles")
-    if pq:
-        ri += "  \n**Peak within 5 days, calibrated quantiles:** " + "; ".join(f"{int(round(l * 100))}% {v:.0f} kt" for l, v in zip(pq["levels"], pq["peak_kt"])) + " (plan for the 90% figure)"
-    if result.get("peak_if_ri_kt") is not None and p_ri is not None:
-        ri += f"  \n**If it intensifies rapidly ({p_ri:.0%}):** expected peak {result['peak_if_ri_kt']:.0f} kt"
-    cats = result.get("category_probability")
-    if cats:
-        ri += "  \n**P(at least ...):** " + "; ".join(
-            f"{names.get(int(t), f'{t:.0f} kt')} " + " ".join(f"{h}h {p:.0%}" for h, p in zip(result["leads"], cats["probability"][:, j]) if np.isfinite(p))
-            for j, t in enumerate(cats["thresholds_kt"]))
-    if result.get("intensity_note"):
-        ri += f"  \n**Note:** {result['intensity_note']}"
-    envt = result.get("environment") or {}
-    if "tchp_kj_cm2" in envt and np.isfinite(envt["tchp_kj_cm2"][:49]).any():
-        ri += (f"  \n**Ocean under the first 48 h:** 26 C water {np.nanmean(envt['d26_m'][:49]):.0f} m deep, heat potential "
-               f"{np.nanmean(envt['tchp_kj_cm2'][:49]):.0f} kJ/cm2, sea surface {np.nanmean(envt['sst_k'][:49]) - 273.15:.1f} C "
-               f"(effective {np.nanmean(envt['sst_eff_k'][:49]) - 273.15:.1f} C under the core)")
-    if run.get("r34_km") is not None and np.isfinite(run["r34_km"]):
-        ri += f"  \n**Observed 34-kt radius:** {run['r34_km']:.0f} km (the wind field is sized to it)"
-    deep = result.get("model_deepening_hpa")
-    if deep is not None and np.isfinite(deep).any():
-        ri += "  \n**Models' deepening (hPa, central-pressure deficit):** " + "  ".join(f"{h}h {d:+.0f}" for h, d in zip(result["leads"], deep) if np.isfinite(d))
-    if ir:
-        ri += f"  \n**{ir['text']}**"
-    guide = run.get("guidance") or {}
-    if guide.get("available"):
-        used_t = (result.get("aids_track") or {}).get("members", [])
-        used_i = (result.get("aids_intensity") or {}).get("members", [])
-        subs = {**(result.get("aids_track") or {}).get("substituted", {}), **(result.get("aids_intensity") or {}).get("substituted", {})}
-        ri += (f"  \n**NHC guidance ({len(guide['available'])} aids in the a-deck):** track blended with {', '.join(used_t) or 'none'}; "
-               f"intensity with {', '.join(used_i) or 'none'}" + (f"; stand-ins {', '.join(f'{v} for {k}' for k, v in subs.items())}" if subs else ""))
-        if result.get("intensity_ours") is not None:
-            ri += "  \n**Our own consensus before the aids:** " + "  ".join(f"{h} h {v:.0f} kt" for h, v in zip(result["leads"], result["intensity_ours"]) if np.isfinite(v))
-        at = result.get("aids_track") or {}
-        if at.get("disagreement_km") is not None:
-            dis = np.asarray(at["disagreement_km"], float); cone = np.asarray(result.get("cone_km", np.full(len(dis), np.nan)), float)
-            far = [f"{h} h {d:.0f} km (cone {c:.0f})" for h, d, c in zip(result["leads"], dis, cone) if np.isfinite(d) and np.isfinite(c) and d > c]
-            ri += ("  \n**Our track and HCCA disagree beyond the cone at " + "; ".join(far) + " -- both are in the record; the blend sits between them**") if far else \
-                  "  \n**Our track and HCCA agree within the cone at every lead**"
-        if at.get("adaptive_w_ours") is not None:
-            pe = at.get("previous_errors_km", {})
-            ri += (f"  \n**Weights earned from the previous cycle:** ours {pe.get('ours', float('nan')):.0f} km off, HCCA {pe.get('HCCA', float('nan')):.0f} km off at the time now analysed; "
-                   f"our share {np.asarray(at['adaptive_w_ours'])[2]:.0%} at 24 h")
-        of = guide.get("ofcl") or {}
-        if of.get("intensity") is not None and of.get("track") is not None:
-            ri += "  \n**NHC official forecast:** " + "  ".join(
-                f"{h} h {la:.1f}N {abs(lo):.1f}{'W' if lo < 0 else 'E'} {v:.0f} kt"
-                for h, (la, lo), v in zip(result["leads"], of["track"], of["intensity"]) if np.isfinite(la) and np.isfinite(v))
-        if guide.get("nhc_ri") and guide["nhc_ri"].get("p30_24") is not None:
-            schemes = "; ".join(f"{k} {v:.0%}" for k, v in (guide["nhc_ri"].get("schemes") or {}).items() if v is not None)
-            ri += f"  \n**NHC rapid-intensification guidance:** {guide['nhc_ri']['p30_24']:.0%} ({guide['nhc_ri']['source']}; {schemes})"
-            if guide.get("ri_probability_combined") is not None:
-                ri += f"; equal-weight with ours: **{guide['ri_probability_combined']:.0%}**"
-    used = run.get("models", {})
-    mm = run.get("model_track")
-    model_text = ((f"  \n**Models read:** {', '.join(m['title'] for m in used.values())}; their mean track: "
-                   + "  ".join(f"{h} h {la:.1f}N {abs(lo):.1f}{'W' if lo < 0 else 'E'}" for h, (la, lo) in zip(result["leads"], mm) if np.isfinite(la)))
-                  if mm is not None else "  \n**Models:** none read for this cycle (analysis-only forecast)")
-    spread = result.get("model_spread_km")
-    if spread is not None and np.isfinite(spread).any():
-        model_text += "  \n**Models' disagreement (km):** " + "  ".join(f"{h} h {d:.0f}" for h, d in zip(result["leads"], spread) if np.isfinite(d))
-    if run.get("previous_used") is not None:
-        model_text += f"  \n**Previous cycle:** {str(run['previous_used'])[:16]}Z, its error fed back into this track"
-    cone = result.get("cone_km")
-    cone_text = ("  \n**Cone for this forecast (km, 67%):** " + "  ".join(f"{h} h {r:.0f}" for h, r in zip(result["leads"], cone))
-                 + (" (climatological cone " + "/".join(f"{r:.0f}" for r in result["cone_fixed_km"]) + ")" if "cone_fixed_km" in result else "")) if cone is not None else ""
-    drift = since_previous(storm_id, run, main_summary)
-    record_text = f"  \n**Record:** {record['json']}" + (f", parishes {record['csv'].name}" if record.get("csv") else "") + f"; {len(history(RUNS, storm_id))} cycle(s) on file"
-    panel = mo.vstack([
-        mo.md(f"## {name} ({storm_id}) -- analysis {str(run['analysis_time'])[:16]}Z, {case.wind_kt:.0f} kt at {case.lat:.1f}N {abs(case.lon):.1f}W\n"
-              f"**Satellite path:** {len(filt)} fixes filtered the swarm ({', '.join(sources[:6])}){ess_after}.  \n"
-              f"**Swarm:** {PARTICLES:,} worlds sized to the cone; scenarios: {scen}.  \n"
-              f"**Track** ({result['consensus_table']}): {track}{model_text}{cone_text}  \n**Intensity:** {intensity}{ri}{drift}{record_text}"),
-        fig,
-        *landfall_panels,
-        mo.plain_text(impact.table(top=30)) if impact is not None else mo.md("no impact map for this storm"),
-        mo.md(f"<sub>{region.attribution} Research model, not an operational forecast. Storm surge is not modelled.</sub>"),
-    ])
-    return panel, run["analysis_time"]
-
-
-# ── the storms: once, or watched ─────────────────────────────────────────────────────────────────────────────────
-panels, issued = [], {}
-while True:
-    if STORM is None:
-        storms = [(s["id"], s["name"]) for s in active_storms() if s["id"][:2] in ("al", "ep", "cp")]
-    else:
-        storms = [(STORM, STORM.upper())]
-    if not storms and not panels:
-        panels.append(mo.md("**No active storms in the Atlantic or eastern / central Pacific right now.** "
-                            "Set `STORM = \"al132025\"` and `REPLAY_TIME = \"2025-10-27T00\"` to replay Hurricane Melissa."))
-    for storm_id, name in storms:
-        try:
-            if WATCH_MINUTES and REPLAY_TIME is None and issued.get(storm_id) is not None:
-                newest = newest_cycle(storm_id)
-                if newest is None or newest <= issued[storm_id]:
-                    continue                                                  # nothing new from NHC for this storm
-            panel, when_issued = issue(storm_id, name, REPLAY_TIME)
-            if issued.get(storm_id) == when_issued:
-                continue                                                      # the GFS for the newer cycle is not out yet
-            issued[storm_id] = when_issued
-            panels.append(panel)
-            mo.output.append(panel)
-        except Exception as error:                                            # one storm failing must not hide the others
-            panels.append(mo.md(f"**{name} ({storm_id})**: no forecast -- {type(error).__name__}: {error}"))
-            mo.output.append(panels[-1])
-    if not WATCH_MINUTES or REPLAY_TIME is not None:
-        break
-    mo.output.append(mo.md(f"<sub>watching NHC; next check at {(dt.datetime.now(dt.timezone.utc) + dt.timedelta(minutes=WATCH_MINUTES)):%H:%M} UTC</sub>"))
-    time.sleep(WATCH_MINUTES * 60)
-
-# ── optional: the satellite networks of the 0.12 satellite path, on this one GPU ─────────────────────────────────
-if TRAIN_SATELLITE:
-    from naturev1.b300 import follow, start_job
-    from naturev1.ibtracs import fetch_ibtracs, parse_ibtracs, storm_label_table
-
-    if HF_TOKEN.strip():
-        os.environ["HF_TOKEN"] = HF_TOKEN.strip()
-    SAT, CKPT, LOGS = DATA / "satellite", DATA / "checkpoints", DATA / "logs"
-    for folder in (SAT, CKPT, LOGS):
-        folder.mkdir(parents=True, exist_ok=True)
-    ibtracs = fetch_ibtracs(DATA)
-    labels = SAT / "labels.npz"
-    if not labels.exists():
-        np.savez(labels, **storm_label_table(parse_ibtracs(ibtracs, since=1980, until=2021)))
-    from huggingface_hub import hf_hub_download
-    base = DATA / "base.pt"
-    if not base.exists():
-        import shutil
-        shutil.copy2(hf_hub_download(HF_REPO, "checkpoints/stage3/latest.pt"), base)
-    start_job("gridsat", [sys.executable, "-m", "naturev1.satstage", "--root", str(SAT), "--ibtracs", str(ibtracs),
-                          "--years", "1980-2021", "--workers", str(max((os.cpu_count() or 8) - 2, 2)),
-                          "--resolution", "0.25"], LOGS)
-    follow(LOGS, ["gridsat"])
-    common = ["--checkpoint", str(base), "--root", str(SAT), "--table", str(labels), "--output", str(CKPT),
-              "--hours", "2.0", "--hub-repo", HF_REPO]
-    start_job("stage-a-satnet", ["-m", "naturev1.sattrain", "satnet", *common, "--workers", "8"], LOGS, gpus=[0])
-    follow(LOGS, ["stage-a-satnet"])
-    panels.append(mo.md(f"satellite stage A finished: {CKPT / 'stage-a-satnet'}"))
-
-mo.vstack(panels)

naturev1/__init__.py

@@ -1,253 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""NatureV1 - a probabilistic weather model over geolocated fields."""
-
-from .besttrack import Track, parse_hurdat2, rapid_intensification, split_by_storm
-from .checkpoint import CheckpointManager, TrainingState
-from .corpora import CORPORA, augment_batch, catalogue, open_weatherbench, rotate_longitude
-from .era5 import (
-                   FIELD_DIMS,
-                   CachedERA5,
-                   ERA5Window,
-                   GridCollate,
-                   Normalizer,
-                   corpus_scale,
-                   equiangular_weights,
-                   era5_loader,
-                   era5_source_grid,
-                   era5_splits,
-                   expand_variables,
-                   lead_offsets,
-                   materialise,
-                   normalization,
-                   read_block,
-)
-from .fallback import (
-                   Choice,
-                   Plan,
-                   ensure_packages,
-                   install_packages,
-                   resolve_all,
-                   resolve_batch,
-                   resolve_precision,
-                   resolve_staging,
-                   resolve_variables,
-                   with_retry,
-)
-from .forecast import (
-                   build_forecast,
-                   decode_eyewall,
-                   decode_landfall,
-                   decode_point_forecast,
-                   decode_rapid_intensification,
-                   decode_track,
-                   nearest_point,
-)
-from .guards import (
-                   PHYSICAL,
-                   Bounds,
-                   PreflightError,
-                   TrainingWatchdog,
-                   check_device_agreement,
-                   check_environment,
-                   check_forecast,
-                   check_grid_alignment,
-                   check_normalization,
-                   check_weights,
-                   format_preflight,
-                   preflight,
-                   responds_to_input,
-)
-from .hub import from_pretrained, push_to_hub, save_for_hub
-from .launch import follow, launch, progress, status, stop
-from .live import fetch_latest, latest_scene_keys, watch
-from .losses import area_weights, focal_bce, masked_gaussian_nll, total_loss, track_mixture_nll
-from .mirror import HubMirror, session_started
-from .model import (
-                   RI_THRESHOLDS_KT,
-                   STORM_ENVIRONMENT_FEATURES,
-                   STORM_STATE_FEATURES,
-                   SURFACE_FIELDS,
-                   TRACK_MEMBERS,
-                   TRACKED_HEADS,
-                   WEATHER_TYPES,
-                   WIND_RADII_THRESHOLDS_KT,
-                   EyewallHead,
-                   NatureConfig,
-                   NatureV1,
-                   RapidIntensificationHead,
-                   calendar_features,
-)
-from .planning import autotune_batch_size, benchmark_steps, device_report, format_plan, training_plan
-from .rollout import (
-                   RolloutSchedule,
-                   advance_calendar,
-                   drift_report,
-                   field_to_channel,
-                   reinject,
-                   rollout_forecast,
-                   rollout_loss,
-)
-from .satellite import SatelliteScene, fixed_grid_to_latlon, footprint_area_km2, normalize_channels, scene_from_netcdf
-from .state import (
-                   FORCING_VARIABLES,
-                   HEADLINE_STATE_FIELDS,
-                   STATIC_VARIABLES,
-                   ChannelRoles,
-                   StateStepper,
-                   channel_loss_weights,
-                   channel_roles,
-                   conserve_mass,
-                   fair_crps,
-                   score_state,
-                   solar_forcing,
-                   spread_skill_ratio,
-                   state_forecast,
-                   state_rollout_loss,
-                   tendency_std,
-                   toa_accumulated,
-                   toa_flux,
-                   train_state_rollout,
-)
-from .steering import (
-                   BETA_DRIFT_MS,
-                   advect,
-                   describe_environment,
-                   extrapolation_track,
-                   steering_track,
-                   storm_environment,
-)
-from .storms import (
-                   StormTargets,
-                   calibration_report,
-                   fit_feature_monitor,
-                   fit_probability_calibration,
-                   StormWindow,
-                   consensus_track,
-                   describe_consensus,
-                   fit_track_consensus,
-                   format_pairing,
-                   lead_track_points,
-                   pair_tracks_with_reanalysis,
-                   storm_feature_bank,
-                   storm_scorecard,
-                   storm_state_vector,
-                   track_members,
-                   train_storm_heads,
-)
-from .train import Trainer, TrainSettings, apply_ema, load_for_inference, next_state_targets
-from .upper import (
-                   HEADLINE_LEVELS,
-                   PRESSURE_LEVELS,
-                   SURFACE_EXTRAS,
-                   UPPER_VARIABLES,
-                   channel_names,
-                   headline_channels,
-                   open_weatherbench_levels,
-                   read_levels,
-                   upper_air_report,
-                   volume_coords,
-                   volume_grid,
-)
-from .wb2 import (
-                   HEADLINE,
-                   Score,
-                   Scorecard,
-                   ScoredField,
-                   build_climatology,
-                   climatology_forecast,
-                   latitude_weights,
-                   persistence_forecast,
-                   score_model,
-                   scoring_fields,
-                   weighted_acc,
-                   weighted_rmse,
-)
-
-
-from . import stormsat  # noqa: E402
-
-__version__ = "0.16.0"
-
-#: 0.12 names, imported from their modules on first use -- so ``import naturev1`` costs nothing extra and
-#: works with ihelix 0.5, and only the satellite networks themselves ask for ihelix 0.6.
-_LAZY = {
-    "SatNetStorm": "satnet", "SatNetConfig": "satnet", "SatelliteRetrieval": "satnet", "apply_retrieval": "satnet",
-    "cloud_motion": "satnet", "RI_WINDOWS": "satnet",
-    "parse_ibtracs": "ibtracs", "storm_label_table": "ibtracs", "describe_table": "ibtracs", "fetch_ibtracs": "ibtracs",
-    "stage_gridsat": "satstage", "stage_month": "satstage", "read_gridsat": "satstage", "decode_global": "satstage",
-    "GlobalFrames": "satdata", "StormPatches": "satdata", "StormSequenceDataset": "satdata",
-    "RetrievalDataset": "satdata",
-    "Engine": "engine", "EngineSettings": "engine",
-    "train_satnet": "sattrain", "train_retrieval": "sattrain", "merged_model": "sattrain",
-    "train_storms": "stormtrain", "memmap_feature_bank": "stormtrain", "finalise_storms": "stormtrain",
-    "compare_models": "stormtrain",
-    "track_vortex": "tracker", "find_storms": "tracker", "rollout_member_tracks": "tracker",
-    "vortex_centre": "tracker",
-    "fit_intensity_correction": "storms", "ri2_report": "storms", "intensity_by_category": "storms",
-    "hardware_preflight": "hardware", "publish_release": "b300",
-    "select_rotations": "stormtrain", "class_weights": "stormtrain", "refine_centre": "satnet",
-    "potential_intensity": "thermo", "storm_physics": "thermo", "cyclone_phase": "thermo", "genesis_map": "thermo",
-    "STORM_PHYSICS_FEATURES": "thermo",
-    "wind_field": "windfield", "wind_hazard": "windfield", "wind_probability_map": "windfield",
-    "StatisticalModels": "statistical", "fit_intensity_consensus": "statistical",
-    "multi_fix_centre": "tracker", "track_storm_in_rollout": "tracker", "AnalogForecaster": "tracker",
-    "merge_rotations": "model", "rotation_angles": "model",
-    "Assimilator": "assimilation", "Observations": "assimilation",
-    "HighResHead": "highres", "decode_highres": "highres", "train_highres": "highres",
-}
-
-#: Subpackage entry points: ``naturev1.physics_forecast`` etc. resolve lazily to these modules.
-_LAZY_SUB = {"physics_forecast": "cyclone", "TEACHERS": "distill.catalog", "train_distillation": "distill.train",
-             "ArchiveTeacher": "distill.sources"}
-
-
-def __getattr__(name):
-    module = _LAZY.get(name) or _LAZY_SUB.get(name)
-    if module is None:
-        raise AttributeError(f"module 'naturev1' has no attribute {name!r}")
-    import importlib
-
-    value = getattr(importlib.import_module(f".{module}", __name__), name)
-    globals()[name] = value
-    return value
-__author__ = "Nathan"
-__all__ = [
-    "CORPORA", "RI_THRESHOLDS_KT", "WIND_RADII_THRESHOLDS_KT", "EyewallHead", "RapidIntensificationHead",
-    "Track", "apply_ema", "augment_batch", "autotune_batch_size", "benchmark_steps", "catalogue",
-    "device_report", "focal_bce", "format_plan", "masked_gaussian_nll", "next_state_targets",
-    "open_weatherbench", "parse_hurdat2", "rapid_intensification", "rotate_longitude", "split_by_storm",
-    "training_plan", "CachedERA5", "ERA5Window", "corpus_scale", "era5_source_grid", "era5_splits",
-    "materialise", "normalization", "Normalizer", "equiangular_weights", "era5_loader",
-    "from_pretrained", "push_to_hub", "save_for_hub",
-    "Plan", "Choice", "resolve_all", "resolve_variables", "resolve_staging",
-    "resolve_precision", "resolve_batch", "with_retry", "ensure_packages", "install_packages",
-    "ChannelRoles", "StateStepper", "channel_roles", "channel_loss_weights", "conserve_mass",
-    "fair_crps", "solar_forcing", "spread_skill_ratio", "state_forecast", "state_rollout_loss",
-    "tendency_std", "toa_accumulated", "toa_flux", "STATIC_VARIABLES", "FORCING_VARIABLES",
-    "HEADLINE_STATE_FIELDS", "score_state", "train_state_rollout", "lead_track_points",
-    "launch", "follow", "progress", "status", "stop", "HubMirror", "session_started",
-    "area_weights", "TRACKED_HEADS", "STORM_STATE_FEATURES", "storm_feature_bank", "storm_scorecard",
-    "storm_state_vector", "train_storm_heads", "calibration_report", "fit_feature_monitor",
-    "fit_probability_calibration", "stormsat",
-    "STORM_ENVIRONMENT_FEATURES", "TRACK_MEMBERS", "BETA_DRIFT_MS", "advect", "describe_environment",
-    "extrapolation_track", "steering_track", "storm_environment", "consensus_track", "describe_consensus",
-    "fit_track_consensus", "track_members",
-    "preflight", "format_preflight", "PreflightError", "TrainingWatchdog", "check_forecast",
-    "check_grid_alignment", "check_weights", "check_normalization", "check_device_agreement",
-    "check_environment", "responds_to_input", "PHYSICAL", "Bounds",
-    "RolloutSchedule", "rollout_loss", "rollout_forecast", "reinject", "advance_calendar",
-    "field_to_channel", "drift_report",
-    "PRESSURE_LEVELS", "UPPER_VARIABLES", "SURFACE_EXTRAS", "HEADLINE_LEVELS", "channel_names",
-    "headline_channels", "open_weatherbench_levels", "read_levels", "upper_air_report",
-    "volume_coords", "volume_grid",
-    "HEADLINE", "Score", "Scorecard", "ScoredField", "scoring_fields", "score_model", "latitude_weights", "weighted_rmse",
-    "weighted_acc", "persistence_forecast", "climatology_forecast", "build_climatology", "FIELD_DIMS", "read_block", "expand_variables", "lead_offsets", "GridCollate",
-    "SURFACE_FIELDS", "WEATHER_TYPES", "CheckpointManager", "NatureConfig", "NatureV1", "SatelliteScene",
-    "TrainSettings", "Trainer", "TrainingState", "build_forecast", "calendar_features", "decode_landfall",
-    "decode_point_forecast", "decode_track", "decode_eyewall", "decode_rapid_intensification", "fetch_latest", "fixed_grid_to_latlon", "footprint_area_km2",
-    "latest_scene_keys", "load_for_inference", "nearest_point", "normalize_channels", "scene_from_netcdf",
-    "total_loss", "track_mixture_nll", "watch", "StormWindow", "StormTargets",
-    "pair_tracks_with_reanalysis", "format_pairing",
-    # 0.12, loaded on first use (the satellite networks need ihelix 0.6; nothing else does)
-    *sorted(_LAZY), *sorted(_LAZY_SUB),
-]

naturev1/_pipeline.py

@@ -1,772 +0,0 @@
-# ruff: noqa
-# The whole training pipeline -- the same code as colab_naturev1.py, packaged so naturev1.launch() can run
-# it as a background process that survives a dropped connection. Importing it would start training.
-if __name__ not in ("__main__", "__naturev1_pipeline__"):
-    raise ImportError("naturev1._pipeline is the training pipeline itself; start it with naturev1.launch()")
-
-# ═══════════════════════════════════════════════════════════════════════════════════════════════════
-#  NatureV1 0.11.0 — the whole thing in one cell. Pure Python: marimo, Colab, Jupyter or a plain script.
-#
-#  Paste and run. It installs what it needs, stages the data, builds the 89M-parameter model, trains it
-#  in stages, scores itself against persistence and climatology, and only publishes if it earned it.
-#
-#  With BACKGROUND = True (the default) the run happens in a supervised process on the machine itself:
-#  it keeps going if the wifi drops or the notebook closes, and it restarts itself from its last
-#  checkpoint if it crashes, runs out of GPU memory, or stalls. The cell then stays running as a live
-#  window on it -- every log line as it happens, a proof-of-life line every minute when the run is
-#  quiet, a status line every ten minutes -- until the run finishes (WATCH_SECONDS = None). Stopping the
-#  cell stops only the window; the run never depends on it. Run the cell again any time to reopen it.
-#
-#  If it stops for any reason -- a crash, a reboot, naturev1.stop(), the supervisor giving up -- just run
-#  this cell again: every stage continues from its last checkpoint (saved every minute, a snapshot every
-#  30 minutes, and a second copy in BACKUP_DIR). naturev1.progress() shows where it will continue from.
-#
-#  ON A HOSTED NOTEBOOK (molab, Colab): the run survives the notebook, but not the machine. molab ends a
-#  session after 12 hours, or after 90 idle minutes, and wipes its disk. So, with HF_TOKEN set, everything
-#  expensive is mirrored to HF_REPO as soon as it exists: the staged ERA5 (once, in the background), the
-#  checkpoints (every 10 minutes, and once more when the session is told to stop), the storm feature
-#  banks, the remembered batch size. A new session pulls them back in minutes instead of rebuilding them:
-#  the download does not start over, training resumes where the last session stopped. On molab: set
-#  HF_TOKEN, keep this tab open (the cell staying active is what keeps the notebook from being idle), and
-#  when the 12 hours are up, open a new session and run this cell again.
-#
-#  0.9: the hurricane heads read the storm's physical environment -- deep-layer steering, 200-850 hPa
-#  shear, mid-level moisture, ocean temperature -- computed from the model's own atmosphere, plus a
-#  wider 1000 km pool. The track head predicts the residual from a physics-only steering track, and the
-#  forecast is a multi-model consensus of learned track, steering track and extrapolation, weighted per
-#  lead on held-out seasons. The scorecard shows every member, so you can see which one earns its place.
-#
-#  0.11: stage three -- what the satellite sees. Storm-centred infrared (HURSAT-B1 to 2016, GridSat-B1
-#  after, GOES band 13 live) feeds a small branch into the hurricane heads, aimed at intensity, which a
-#  1.5-degree reanalysis cannot see. It is fine-tuned with the backbone frozen and can never end worse on
-#  held-out storms than the model it started from. Then, from the red team: landfall and rapid-
-#  intensification probabilities are calibrated on held-out seasons, an input monitor marks forecasts
-#  from inputs unlike training as untrustworthy, the forecast can no longer state impossible structure,
-#  and the rollout's tendency statistics ship with the weights. Stages already trained are loaded, not
-#  redone: a finished 0.10 run goes straight to stage three.
-# ═══════════════════════════════════════════════════════════════════════════════════════════════════
-
-BACKGROUND    = True      # supervised background run: survives disconnects, restarts on crash or stall
-STALL_MINUTES = 30        # background: restart a run that shows no progress for this long (12 while downloading)
-WATCH_SECONDS = None      # None: this cell stays running as a live window until the run finishes; or seconds
-MIRROR        = True      # mirror staged data, checkpoints and banks to HF_REPO (needs HF_TOKEN); see above
-
-RUN_PRETRAIN  = True      # stage one: every channel at every lead, on ERA5 reanalysis
-RUN_ROLLOUT   = True      # stage 1b: the whole atmosphere rolled forward 12 steps, CRPS ensemble
-RUN_STORMS    = True      # stage two: hurricane heads on HURDAT2, backbone frozen
-RETRAIN_STORMS = False    # stage two: train the heads again even if a stage-two checkpoint exists
-RUN_SATELLITE = True      # stage three: storm-centred infrared satellite, then calibration and the monitor
-RETRAIN_SATELLITE = False # stage three: train again even if a stage-three checkpoint exists
-RUN_SCORE     = True      # WeatherBench-style scorecards against persistence and climatology
-RUN_HINDCAST  = True      # forecast a held-out hurricane from its real analysis; compare with truth
-RUN_PUBLISH   = False     # push to the Hub -- only if it beats persistence somewhere
-RUN_FORECAST  = False     # live GOES forecast (refused while the satellite path is untrained)
-RUN_WATCHER   = False     # then re-forecast every hour
-
-STAGE_YEARS   = 5         # training years staged to local disk, ~7.5 GB each at 89 channels
-VAL_YEARS     = 1         # held-out years staged too, so validation and scoring are not network-bound
-EPOCHS        = 8         # passes over the staged years in stage one
-BATCH         = None      # None: find the largest batch that fits once, then remember it; or a number
-MAX_BATCH     = 16        # ceiling on the batch search: host RAM, not VRAM, is the limit above this
-WORKERS       = 4         # data-loading processes
-ROLLOUT_STEPS = 12        # longest rollout trained: 12 x 6 h = 72 h, GraphCast's curriculum
-ROLLOUT_TRAIN = 4_000     # optimizer steps of rollout training (the log prints the time per step)
-MEMBERS       = 2         # CRPS ensemble members; 1 = deterministic Gaussian training
-STORM_FIRST_SEASON = 1979 # the satellite era; earlier best-track intensities are much less reliable
-HINDCAST      = ("DORIAN", 2019)       # a held-out storm: 2019 is never trained on
-STORM         = (24.6, -78.2)          # live forecast: current storm centre (lat, lon)
-CITY          = (25.77, -80.19)        # live forecast: somewhere you want a local forecast
-HF_REPO       = "CorxLabs/NatureV1-500"
-HF_TOKEN      = ""        # a write token, to publish and mirror checkpoints; or set the HF_TOKEN env var
-DATA_DIR      = None      # None: /content on Colab, ~/naturev1_data elsewhere; or any folder with room
-BACKUP_DIR    = None      # second copy of every checkpoint. None: ~/naturev1_backup; best on another disk;
-                          # "" turns it off
-
-# ═══ 0 ═══ install ═════════════════════════════════════════════════════════════════════════════════
-# Standard library only, before numpy or torch are imported: pip may upgrade numpy while satisfying
-# zarr or gcsfs, and a numpy that changes under an imported torch fails far from here.
-import importlib
-import importlib.metadata
-import importlib.util
-import os
-import shutil
-import subprocess
-import sys
-
-os.environ.setdefault("GRPC_VERBOSITY", "ERROR")   # the cloud client logs every DataLoader fork otherwise
-# Let the GPU allocator grow segments instead of fragmenting them. Training at batch 8 fills a 96 GB card
-# to within ~130 MB, and without this the allocator has to flush and retry. Only takes effect if torch
-# has not touched the GPU yet in this kernel -- restart the kernel for it to apply.
-os.environ.setdefault("PYTORCH_CUDA_ALLOC_CONF", "expandable_segments:True")
-
-
-def _halt(message, kind="danger"):
-    """
-    End the cell here, on purpose. Only kind="danger" is an error. marimo shows the message as a
-    coloured note instead of a traceback, Jupyter and Colab show it without one, and a plain script
-    exits with status 0 for "success" and 1 for anything else -- which is what the supervisor of a
-    background run reads, so a run stopped part-way is resumed and a finished one is not.
-    """
-    marimo = sys.modules.get("marimo")
-    if marimo is not None and getattr(marimo, "running_in_notebook", lambda: False)():
-        try:
-            note = marimo.callout(marimo.plain_text(message), kind=kind)
-        except Exception:
-            note = None
-            print(message)
-        marimo.stop(True, note)
-    ipython = sys.modules.get("IPython")
-    if kind != "danger" and ipython is not None and getattr(ipython, "get_ipython", lambda: None)() is not None:
-        class Halted(Exception):
-            def _render_traceback_(self):
-                return []                         # the message printed above, and no traceback
-        print(message)
-        raise Halted("the cell stopped here on purpose -- the message is above")
-    if kind == "success":
-        print(message)
-        raise SystemExit(0)
-    raise SystemExit(message)
-
-
-# 0.11 is installed from the project's GitHub branch until it is on PyPI.
-_NEEDED = {"naturev1": ("naturev1[all] @ git+https://github.com/Wisk-inc/transformers"
-                        "@claude/linear-context-architecture-a35c6h#subdirectory=natureweather", (0, 11, 0)),
-           "ihelix": ("ihelix>=0.5.1", (0, 5, 1))}
-
-
-def _version(module):
-    try:
-        return tuple(int(p) for p in importlib.metadata.version(module).split(".")[:3])
-    except Exception:
-        return None
-
-
-_missing = [req for mod, (req, low) in _NEEDED.items()
-            if importlib.util.find_spec(mod) is None or (_version(mod) or (0,)) < low]
-if _missing:
-    print(f"installing: {' '.join(_missing)}")
-    _loaded = {name: getattr(sys.modules.get(name), "__version__", None) for name in ("numpy", "torch")}
-    _tries = ([("uv", ["uv", "pip", "install", "--python", sys.executable, "--upgrade", *_missing])]
-              if shutil.which("uv") else [])
-    _pip = [sys.executable, "-m", "pip", "install", "--upgrade"]
-    _tries += [("pip, fresh index", [*_pip, "--no-cache-dir", "--index-url", "https://pypi.org/simple", *_missing]),
-               ("pip, no cache", [*_pip, "--no-cache-dir", *_missing]),
-               ("pip", [*_pip, *_missing])]
-    for _label, _command in _tries:
-        try:
-            subprocess.check_call(_command)
-            print(f"installed via {_label}")
-            break
-        except (subprocess.CalledProcessError, FileNotFoundError):
-            print(f"  {_label} failed, trying the next way")
-    else:
-        _halt("could not install; add these in your package manager, then re-run: " + " ".join(_missing))
-    importlib.invalidate_caches()
-    # A restart is needed only if an old copy is already in memory, or pip moved numpy/torch under us.
-    _stale = [m for m in _NEEDED if m in sys.modules]
-    for _name, _was in _loaded.items():
-        try:
-            if _was and importlib.metadata.version(_name) != _was:
-                _stale.append(f"{_name} {_was}")
-        except importlib.metadata.PackageNotFoundError:
-            pass
-    if _stale:
-        _halt(f"installed. {', '.join(_stale)} was already loaded in this kernel: RESTART THE KERNEL, then run "
-              "this cell again. (A background run that is already training is not affected.)", kind="warn")
-
-if HF_TOKEN:
-    os.environ["HF_TOKEN"] = HF_TOKEN
-# Every checkpoint is also copied here, so losing or damaging the data folder does not lose the run.
-os.environ["NATUREV1_BACKUP_DIR"] = (os.path.expanduser("~/naturev1_backup") if BACKUP_DIR is None
-                                     else os.path.expanduser(BACKUP_DIR))
-
-if BACKGROUND and not os.environ.get("NATUREV1_BACKGROUND_CHILD"):
-    # Hand this same pipeline, with these settings, to a supervised process on this machine, and stop
-    # here: the notebook only starts and watches it. The GPU is never touched from the notebook.
-    # Imported under a private name: marimo lets a name be defined by only one cell, and this way any
-    # other cell can still `import naturev1` to call naturev1.follow() or naturev1.stop().
-    import naturev1 as _naturev1
-
-    _SETTINGS = {name: globals()[name] for name in (
-        "RUN_PRETRAIN", "RUN_ROLLOUT", "RUN_STORMS", "RETRAIN_STORMS", "RUN_SATELLITE", "RETRAIN_SATELLITE",
-        "RUN_SCORE", "RUN_HINDCAST", "RUN_PUBLISH",
-        "RUN_FORECAST", "RUN_WATCHER", "STAGE_YEARS", "VAL_YEARS", "EPOCHS", "BATCH", "MAX_BATCH", "WORKERS",
-        "ROLLOUT_STEPS", "ROLLOUT_TRAIN", "MEMBERS", "STORM_FIRST_SEASON", "HINDCAST", "STORM", "CITY",
-        "HF_REPO", "HF_TOKEN", "DATA_DIR", "BACKUP_DIR", "MIRROR")}
-    _was_running = _naturev1.status(DATA_DIR) is not None
-    _naturev1.launch(directory=DATA_DIR, stall_minutes=STALL_MINUTES, **_SETTINGS)
-    if _was_running:
-        _naturev1.progress(DATA_DIR)                 # what the run that is already going has done so far
-    # A fresh run: wait for its first lines. Then show the log live for a while, so the cell ends with
-    # the run visibly moving rather than with a snapshot that looks frozen.
-    _naturev1.follow(lines=25, directory=DATA_DIR, wait=90, watch=WATCH_SECONDS)
-    if _naturev1.status(DATA_DIR) is None:
-        _naturev1.progress(DATA_DIR)
-        _halt("The run has ended -- the last lines above say whether it finished or stopped. If it finished, "
-              "the scorecards and the hindcast are above. If it stopped, run this cell again: it continues "
-              "from the last checkpoint, pulling data, checkpoints and banks back from the Hub mirror if this "
-              "machine's disk was wiped.", kind="success")
-    _halt("NatureV1 is running in the background; this cell was its window and has closed -- the run has "
-          "NOT stopped. Nothing in this notebook can stop it except naturev1.stop().\n"
-          "To reopen the window: run this cell again (it will not start a second run), or in any cell\n"
-          "    import naturev1; naturev1.follow(watch=None)\n"
-          "If the run ever does stop, run this cell again: it continues from the last checkpoint, pulling "
-          "data, checkpoints and banks back from the Hub mirror if this machine's disk was wiped.\n"
-          "naturev1.progress() shows each stage's checkpoint, its age, and its backup.",
-          kind="success")
-
-# ═══ 1 ═══ imports, paths, hardware ══════════════════════��═════════════════════════════════════════
-import datetime as dt
-import json
-
-import numpy as np
-import torch
-from ihelix import FieldGrid, Geometry, fibonacci_sphere
-from naturev1 import (HEADLINE_STATE_FIELDS, CachedERA5, CheckpointManager, ERA5Window, HubMirror, NatureConfig,
-                      NatureV1, RolloutSchedule, StateStepper, Trainer, TrainSettings, autotune_batch_size,
-                      benchmark_steps, build_climatology, build_forecast, calendar_features, catalogue,
-                      channel_loss_weights, check_forecast, check_grid_alignment, check_normalization,
-                      check_weights, corpus_scale, describe_environment, device_report, era5_loader,
-                      era5_source_grid, era5_splits, expand_variables, extrapolation_track, fetch_latest,
-                      format_pairing, format_plan, format_preflight, lead_offsets, masked_gaussian_nll,
-                      materialise, normalize_channels, open_weatherbench_levels, pair_tracks_with_reanalysis,
-                      parse_hurdat2, preflight, push_to_hub, rapid_intensification, resolve_all,
-                      responds_to_input, scene_from_netcdf, score_model, score_state, scoring_fields,
-                      split_by_storm, spread_skill_ratio, state_forecast, steering_track, storm_environment,
-                      storm_feature_bank, storm_scorecard, storm_state_vector, train_state_rollout,
-                      train_storm_heads, training_plan, upper_air_report, watch)
-from naturev1.besttrack import download
-from naturev1.checkpoint import TrainingState
-from naturev1.era5 import _target_index
-from naturev1.storms import calibration_report, fit_feature_monitor, fit_probability_calibration
-from naturev1.stormsat import (IBTRACS_NA_URL, GridSatArchive, HursatArchive, describe_patch, encode_bt,
-                               ibtracs_atcf_map, satellite_bank)
-from naturev1.safeio import atomic_write_text, read_json
-
-DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
-COLAB_DRIVE = "/content/drive/MyDrive"
-DATA_DIR = DATA_DIR or ("/content" if os.path.isdir("/content") else os.path.expanduser("~/naturev1_data"))
-CKPT_DIR = (f"{COLAB_DRIVE}/naturev1_ckpt" if os.path.isdir(COLAB_DRIVE)       # Drive outlives the VM
-            else os.path.join(DATA_DIR, "naturev1_ckpt"))
-os.makedirs(DATA_DIR, exist_ok=True)
-os.makedirs(CKPT_DIR, exist_ok=True)
-CACHE, VAL_CACHE, STATS = (os.path.join(DATA_DIR, name) for name in ("era5.npy", "era5_val.npy", "stats.json"))
-# Everything expensive goes to the Hub as soon as it exists and comes back at the start of a new session,
-# so a wiped disk costs minutes, not hours. Off without a repo or token; see the header.
-mirror = HubMirror(HF_REPO if MIRROR else None, token=HF_TOKEN or None)
-
-
-def banner(text):
-    print(f"\n{'═' * 99}\n  {text}\n{'═' * 99}")
-
-
-banner("HARDWARE")
-print(device_report())
-print(f"data {DATA_DIR} | checkpoints {CKPT_DIR}\n{mirror.describe()}")
-
-# ═══ 2 ═══ data: 13 pressure levels + surface + static, resolved against this machine ══════════════
-banner("DATA — ERA5 (WeatherBench 2), surface and 13 pressure levels")
-ERA5, SURFACE, UPPER = open_weatherbench_levels()
-LEVELS = [int(x) for x in ERA5.level.values]
-SRC, LAT, LON = era5_source_grid(ERA5)
-plan = resolve_all(ERA5, tuple(SURFACE) + tuple(UPPER), LEVELS, STAGE_YEARS + VAL_YEARS, SRC.num_points,
-                   layers=17, batch=MAX_BATCH, precision="bf16", path=DATA_DIR,
-                   staged=(CACHE, VAL_CACHE))      # data already on disk counts as room, not as used
-print(plan.summary())
-R = plan.resolved
-CHANNELS = expand_variables(ERA5, R["variables"], R["levels"])
-WIDTH = len(CHANNELS) + 7                         # room for observation-mask channels, zero-padded
-print(f"\n{upper_air_report(SURFACE, UPPER, LEVELS)}")
-assert not check_weights(SRC), check_weights(SRC)  # poles present, not deleted by cos(latitude)
-
-OFFSETS, SPLITS = lead_offsets((6, 12, 18, 24, 36, 48, 72, 96, 120)), era5_splits(ERA5)
-TRAIN_STEPS = max(R["years"] - VAL_YEARS, 1) * 1460
-VAL_STEPS = VAL_YEARS * 1460
-common = dict(history=6, lead_steps=OFFSETS, variables=tuple(R["variables"]), levels=R["levels"], channels=WIDTH)
-for name, index in SPLITS.items():
-    print(f"  {name:5} {str(ERA5.time.values[index[0]])[:10]} -> {str(ERA5.time.values[index[-1]])[:10]}")
-print("split by TIME: weather is autocorrelated for days, so a random split leaks the answer.")
-
-mirror.pull(STATS, "staging/stats.json")             # the normalisation statistics, from an earlier session
-stream = ERA5Window(ERA5, indices=SPLITS["train"], stats_cache=STATS, **common)
-mirror.push(STATS, "staging/stats.json")
-print(f"\n{stream.normalizer.report()}")
-print(f"\n{corpus_scale(ERA5, tuple(R['variables']))}\n\n{catalogue()}")
-
-if R["streaming"]:
-    print("\nnot enough disk to stage: streaming from the network (~100x slower per window)")
-    train_ds, roll_ds = stream, ERA5Window(ERA5, indices=SPLITS["train"], stats_cache=STATS,
-                                           state_steps=ROLLOUT_STEPS, **common)
-    val_ds = ERA5Window(ERA5, indices=SPLITS["val"], augment=False, stats_cache=STATS,
-                        state_steps=ROLLOUT_STEPS, **common)
-else:
-    # Always called, and never downloads twice: it returns at once when what is on disk already covers
-    # the request, copies from disk what it can when the request grows, and resumes a download that died.
-    TRAIN_SPAN, VAL_SPAN = SPLITS["train"][-TRAIN_STEPS:], SPLITS["val"][:VAL_STEPS]
-    # A staging an earlier session already made comes back from the Hub in minutes; it is pushed there,
-    # in the background, the first time it is complete. Then materialise() reuses, grows or resumes it.
-    mirror.pull_staging(CACHE, "staging/era5", CHANNELS, TRAIN_SPAN)
-    mirror.pull_staging(VAL_CACHE, "staging/era5_val", CHANNELS, VAL_SPAN)
-    materialise(ERA5, TRAIN_SPAN, CACHE, variables=tuple(R["variables"]),
-                levels=R["levels"], normalizer=stream.normalizer, workers=8)
-    materialise(ERA5, VAL_SPAN, VAL_CACHE, variables=tuple(R["variables"]),
-                levels=R["levels"], normalizer=stream.normalizer, workers=8)
-    mirror.push_staging(CACHE, "staging/era5")
-    mirror.push_staging(VAL_CACHE, "staging/era5_val")
-    train_ds = CachedERA5(CACHE, history=6, lead_steps=OFFSETS, channels=WIDTH, augment=True,
-                          restrict_to=TRAIN_SPAN)
-    roll_ds = CachedERA5(CACHE, history=6, lead_steps=OFFSETS, channels=WIDTH, augment=True,
-                         state_steps=ROLLOUT_STEPS, restrict_to=TRAIN_SPAN)
-    val_ds = CachedERA5(VAL_CACHE, history=6, lead_steps=OFFSETS, channels=WIDTH, augment=False,
-                        state_steps=ROLLOUT_STEPS, restrict_to=VAL_SPAN)
-print(f"\ntrain {len(train_ds):,} windows | validate on {len(val_ds):,} held-out windows")
-
-sample = train_ds[0]["analysis"]
-for problem in (check_grid_alignment(SRC, sample[-1, :, train_ds.variables.index("2m_temperature")])
-                + check_normalization(sample, "analysis")):
-    _halt(f"DATA PROBLEM: {problem}")
-print("data ok: samples land where the grid says, no spike channels")
-
-# ═══ 3 ═══ what each channel IS — decides what a rollout does with it ══════════════════════════════
-stepper = StateStepper.build(roll_ds, input_channels=WIDTH, grid=SRC, samples=64)
-print(f"\nchannel roles:\n{stepper.roles.describe()}")
-WEIGHTS = channel_loss_weights(train_ds.variables, WIDTH)
-
-# ═══ 4 ═══ the model ═══════════════════════════════════════════════════════════════════════════════
-banner("MODEL")
-CFG = NatureConfig(
-    analysis_channels=WIDTH, satellite_channels=6, environment_channels=8,
-    hidden_size=512, num_layers=17, num_heads=8, num_kv_heads=4, head_dim=64, intermediate_size=2048,
-    latent_points=4096, min_radius_km=120.0, max_radius_km=1600.0, history_frames=6,
-    lead_times_hours=(6, 12, 18, 24, 36, 48, 72, 96, 120), track_modes=6,
-    state_channels=stepper.roles.num_prognostic,        # predict and evolve the whole atmosphere
-    noise_dim=32 if MEMBERS > 1 else 0)                 # per-member noise for the CRPS ensemble
-model = NatureV1(CFG, fibonacci_sphere(CFG.latent_points, num_neighbours=CFG.latent_neighbours,
-                                       cluster_size=CFG.latent_cluster)).to(DEVICE)
-model.gradient_checkpointing_enable(True)
-stepper.grid = SRC.to(DEVICE)
-print(f"NatureV1 {model.num_parameters()/1e6:.2f}M parameters on {DEVICE}; state head over "
-      f"{CFG.state_channels} channels; {MEMBERS}-member ensemble")
-print(format_preflight(preflight(model=model, dataset=train_ds, grid=SRC, strict=True)))
-
-
-def restore(*stages):
-    """Load the newest checkpoint of the first stage that has one -- locally, else from the Hub."""
-    for stage in stages:
-        manager = CheckpointManager(f"{CKPT_DIR}/{stage}", repo_id=HF_REPO)
-        manager.fetch_from_hub()
-        if manager.load(model, map_location=DEVICE) is not None:
-            return stage
-    return None
-
-
-# ═══ 5 ═══ the largest batch that fits, and what the run costs ═════════════════════════════════════
-banner("BENCHMARK — largest batch that fits, and what the run costs")
-
-
-def make_step(batch_size):
-    items = [train_ds[i] for i in range(batch_size)]
-    batch = {k: torch.stack([x[k] for x in items]).to(DEVICE) for k in ("analysis", "calendar", "field_target", "field_mask")}
-
-    def step():
-        with torch.autocast(DEVICE, dtype=torch.bfloat16, enabled=DEVICE == "cuda"):
-            out = model(analysis=batch["analysis"], analysis_grid=SRC, calendar=batch["calendar"], output_grid=SRC)
-            loss = masked_gaussian_nll(out["field_mean"], out["field_log_var"],
-                                       torch.where(batch["field_mask"] > 0, batch["field_target"], torch.nan))
-        loss.backward()
-        model.zero_grad(set_to_none=True)
-    return step
-
-
-# The search is done once and remembered: repeating it on every restart costs minutes, pushes the card
-# to the edge of its memory each time, and could pick a different batch -- a different run -- each time.
-BATCH_FILE = os.path.join(CKPT_DIR, "batch.json")
-mirror.pull(BATCH_FILE, "staging/batch.json")
-REMEMBERED = read_json(BATCH_FILE, default={}) if BATCH is None else {}   # a damaged file is searched again
-if REMEMBERED.get("batch"):
-    BATCH, SPEED = int(REMEMBERED["batch"]), float(REMEMBERED.get("samples_per_second", 0.0))
-    print(f"batch {BATCH}, found on an earlier run (delete {BATCH_FILE} to search again)")
-else:
-    if BATCH is None:
-        BATCH = min(autotune_batch_size(make_step, start=1, target_fraction=0.85), MAX_BATCH)
-    MARK = benchmark_steps(make_step(BATCH), BATCH, warmup=1, iterations=10, gradient_checkpointing=True)
-    SPEED = MARK.samples_per_second
-    atomic_write_text(BATCH_FILE, json.dumps({"batch": BATCH, "samples_per_second": SPEED}))
-    mirror.push(BATCH_FILE, "staging/batch.json")
-    print(f"batch {BATCH} | {MARK}")
-if SPEED:
-    print(format_plan(training_plan(SPEED, corpus_samples=len(train_ds), epochs=EPOCHS,
-                                    watts=600.0, electricity_per_kwh=0.15, cloud_per_hour=2.50)))
-if DEVICE == "cuda":
-    torch.cuda.empty_cache()                      # hand back what the search held before training starts
-loader = era5_loader(train_ds, batch_size=BATCH, num_workers=WORKERS, analysis_grid=SRC, output_grid=SRC,
-                     prefetch_factor=2)
-val_loader = era5_loader(val_ds, batch_size=BATCH, num_workers=WORKERS, shuffle=False, analysis_grid=SRC,
-                         output_grid=SRC, prefetch_factor=2)
-
-# ═══ 6 ═══ stage one — every channel, every lead ═══════════════════════════════════════════════════
-if RUN_PRETRAIN:
-    banner("STAGE ONE — pretraining on reanalysis")
-    trainer = Trainer(model, TrainSettings(
-        stage="pretrain", learning_rate=3e-4, warmup_steps=1000,
-        precision=R["precision"], max_steps=int(len(train_ds) * EPOCHS / BATCH),
-        checkpoint_dir=f"{CKPT_DIR}/stage1", checkpoint_seconds=60, hub_repo=HF_REPO, hub_push_seconds=600,
-        ema_decay=0.0, log_every=5, val_every=500, val_batches=32), device=DEVICE)
-    trainer.resume()
-    trainer.fit(loader, epochs=EPOCHS, val_loader=val_loader)
-    if trainer.interrupted:
-        # Stopped part-way: checkpointed, and the next stage must not start from a half-trained model.
-        _halt("stage one stopped and checkpointed -- run again to resume it where it left off", kind="warn")
-    print("held-out falling = learning; held-out rising while training falls = memorising.")
-
-# ═══ 7 ═══ stage 1b — the whole atmosphere, rolled forward on its own forecasts ════════════════════
-if RUN_ROLLOUT:
-    banner(f"ROLLOUT — {ROLLOUT_STEPS}-step full-state training, {MEMBERS}-member CRPS ensemble")
-    if not RUN_PRETRAIN and restore("stage1") is None:
-        print("!! no stage-one checkpoint: rolling out an untrained backbone. Set RUN_PRETRAIN = True.")
-    steps = ROLLOUT_TRAIN
-    roll_loader = era5_loader(roll_ds, batch_size=max(BATCH // 2, 1), num_workers=WORKERS,
-                              analysis_grid=SRC, output_grid=SRC, prefetch_factor=2)
-    train_state_rollout(
-        model, roll_loader, stepper, max_steps=steps,
-        schedule=RolloutSchedule(start_step=max(steps // 10, 1), ramp_steps=max(steps // 2, 1),
-                                 max_steps=ROLLOUT_STEPS),
-        channel_weights=WEIGHTS, members=MEMBERS, precision=R["precision"],
-        checkpoint_dir=f"{CKPT_DIR}/rollout", hub_repo=HF_REPO, log_every=25)
-
-# ═══ 8 ═══ stage two — hurricane heads, on the frozen backbone ═════════════════════════════════════
-banner("STAGE TWO — HURDAT2 best tracks")
-tracks = parse_hurdat2(download("https://www.nhc.noaa.gov/data/hurdat/hurdat2-1851-2024-040425.txt",
-                                os.path.join(DATA_DIR, "hurdat2.txt")))
-print(f"HURDAT2: {len(tracks):,} storms, {sum(len(t) for t in tracks):,} points, "
-      f"{sum(int(t.landfall.sum()) for t in tracks):,} landfalls")
-walk = rapid_intensification(tracks, threshold_kt=30.0)
-print(f"rapid intensification: {walk['positives']:,} of {walk['eligible']:,} eligible = "
-      f"{100 * walk['base_rate']:.2f}%  (an always-'no' classifier scores {100 - 100 * walk['base_rate']:.0f}%)")
-GROUPS = split_by_storm([t for t in tracks if t.year >= STORM_FIRST_SEASON])
-STORE_TIMES = ERA5.time.values.astype("datetime64[s]").astype(np.int64)
-
-
-def paired(which):
-    starts, targets, report = pair_tracks_with_reanalysis(GROUPS[which], STORE_TIMES, OFFSETS, history=6)
-    return starts, targets, report
-
-
-def storm_banks():
-    """The frozen backbone's features for every storm sample: built once, cached, mirrored."""
-    (tr_starts, tr_targets, tr_report), (va_starts, va_targets, va_report) = paired("train"), paired("validation")
-    print(f"\n{format_pairing(tr_report)}")
-    print(f"validation: {va_report['paired']:,} samples from {va_report['storms']} unseen storms "
-          f"(seasons 2017/2019/2021)")
-    print("\nreading each storm's reanalysis once and running the frozen backbone over it "
-          "(cached; resumes if interrupted):")
-    for _name in ("storm_bank_train", "storm_bank_val"):
-        mirror.pull(f"{CKPT_DIR}/{_name}.pt", f"checkpoints/{_name}.pt")   # rebuilt anyway if the backbone changed
-    train = storm_feature_bank(model, ERA5, stream, tr_starts, tr_targets, SRC,
-                               cache=f"{CKPT_DIR}/storm_bank_train.pt", precision=R["precision"])
-    val = storm_feature_bank(model, ERA5, stream, va_starts, va_targets, SRC,
-                             cache=f"{CKPT_DIR}/storm_bank_val.pt", precision=R["precision"])
-    for _name in ("storm_bank_train", "storm_bank_val"):
-        mirror.push(f"{CKPT_DIR}/{_name}.pt", f"checkpoints/{_name}.pt")
-    return train, val, tr_targets, va_targets
-
-
-bank_train = bank_val = None
-if RUN_STORMS:
-    # A finished stage two is loaded *before* the banks are built: its backbone is the one they were
-    # built with, so they are reused rather than rebuilt from whatever checkpoint the Hub has for 1b.
-    resumed = None if RETRAIN_STORMS else restore("stage2")
-    if resumed is None and not (RUN_PRETRAIN or RUN_ROLLOUT) and restore("rollout", "stage1") is None:
-        _halt("no pretrained backbone found. Freezing an untrained one would fine-tune the storm "
-              "heads on noise -- set RUN_PRETRAIN = True.")
-    bank_train, bank_val, tr_targets, va_targets = storm_banks()
-    if resumed is not None:
-        print("\nstage two is already trained: its checkpoint is loaded (RETRAIN_STORMS = True trains it again)")
-    else:
-        history = train_storm_heads(model, bank_train, bank_val, epochs=300,
-                                    patience=25, checkpoint_dir=f"{CKPT_DIR}/stage2", hub_repo=HF_REPO)
-        best = min(history, key=lambda h: h["val"])
-        banner("SCOREBOARD — is it generalising, or memorising?")
-        print(f"best epoch {best['epoch']}: held-out {best['val']:.4f}  training {best['train']:.4f}  "
-              f"gap {best['val'] - best['train']:+.4f}   (a large positive gap = memorised the training storms)")
-    print(f"\nheld-out storms, seasons never trained on:\n{storm_scorecard(model, bank_val, CFG.lead_times_hours)}")
-
-# ═══ 8b ═══ stage three — what the satellite sees ══════════════════════════════════════════════════
-if RUN_SATELLITE:
-    banner("STAGE THREE — storm-centred infrared (HURSAT-B1 to 2016, GridSat-B1 after)")
-    loaded = None if RETRAIN_SATELLITE else restore("stage3")
-    if loaded is None and not RUN_STORMS and restore("stage2") is None:
-        _halt("no trained hurricane heads to build on -- run with RUN_STORMS = True first")
-    if bank_train is None:
-        bank_train, bank_val, tr_targets, va_targets = storm_banks()
-    print("\nstorm-centred infrared for every sample, now and six hours earlier (cached; mirrored):")
-    hursat = HursatArchive(os.path.join(DATA_DIR, "hursat"),
-                           ibtracs_atcf_map(download(IBTRACS_NA_URL, os.path.join(DATA_DIR, "ibtracs.NA.csv"))))
-    gridsat = GridSatArchive()
-    for _name in ("satellite_bank_train", "satellite_bank_val"):
-        mirror.pull(f"{CKPT_DIR}/{_name}.pt", f"checkpoints/{_name}.pt")
-    sat_train = satellite_bank(tr_targets, f"{CKPT_DIR}/satellite_bank_train.pt", hursat, gridsat)
-    sat_val = satellite_bank(va_targets, f"{CKPT_DIR}/satellite_bank_val.pt", hursat, gridsat)
-    for _name in ("satellite_bank_train", "satellite_bank_val"):
-        mirror.push(f"{CKPT_DIR}/{_name}.pt", f"checkpoints/{_name}.pt")
-    shutil.rmtree(os.path.join(DATA_DIR, "hursat"), ignore_errors=True)    # the patches are kept; the archives are not
-    plain_val = dict(bank_val)
-    bank_train["satellite"], bank_val["satellite"] = sat_train, sat_val
-    coverage = float(sat_val["available"][:, 0].float().mean())
-    # The model as it arrives -- stage two, no satellite -- scored first: that is what stage three must beat.
-    before = None if loaded is not None else storm_scorecard(model, plain_val, CFG.lead_times_hours)
-    if loaded is not None:
-        print("\nstage three is already trained: its checkpoint is loaded (RETRAIN_SATELLITE = True trains it again)")
-    elif coverage < 0.3:
-        print(f"\nonly {coverage:.0%} of held-out samples have an image: too few to judge the satellite branch, "
-              "so it is not trained. Calibration and the input monitor still are.")
-    else:
-        history = train_storm_heads(model, bank_train, bank_val, epochs=80, batch_size=128, learning_rate=2e-4,
-                                    satellite_learning_rate=1e-3, augment=True, keep_if_no_better=True,
-                                    patience=15, log_every=5)
-    banner("CALIBRATION, INPUT MONITOR, ROLLOUT STATISTICS")
-    print("probabilities on held-out seasons, each season calibrated without itself:\n"
-          + calibration_report(model, bank_val))
-    fit_probability_calibration(model, bank_val)
-    print(f"\ninput monitor fitted on the training storms: limit {fit_feature_monitor(model, bank_train):.2f}")
-    model.state_tendency.copy_(stepper.tendency.to(model.state_tendency.device))
-    _stage3 = CheckpointManager(f"{CKPT_DIR}/stage3", repo_id=HF_REPO)
-    _stage3.save(model, None, state=TrainingState(step=int(model.trained_heads()["storm_satellite"])),
-                 config=model.config.to_dict(), force=True)
-    _stage3.push_now(TrainingState(step=int(model.trained_heads()["storm_satellite"])))
-    banner("SCOREBOARD — what the satellite adds, on held-out storms")
-    if before is not None:
-        print(f"stage two, before the satellite (the score to beat):\n{before}")
-    else:
-        print(f"stage three with the images withheld:\n{storm_scorecard(model, plain_val, CFG.lead_times_hours)}")
-    print(f"\nstage three, with the satellite ({coverage:.0%} of held-out samples have an image):\n"
-          f"{storm_scorecard(model, bank_val, CFG.lead_times_hours)}")
-
-# ═══ 9 ═══ did it learn? scorecards against persistence and climatology ════════════════════════════
-if not (RUN_PRETRAIN or RUN_ROLLOUT or RUN_STORMS or RUN_SATELLITE):
-    print(f"loaded: {restore('stage3', 'stage2', 'rollout', 'stage1') or 'nothing -- untrained'}")
-print(f"\ntraining record (steps per output; 0 = never trained, never shown as a forecast):\n"
-      f"  {model.trained_heads()}")
-
-_probe_stream = iter(val_loader)
-
-
-def _probe():
-    batch = next(_probe_stream)
-    return {"analysis": batch["analysis"].to(DEVICE), "calendar": batch["calendar"].to(DEVICE)}
-
-
-responds, spread = responds_to_input(model, _probe, SRC)
-print(f"\nresponds to the weather: {responds}  (spread {spread:.2e})")
-
-card = state_card = None
-if RUN_SCORE:
-    banner("SCORECARDS — area-weighted, physical units, identical batches for every baseline")
-    climo = build_climatology(train_ds, np.arange(len(train_ds)), WIDTH, SRC.num_points,
-                              samples=200)
-    batches = 32
-    card = score_model(model, val_loader, SRC, LAT, len(LON), CFG.lead_times_hours,
-                       fields=scoring_fields(train_ds.variables, _target_index(train_ds.variables)),
-                       normalizer=train_ds.normalizer, climatology=climo, max_batches=batches, device=DEVICE)
-    print("surface heads, direct multi-lead:\n" + card.table() + "\n" + card.verdict())
-    state_card = score_state(model, val_loader, stepper, HEADLINE_STATE_FIELDS,
-                             steps=ROLLOUT_STEPS, climatology=climo,
-                             max_batches=batches, precision=R["precision"])
-    print("\nfull-state rollout (Z500 in m2/s2, as WeatherBench 2 reports it):\n"
-          + state_card.table() + "\n" + state_card.verdict())
-    if MEMBERS > 1 and "geopotential@500" in train_ds.variables:
-        batch = {k: (v.to(DEVICE) if torch.is_tensor(v) else v) for k, v in next(iter(val_loader)).items()}
-        lead = min(4, batch["state_target"].shape[1])
-        ensemble = state_forecast(model, batch, stepper, steps=lead, members=max(MEMBERS, 4),
-                                  precision=R["precision"])
-        z500 = train_ds.variables.index("geopotential@500")
-        ratio = spread_skill_ratio(ensemble[:, -1, ..., z500], batch["state_target"][:, lead - 1, :, z500])
-        print(f"\nZ500 +{6 * lead}h ensemble spread/skill {ratio:.2f}   (1.0 calibrated, <1 overconfident)")
-        if ratio < 0.05:
-            print("  no spread yet: the noise path starts at exactly zero and CRPS training grows it.")
-
-# ═══ 10 ═══ hindcast — a held-out hurricane, from its real analysis ════════════════════════════════
-if RUN_HINDCAST:
-    banner(f"HINDCAST — {HINDCAST[0].title()} {HINDCAST[1]}, a season the model never trained on")
-    storm = next((t for t in tracks if t.name.strip().upper() == HINDCAST[0] and t.year == HINDCAST[1]), None)
-    starts, targets, _ = (pair_tracks_with_reanalysis([storm], STORE_TIMES, OFFSETS, history=6)
-                          if storm is not None else ([], [], None))
-    if not len(starts):
-        print("that storm is not in the reanalysis window (1959-2021); pick another in HINDCAST")
-    else:
-        peak = int(np.nanargmax(storm.max_wind_kt))
-        choice = min(range(len(targets)), key=lambda i: abs(targets[i].point - max(peak - 8, 0)))   # ~48 h before peak
-        target = targets[choice].build()
-        window = ERA5Window(ERA5, indices=starts[choice:choice + 1], augment=False, stats_cache=STATS, **common)[0]
-        issued = dt.datetime.fromtimestamp(float(window["valid_time"]), tz=dt.timezone.utc)
-        centre = target["storm_center"].tolist()
-        here = target["storm_center"][None].to(DEVICE)
-        # The storm's environment and the physics-only steering track, from the analysis "now".
-        now = window["analysis"][-1][None].to(DEVICE)
-        environment = storm_environment(now, train_ds.variables, train_ds.normalizer, SRC, here)
-        steer = steering_track(now, train_ds.variables, train_ds.normalizer, SRC, here, CFG.lead_times_hours)
-        print(describe_environment(environment[0]))
-        # The satellite view at issue time and six hours earlier, if stage three has trained that branch.
-        seen = None
-        if model.trained_heads()["storm_satellite"] > 0:
-            from naturev1.stormsat import _earlier_position
-            earlier = _earlier_position(targets[choice])
-            when = np.datetime64(issued.replace(tzinfo=None), "m")
-            wanted = [(when, tuple(centre))] + ([earlier] if earlier is not None else [])
-            images = GridSatArchive().patches(wanted, progress=False)
-            if images[0] is not None:
-                codes = np.zeros((1, 2, *images[0].shape), np.uint8)
-                codes[0, 0] = encode_bt(images[0])
-                if len(images) > 1 and images[1] is not None:
-                    codes[0, 1] = encode_bt(images[1])
-                seen = (torch.from_numpy(codes).to(DEVICE),
-                        torch.tensor([[True, len(images) > 1 and images[1] is not None]], device=DEVICE))
-                print("satellite (GridSat-B1): " + describe_patch(images[0]))
-        with torch.no_grad(), torch.autocast(DEVICE, dtype=torch.bfloat16, enabled=DEVICE == "cuda"):
-            out = model.eval()(analysis=window["analysis"][None].to(DEVICE), analysis_grid=SRC,
-                               calendar=window["calendar"][None].to(DEVICE), output_grid=SRC,
-                               storm_center=here, storm_state=target["storm_state"][None].to(DEVICE),
-                               storm_environment=environment,
-                               track_prior=steer if model.uses_track_prior() else None,
-                               storm_satellite=seen)
-        out = {k: v.float().cpu() for k, v in out.items()}
-        out.setdefault("track_prior", steer.float().cpu())
-        # A second physics member: the storm carried by the atmosphere the model *forecasts*, step by
-        # step, rather than by today's flow held steady. Only once the state head has been trained.
-        rolled = None
-        if model.trained_heads()["state"] > 0:
-            with torch.no_grad():
-                future = state_forecast(model, {"analysis": window["analysis"][None].to(DEVICE),
-                                                "calendar": window["calendar"][None].to(DEVICE),
-                                                "valid_time": window["valid_time"].view(1)},
-                                        stepper, steps=ROLLOUT_STEPS, precision=R["precision"])[0]
-            rolled = steering_track(torch.cat([now[None], future.to(DEVICE)]), train_ds.variables,
-                                    train_ds.normalizer, SRC, here, CFG.lead_times_hours).float().cpu()
-        fc = build_forecast(out, CFG.lead_times_hours, issued, storm_center=centre,
-                            normalizer=train_ds.normalizer, trained=model.trained_heads(), inputs=("analysis",),
-                            consensus={"weights": model.track_consensus.cpu(), "storm_state": target["storm_state"]})
-        print(f"issued {issued:%Y-%m-%d %H:%M}Z at {centre[0]:.1f}N {-centre[1]:.1f}W, "
-              f"{float(target['current_wind_kt']):.0f} kt now")
-
-        def km_off(d_lat, d_lon, lead):
-            lat = centre[0] + float(target["track_target"][lead, 0])
-            lon = centre[1] + float(target["track_target"][lead, 1])
-            return 111.2 * np.hypot(centre[0] + float(d_lat) - lat,
-                                    (centre[1] + float(d_lon) - lon) * np.cos(np.radians(lat)))
-
-        members = {"steering": steer[0].cpu(), "extrap.": extrapolation_track(target["storm_state"][None],
-                                                                              CFG.lead_times_hours)[0]}
-        if rolled is not None:
-            members["rollout-steer"] = rolled[0]
-        if isinstance(fc["track_scenarios"], list):
-            top = fc["track_scenarios"][0]
-            members = {f"model ({top['probability']:.0%})": torch.tensor(
-                [[p["latitude"] - centre[0], p["longitude"] - centre[1]] for p in top["track"]]), **members}
-        if "track_consensus" in fc:
-            members["consensus"] = torch.tensor([[p["latitude"] - centre[0], p["longitude"] - centre[1]]
-                                                 for p in fc["track_consensus"]["track"]])
-        print("track error vs what happened, km, by member -- the physics members need no training:")
-        print("  " + f"{'lead':>6}" + "".join(f"{name:>16}" for name in members) + f"{'wind fcst/actual':>20}")
-        for lead, hours in enumerate(CFG.lead_times_hours):
-            if target["track_valid"][lead] > 0:
-                row = "".join(f"{km_off(*member[lead], lead):>13.0f} km" for member in members.values())
-                wind = ""
-                if isinstance(fc["intensity"], list):
-                    wind = f"{fc['intensity'][lead]['max_wind_ms'] * 1.94384:5.0f}"
-                    if target["intensity_mask"][lead, 0] > 0:
-                        wind += f" / {float(target['intensity_target'][lead, 0]) * 1.94384:3.0f} kt"
-                print(f"  +{hours:4d}h {row}{wind:>20}")
-        if not isinstance(fc["track_scenarios"], list):
-            print("track head untrained -- run RUN_STORMS first; the physics members above still stand")
-        problems = check_forecast(fc)
-        print("forecast checks: " + ("pass" if not problems else "; ".join(problems)))
-
-# ═══ 11 ═══ publish only if it earned it ═══════════════════════════════════════════════════════════
-if RUN_PUBLISH:
-    cards = [c for c in (state_card, card) if c is not None]
-    beats = [s for c in cards for s in c.scores if s.beats_persistence]
-    if not cards:
-        print("\nnot publishing: nothing was scored (set RUN_SCORE = True).")
-    elif not responds:
-        print("\nnot publishing: the model gives the same answer whatever weather it is shown.")
-    elif not beats:
-        print("\nnot publishing: it loses to persistence at every field and lead.")
-    else:
-        url = push_to_hub(model, HF_REPO, normalizer=train_ds.normalizer, scorecard=cards[0], name="NatureV1",
-                          author="Nathan", token=HF_TOKEN or None,
-                          training_data=f"ERA5 (WeatherBench 2), {len(CHANNELS)} channels, {R['years']} years; "
-                                        f"full-state {ROLLOUT_STEPS}-step rollout, {MEMBERS}-member CRPS; "
-                                        f"HURDAT2 {STORM_FIRST_SEASON}+ for the storm heads.")
-        print(f"\npublished: {url}  (beats persistence on {len(beats)} field-lead pairs)")
-
-# ═══ 12 ═══ live forecast from GOES — only once that input path is trained ═════════════════════════
-def load_scene(paths, center, half_width_deg=9.0, stride=4):
-    """Geolocated samples plus true pixel footprints, cropped to a real box on the planet."""
-    scene = scene_from_netcdf({c: str(p) for c, p in paths.items()}, stride=stride,
-                              bounds=(center[0] - half_width_deg, center[0] + half_width_deg,
-                                      center[1] - half_width_deg, center[1] + half_width_deg))
-    coords = torch.tensor(np.stack([np.radians(scene.latitude), np.radians(scene.longitude) % (2 * np.pi)], -1),
-                          dtype=torch.float64)
-    grid = FieldGrid.from_points(coords, Geometry.globe(), num_neighbours=16, cluster_size=64,
-                                 weights=torch.tensor(scene.area_km2, dtype=torch.float64))
-    values = torch.tensor(normalize_channels(scene.values, scene.channels), dtype=torch.float32)
-    if CFG.satellite_channels > values.shape[-1]:
-        values = torch.cat([values, torch.zeros(values.shape[0], CFG.satellite_channels - values.shape[-1])], -1)
-    return grid, values, scene
-
-
-@torch.no_grad()
-def forecast_now(storm=STORM, city=CITY):
-    paths = fetch_latest(os.path.join(DATA_DIR, "goes"), ("C13", "C09"), satellite="east", product="conus")
-    grid, values, scene = load_scene(paths, storm)
-    print(scene)
-    frames = CFG.history_frames
-    out_grid = fibonacci_sphere(2000, num_neighbours=16, cluster_size=50)
-    out = model.eval()(satellite=values[None, None].expand(1, frames, -1, -1).contiguous().to(DEVICE),
-                       satellite_grid=grid, output_grid=out_grid, neighbours=12,
-                       calendar=calendar_features(torch.full((1, frames), scene.timestamp.timestamp())).to(DEVICE),
-                       storm_center=torch.tensor([storm], dtype=torch.float32, device=DEVICE))
-    return build_forecast({k: v.float().cpu() for k, v in out.items()}, CFG.lead_times_hours, scene.timestamp,
-                          storm_center=storm, output_grid=out_grid, point_of_interest=city,
-                          normalizer=train_ds.normalizer, trained=model.trained_heads(), inputs=("satellite",))
-
-
-def show(fc):
-    print(f"\nissued {fc['issued']}   trustworthy: {fc['trustworthy']}")
-    for key in ("warning", "note"):
-        if key in fc:
-            print(f"  !! {fc[key]}")
-    for section in ("enso", "landfall", "track_scenarios", "eyewall", "rapid_intensification"):
-        value = fc.get(section)
-        if isinstance(value, dict) and value.get("available") is False:
-            print(f"  {section}: not available -- {value['reason']}")
-    if isinstance(fc.get("track_scenarios"), list):
-        for s in fc["track_scenarios"][:4]:
-            p = s["track"][5]
-            print(f"  {s['probability']:>5.0%} -> +{p['lead_hours']}h {p['latitude']:6.2f},{p['longitude']:7.2f}"
-                  f"  95% cone {p['cone_radius_km_95']:.0f} km")
-    print("  checks: " + ("pass" if not check_forecast(fc) else "; ".join(check_forecast(fc))))
-
-
-if RUN_FORECAST or RUN_WATCHER:
-    if model.trained_heads()["satellite_encoder"] == 0:
-        print("\nlive GOES forecast refused: no training stage has ever fed this model satellite imagery, so "
-              "its satellite encoder is at initialisation and every number it produced would be noise shaped "
-              "like a forecast. Use the HINDCAST section, which runs from the analysis the model was trained on.")
-    elif RUN_FORECAST:
-        banner("LIVE FORECAST — newest GOES scene")
-        show(forecast_now())
-
-
-def on_new_scene(paths):
-    result = forecast_now()
-    os.makedirs(os.path.join(DATA_DIR, "forecasts"), exist_ok=True)
-    stamp = dt.datetime.now(dt.timezone.utc).strftime("%Y%m%dT%H%M")
-    with open(os.path.join(DATA_DIR, "forecasts", f"forecast_{stamp}.json"), "w") as handle:
-        json.dump(result, handle, indent=2)
-    show(result)
-
-
-if RUN_WATCHER and model.trained_heads()["satellite_encoder"] > 0:
-    banner("WATCHING — a new forecast every hour")
-    watch(on_new_scene, interval_seconds=3600, directory=os.path.join(DATA_DIR, "goes"), channels=("C13", "C09"))

naturev1/assimilation.py

@@ -1,290 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Data assimilation for live running: scrub real-time inputs before they reach a model trained on ERA5.
-
-NatureV1 (like every machine-learning weather model) learned on ERA5, a reanalysis polished by 4D-Var with
-observations that arrived for years after the fact. In real time the inputs are messier: another centre's
-operational analysis with its own biases and resolution, late or missing observations, a radiosonde with a
-transmission error. Fed straight in, those differences become forecast error. ECMWF's AIFS sidesteps this by
-running inside an operational data-assimilation cycle; this module gives NatureV1 a compact version of one:
-
-1. **Background** -- NatureV1's own 6-hour forecast from the previous cycle, with its own predicted variance
-   (``state_delta_log_var``) as the background error variance: flow-dependent, large where the model is
-   unsure (a developing storm, a front), small where it is confident.
-2. **Bias correction** (:class:`BiasCorrector`) -- the running mean of innovations (observation minus background)
-   per channel and latitude band, an exponentially-weighted version of variational bias correction, removed
-   from each source before it is used; a real-time analysis that is systematically 0.5 K warmer than ERA5 at
-   850 hPa stops pulling NatureV1 off its climate.
-3. **Quality control** (:func:`quality_control`) -- a gross check against physical limits, a background check
-   (reject when ``|O - B| > k sqrt(sigma_o^2 + sigma_b^2)``), and a buddy check (reject an observation whose
-   innovation disagrees with the median of its neighbours' by more than ``k`` of their spread).
-4. **Analysis** (:func:`analyse`) -- optimal interpolation, solved locally in tiles (as in a local ensemble
-   transform filter, without the ensemble): the observations within a Gaspari-Cohn localisation radius of a tile
-   are combined with the background through ``x_a = x_b + B H^T (H B H^T + R)^-1 (y - H x_b)``, with Gaussian
-   background-error correlations of a per-variable length scale.
-5. **Super-observations** (:func:`superobs`) -- a gridded source (a 0.25-degree analysis) is first averaged into
-   coarser boxes, so its spatially correlated errors are not counted as independent evidence.
-
-Everything works channel by channel on NatureV1's normalised ``(points, channels)`` state.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-import numpy as np
-
-from .cyclone.geometry import EARTH_RADIUS_KM
-
-#: Physical limits for the gross check, in SI units, by variable base name.
-LIMITS = {"temperature": (150.0, 340.0), "2m_temperature": (180.0, 340.0), "geopotential": (-5000.0, 220000.0),
-          "u_component_of_wind": (-120.0, 120.0), "v_component_of_wind": (-120.0, 120.0),
-          "10m_u_component_of_wind": (-80.0, 80.0), "10m_v_component_of_wind": (-80.0, 80.0),
-          "mean_sea_level_pressure": (85000.0, 110000.0), "specific_humidity": (0.0, 0.04),
-          "surface_pressure": (45000.0, 110000.0), "sea_surface_temperature": (269.0, 310.0)}
-#: Background-error correlation length scale, km, by variable base name (default 400).
-LENGTH_KM = {"geopotential": 600.0, "mean_sea_level_pressure": 500.0, "temperature": 400.0, "2m_temperature": 250.0,
-             "u_component_of_wind": 350.0, "v_component_of_wind": 350.0, "specific_humidity": 250.0}
-
-
-def unit_vectors(lat, lon) -> np.ndarray:
-    la, lo = np.radians(lat), np.radians(lon)
-    return np.stack([np.cos(la) * np.cos(lo), np.cos(la) * np.sin(lo), np.sin(la)], -1)
-
-
-def chord_km(a: np.ndarray, b: np.ndarray) -> np.ndarray:
-    """Great-circle distance between unit vectors (rows of ``a`` against rows of ``b``), km."""
-    dot = np.clip(a @ b.T, -1.0, 1.0)
-    return EARTH_RADIUS_KM * np.arccos(dot)
-
-
-def gaspari_cohn(distance: np.ndarray, radius: float) -> np.ndarray:
-    """Gaspari-Cohn fifth-order compactly supported correlation, zero beyond ``2 * radius`` -- here ``radius`` is half."""
-    r = np.abs(distance) / radius
-    out = np.zeros_like(r)
-    a = r <= 1.0
-    b = (r > 1.0) & (r < 2.0)
-    ra, rb = r[a], r[b]
-    out[a] = -0.25 * ra ** 5 + 0.5 * ra ** 4 + 0.625 * ra ** 3 - 5.0 / 3.0 * ra ** 2 + 1.0
-    out[b] = rb ** 5 / 12.0 - 0.5 * rb ** 4 + 0.625 * rb ** 3 + 5.0 / 3.0 * rb ** 2 - 5.0 * rb + 4.0 - 2.0 / (3.0 * rb)
-    return out
-
-
-@dataclass
-class Observations:
-    """Observations of one channel: positions, values and error standard deviations (all in the same units as
-    the state they are compared with)."""
-
-    lat: np.ndarray
-    lon: np.ndarray
-    value: np.ndarray
-    sigma: np.ndarray
-    source: np.ndarray = field(default_factory=lambda: np.zeros(0, dtype="<U16"))
-
-    def __post_init__(self):
-        self.lat, self.lon = np.asarray(self.lat, np.float64), np.asarray(self.lon, np.float64)
-        self.value, self.sigma = np.asarray(self.value, np.float64), np.broadcast_to(np.asarray(self.sigma, np.float64), self.lat.shape).copy()
-        if self.source.size != self.lat.size:
-            self.source = np.full(self.lat.size, "obs", dtype="<U16")
-
-    def subset(self, keep: np.ndarray) -> "Observations":
-        return Observations(self.lat[keep], self.lon[keep], self.value[keep], self.sigma[keep], self.source[keep])
-
-    def __len__(self) -> int:
-        return self.lat.size
-
-
-def interpolate_background(grid_lat: np.ndarray, grid_lon: np.ndarray, field: np.ndarray, lat, lon) -> np.ndarray:
-    """Bilinear background ``H x_b`` at observation points on a regular grid (lat ascending, lon 0..360)."""
-    step_lat = grid_lat[1] - grid_lat[0]
-    step_lon = grid_lon[1] - grid_lon[0]
-    grid = field.reshape(grid_lat.size, grid_lon.size)
-    fi = np.clip((np.asarray(lat) - grid_lat[0]) / step_lat, 0, grid_lat.size - 1.000001)
-    fj = (np.asarray(lon) % 360.0 - grid_lon[0]) / step_lon
-    i0 = np.floor(fi).astype(int)
-    j0 = np.floor(fj).astype(int) % grid_lon.size
-    j1 = (j0 + 1) % grid_lon.size
-    di, dj = fi - i0, fj - np.floor(fj)
-    return ((1 - di) * (1 - dj) * grid[i0, j0] + (1 - di) * dj * grid[i0, j1] + di * (1 - dj) * grid[i0 + 1, j0]
-            + di * dj * grid[i0 + 1, j1])
-
-
-class BiasCorrector:
-    """Running mean of innovations per latitude band (an exponentially weighted variational bias correction)."""
-
-    def __init__(self, bands_deg: float = 15.0, memory: float = 0.05) -> None:
-        self.edges = np.arange(-90.0, 90.0 + bands_deg, bands_deg)
-        self.memory = memory
-        self.bias: dict[str, np.ndarray] = {}
-        self.updates: dict[str, np.ndarray] = {}
-
-    def correct(self, source: str, obs: Observations) -> Observations:
-        b = self.bias.get(source)
-        if b is None:
-            return obs
-        band = np.clip(np.searchsorted(self.edges, obs.lat) - 1, 0, len(self.edges) - 2)
-        return Observations(obs.lat, obs.lon, obs.value - b[band], obs.sigma, obs.source)
-
-    def update(self, source: str, obs: Observations, innovation: np.ndarray) -> None:
-        band = np.clip(np.searchsorted(self.edges, obs.lat) - 1, 0, len(self.edges) - 2)
-        current = self.bias.get(source, np.zeros(len(self.edges) - 1))
-        seen = self.updates.get(source, np.zeros(len(self.edges) - 1))
-        for k in range(len(current)):
-            sel = band == k
-            if sel.sum() >= 5:
-                # Warm start: the first updates are a plain running mean, then the memory takes over.
-                rate = max(self.memory, 1.0 / (seen[k] + 1.0))
-                # Innovations measured against bias-corrected values: add the current estimate back.
-                current[k] = (1 - rate) * current[k] + rate * (current[k] + float(np.median(innovation[sel])))
-                seen[k] += 1
-        self.bias[source], self.updates[source] = current, seen
-
-
-def quality_control(obs: Observations, background_at_obs: np.ndarray, background_sigma_at_obs: np.ndarray,
-                    limits: tuple[float, float] | None = None, k_background: float = 4.0, k_buddy: float = 3.0,
-                    buddy_km: float = 300.0) -> tuple[np.ndarray, dict]:
-    """``(keep, counts)``: gross, background and buddy checks; ``limits`` in the observations' units."""
-    keep = np.isfinite(obs.value)
-    counts = {"total": int(len(obs))}
-    if limits is not None:
-        gross = (obs.value < limits[0]) | (obs.value > limits[1])
-        keep &= ~gross
-        counts["gross"] = int(gross.sum())
-    innovation = obs.value - background_at_obs
-    scale = np.sqrt(obs.sigma ** 2 + background_sigma_at_obs ** 2)
-    background = np.abs(innovation) > k_background * scale
-    keep &= ~background
-    counts["background"] = int((background & np.isfinite(obs.value)).sum())
-    buddy_reject = np.zeros(len(obs), bool)
-    idx = np.nonzero(keep)[0]
-    if idx.size > 3:
-        v = unit_vectors(obs.lat[idx], obs.lon[idx])
-        for start in range(0, idx.size, 2048):
-            block = idx[start:start + 2048]
-            d = chord_km(unit_vectors(obs.lat[block], obs.lon[block]), v)
-            near = (d < buddy_km) & (d > 0)
-            for row, i in enumerate(block):
-                neighbours = idx[near[row]]
-                if neighbours.size < 3:
-                    continue
-                med = np.median(innovation[neighbours])
-                spread = 1.4826 * np.median(np.abs(innovation[neighbours] - med)) + 0.5 * scale[i]
-                if abs(innovation[i] - med) > k_buddy * spread:
-                    buddy_reject[i] = True
-    keep &= ~buddy_reject
-    counts["buddy"] = int(buddy_reject.sum())
-    counts["kept"] = int(keep.sum())
-    return keep, counts
-
-
-def superobs(obs: Observations, box_deg: float = 1.5) -> Observations:
-    """Average observations into ``box_deg`` boxes (error shrinks only as the square root of a quarter of the
-    count, a hedge against their correlated errors)."""
-    i = np.floor((obs.lat + 90.0) / box_deg).astype(int)
-    j = np.floor((obs.lon % 360.0) / box_deg).astype(int)
-    key = i * 100000 + j
-    unique, inverse, counts = np.unique(key, return_inverse=True, return_counts=True)
-    lat = np.bincount(inverse, obs.lat) / counts
-    lon = np.bincount(inverse, np.where(obs.lon % 360.0 > 359.0, obs.lon % 360.0 - 360.0, obs.lon % 360.0)) / counts
-    value = np.bincount(inverse, obs.value) / counts
-    sigma = np.sqrt(np.bincount(inverse, obs.sigma ** 2) / counts) / np.sqrt(np.maximum(counts / 4.0, 1.0))
-    return Observations(lat, lon % 360.0, value, sigma)
-
-
-def analyse(grid_lat: np.ndarray, grid_lon: np.ndarray, background: np.ndarray, background_sigma: np.ndarray,
-            obs: Observations, length_km: float = 400.0, localisation_km: float = 1200.0, tile: int = 4) -> tuple[np.ndarray, np.ndarray]:
-    """
-    Local optimal interpolation of one channel. ``background``/``background_sigma``: ``(P,)`` on the regular grid.
-
-    Returns ``(analysis (P,), analysis_sigma (P,))``.
-    """
-    analysis = background.astype(np.float64).copy()
-    a_sigma = background_sigma.astype(np.float64).copy()
-    if len(obs) == 0:
-        return analysis, a_sigma
-    lat_g, lon_g = np.meshgrid(grid_lat, grid_lon, indexing="ij")
-    hx = interpolate_background(grid_lat, grid_lon, background, obs.lat, obs.lon)
-    sb_obs = interpolate_background(grid_lat, grid_lon, background_sigma, obs.lat, obs.lon)
-    innovation = obs.value - hx
-    ov = unit_vectors(obs.lat, obs.lon)
-    h, w = lat_g.shape
-    for i0 in range(0, h, tile):
-        for j0 in range(0, w, tile):
-            rows = slice(i0, min(i0 + tile, h))
-            cols = slice(j0, min(j0 + tile, w))
-            tlat, tlon = lat_g[rows, cols].ravel(), lon_g[rows, cols].ravel()
-            tv = unit_vectors(tlat, tlon)
-            centre = unit_vectors(tlat.mean(), np.degrees(np.arctan2(np.sin(np.radians(tlon)).mean(), np.cos(np.radians(tlon)).mean())))
-            dc = chord_km(centre[None], ov)[0]
-            near = dc < localisation_km + tile * 170.0
-            if not near.any():
-                continue
-            o = np.nonzero(near)[0]
-            d_oo = chord_km(ov[o], ov[o])
-            d_to = chord_km(tv, ov[o])
-            loc_oo = gaspari_cohn(d_oo, localisation_km / 2.0)
-            loc_to = gaspari_cohn(d_to, localisation_km / 2.0)
-            sb_o = sb_obs[o]
-            point_index = (np.arange(h)[rows][:, None] * w + np.arange(w)[cols][None, :]).ravel()
-            sb_t = background_sigma[point_index]
-            b_oo = sb_o[:, None] * sb_o[None, :] * np.exp(-0.5 * (d_oo / length_km) ** 2) * loc_oo
-            b_to = sb_t[:, None] * sb_o[None, :] * np.exp(-0.5 * (d_to / length_km) ** 2) * loc_to
-            s = b_oo + np.diag(obs.sigma[o] ** 2)
-            try:
-                gain = np.linalg.solve(s, b_to.T).T                       # (T, O)
-            except np.linalg.LinAlgError:
-                continue
-            analysis[point_index] = background[point_index] + gain @ innovation[o]
-            reduction = np.einsum("to,to->t", gain, b_to)
-            a_sigma[point_index] = np.sqrt(np.maximum(sb_t ** 2 - reduction, 0.05 * sb_t ** 2))
-    return analysis, a_sigma
-
-
-class Assimilator:
-    """
-    The cycle: bias-correct each source, quality-control against the background, analyse every channel.
-
-    ``state`` and ``sigma`` are ``(P, C)`` in physical units for the channels being analysed (decode NatureV1's
-    normalised state first with its normaliser); ``observations`` maps a channel name to a list of
-    ``(source name, Observations)``.
-    """
-
-    def __init__(self, channels: list[str], grid_lat=np.linspace(-90, 90, 121), grid_lon=np.arange(240) * 1.5,
-                 bias: BiasCorrector | None = None, anchors=("radiosonde", "buoy", "aircraft")) -> None:
-        self.channels, self.grid_lat, self.grid_lon = list(channels), np.asarray(grid_lat), np.asarray(grid_lon)
-        self.bias = bias or BiasCorrector()
-        # Sources trusted to be unbiased: they anchor the system and are never bias-corrected, so a biased
-        # background cannot drag the corrections along with it.
-        self.anchors = set(anchors)
-
-    def cycle(self, state: np.ndarray, sigma: np.ndarray, observations: dict) -> tuple[np.ndarray, np.ndarray, dict]:
-        analysis, a_sigma = state.copy(), sigma.copy()
-        report = {}
-        for name, sources in observations.items():
-            if name not in self.channels:
-                continue
-            c = self.channels.index(name)
-            base = name.split("@")[0]
-            merged = []
-            for source, obs in sources:
-                anchored = source in self.anchors
-                if not anchored:
-                    obs = self.bias.correct(f"{source}|{name}", obs)
-                hx = interpolate_background(self.grid_lat, self.grid_lon, state[:, c], obs.lat, obs.lon)
-                sb = interpolate_background(self.grid_lat, self.grid_lon, sigma[:, c], obs.lat, obs.lon)
-                keep, counts = quality_control(obs, hx, sb, LIMITS.get(base))
-                if not anchored:
-                    self.bias.update(f"{source}|{name}", obs.subset(keep), (obs.value - hx)[keep])
-                report[f"{source}|{name}"] = counts
-                merged.append(obs.subset(keep))
-            if not merged:
-                continue
-            combined = Observations(np.concatenate([m.lat for m in merged]), np.concatenate([m.lon for m in merged]),
-                                    np.concatenate([m.value for m in merged]), np.concatenate([m.sigma for m in merged]))
-            analysis[:, c], a_sigma[:, c] = analyse(self.grid_lat, self.grid_lon, state[:, c], sigma[:, c], combined,
-                                                    LENGTH_KM.get(base, 400.0))
-        return analysis, a_sigma, report
-
-
-__all__ = ["Assimilator", "BiasCorrector", "LENGTH_KM", "LIMITS", "Observations", "analyse", "gaspari_cohn",
-           "interpolate_background", "quality_control", "superobs", "unit_vectors"]

naturev1/b300.py

@@ -1,257 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Orchestration for one 8-GPU machine: stage the record, launch the training runs, follow them.
-
-Every long job runs as its own process group, detached from the notebook or terminal that started it,
-writing to a log file and a PID file -- so closing the notebook, losing the connection or restarting the
-kernel never stops a run, and running the same cell again reattaches to it instead of starting a second
-copy. The runbook (``b300_naturev1.py``) is a thin layer of settings over these functions.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import signal
-import subprocess
-import sys
-import time
-from pathlib import Path
-
-import numpy as np
-import torch
-
-
-# ------------------------------------------------------------------------------------------- data --
-
-def stage_era5_record(directory: str | Path, first_year: int, last_year: int, stats_path: str | Path,
-                      workers: int = 32) -> Path:
-    """
-    Stage every six-hourly ERA5 state of ``first_year``-``last_year`` (WeatherBench 2, 1.5 degrees, the
-    backbone's 89 channels) to one memmap, normalised with the *training* statistics -- so the retrieval
-    and stage B see exactly what the backbone was trained on. About 7.7 GB a year. Resumable.
-    """
-    from .era5 import Normalizer, expand_variables, materialise
-    from .upper import open_weatherbench_levels
-
-    stats = json.loads(Path(stats_path).read_text())
-    names = list(stats["variables"])
-    levels = sorted({int(v.split("@")[1]) for v in names if "@" in v})
-    base = tuple(dict.fromkeys(v.split("@")[0] for v in names))
-    dataset, _, _ = open_weatherbench_levels()
-    expanded = expand_variables(dataset, base, levels)
-    if expanded != names:
-        raise ValueError("the store's channels do not line up with the training statistics: "
-                         f"{len(expanded)} vs {len(names)}")
-    years = dataset.time.values.astype("datetime64[Y]").astype(int) + 1970
-    indices = np.where((years >= first_year) & (years <= last_year))[0]
-    path = Path(directory) / f"era5_{first_year}_{last_year}.npy"
-    print(f"[b300] ERA5 {first_year}-{last_year}: {len(indices):,} states, about "
-          f"{len(indices) * 121 * 240 * len(names) * 2 / 1e9:.0f} GB", flush=True)
-    return materialise(dataset, indices, path, variables=base, normalizer=Normalizer.from_dict(stats), levels=levels,
-                       workers=workers, chunk=16)
-
-
-def memmap_tendency(path: str | Path, channels: int, samples: int = 512, seed: int = 0) -> torch.Tensor:
-    """
-    Per-channel spread of the six-hour change, in the model's channel layout, from a staged memmap: the
-    scale the full-state rollout and the retrieval predict in. Only for checkpoints that do not record it.
-    """
-    from .era5 import Normalizer
-    from .satdata import prepared_to_state
-
-    path = Path(path)
-    meta = json.loads(path.with_suffix(".json").read_text())
-    values = np.load(path, mmap_mode="r")
-    normalizer = Normalizer.from_dict(meta["statistics"])
-    times = np.asarray(meta["time"], dtype=np.int64)
-    consecutive = np.where(np.diff(times) == 21600)[0]
-    rng = np.random.default_rng(seed)
-    chosen = rng.choice(consecutive, min(samples, len(consecutive)), replace=False)
-    total = squares = None
-    count = 0
-    for row in chosen:
-        delta = (prepared_to_state(values[row + 1], normalizer, channels)
-                 - prepared_to_state(values[row], normalizer, channels)).double()
-        total = delta.sum(0) if total is None else total + delta.sum(0)
-        squares = (delta ** 2).sum(0) if squares is None else squares + (delta ** 2).sum(0)
-        count += delta.shape[0]
-    mean = total / count
-    return (squares / count - mean ** 2).clamp_min(0).sqrt().clamp_min(1e-3).float()
-
-
-# ------------------------------------------------------------------------------------------- jobs --
-
-def _pid_file(logs: Path, name: str) -> Path:
-    return logs / f"{name}.pid"
-
-
-def running(logs: str | Path, name: str) -> int | None:
-    """The PID of job ``name`` if it is still alive."""
-    path = _pid_file(Path(logs), name)
-    if not path.exists():
-        return None
-    try:
-        pid = int(path.read_text().strip())
-        os.kill(pid, 0)
-        return pid
-    except (ValueError, ProcessLookupError, PermissionError):
-        return None
-
-
-def start_job(name: str, args: list[str], logs: str | Path, gpus: list[int] | None = None,
-              env: dict | None = None) -> int:
-    """
-    Start ``args`` detached (its own session), logging to ``<logs>/<name>.log``. With ``gpus``, it runs
-    under ``torchrun`` on exactly those GPUs. Returns the PID; if the job is already running, returns
-    that PID and starts nothing.
-    """
-    logs = Path(logs)
-    logs.mkdir(parents=True, exist_ok=True)
-    alive = running(logs, name)
-    if alive:
-        print(f"[b300] {name} is already running (pid {alive}); following it", flush=True)
-        return alive
-    environment = {**os.environ, **(env or {})}
-    command = list(args)
-    if gpus is not None:
-        environment["CUDA_VISIBLE_DEVICES"] = ",".join(str(g) for g in gpus)
-        import zlib
-
-        port = 29500 + zlib.crc32(name.encode()) % 400                 # stable per job, distinct between jobs
-        command = [sys.executable, "-m", "torch.distributed.run", f"--nproc_per_node={len(gpus)}",
-                   f"--master_port={port}", *command]
-    environment.setdefault("OMP_NUM_THREADS", "4")
-    environment.setdefault("PYTHONUNBUFFERED", "1")
-    log = open(logs / f"{name}.log", "ab")
-    log.write(f"\n===== {time.strftime('%Y-%m-%d %H:%M:%S')} start: {' '.join(command)}\n".encode())
-    log.flush()
-    process = subprocess.Popen(command, stdout=log, stderr=subprocess.STDOUT, env=environment,
-                               start_new_session=True)
-    _pid_file(logs, name).write_text(str(process.pid))
-    print(f"[b300] started {name} (pid {process.pid}) -> {logs / (name + '.log')}", flush=True)
-    return process.pid
-
-
-def stop_job(logs: str | Path, name: str) -> None:
-    pid = running(logs, name)
-    if pid:
-        os.killpg(os.getpgid(pid), signal.SIGTERM)
-        print(f"[b300] stopped {name}", flush=True)
-
-
-def follow(logs: str | Path, names: list[str], every: float = 2.0, quiet_minutes: float = 5.0,
-           seconds: float | None = None) -> dict:
-    """
-    Print new log lines of every job as they come, a heartbeat when they are quiet, until all have ended
-    (or ``seconds`` pass). Interrupting this stops only the watching. Returns each job's last line.
-    """
-    logs = Path(logs)
-    offsets = {name: (logs / f"{name}.log").stat().st_size if (logs / f"{name}.log").exists() else 0
-               for name in names}
-    # Show the recent past once, so a re-attached cell has context.
-    for name in names:
-        path = logs / f"{name}.log"
-        if path.exists():
-            tail = path.read_bytes()[-4000:].decode(errors="replace").splitlines()[-15:]
-            print("\n".join(f"[{name}] {line}" for line in tail), flush=True)
-    began, last_output, last = time.time(), time.time(), {}
-    try:
-        while True:
-            for name in names:
-                path = logs / f"{name}.log"
-                if not path.exists():
-                    continue
-                with open(path, "rb") as handle:
-                    handle.seek(offsets[name])
-                    chunk = handle.read()
-                    offsets[name] = handle.tell()
-                if chunk:
-                    text = chunk.decode(errors="replace").rstrip("\n")
-                    for line in text.splitlines():
-                        if line.strip():
-                            print(f"[{name}] {line}", flush=True)
-                            last[name] = line
-                    last_output = time.time()
-            alive = [n for n in names if running(logs, n)]
-            if not alive:
-                print("[b300] all jobs have ended", flush=True)
-                return last
-            if time.time() - last_output > quiet_minutes * 60:
-                print(f"[b300] {time.strftime('%H:%M')} still running: {', '.join(alive)}", flush=True)
-                last_output = time.time()
-            if seconds is not None and time.time() - began > seconds:
-                return last
-            time.sleep(every)
-    except KeyboardInterrupt:
-        print("[b300] stopped watching; the jobs keep running. Run the cell again to reattach.", flush=True)
-        return last
-
-
-# ------------------------------------------------------------------------------------------ release --
-
-def publish_release(checkpoint: str | Path, stats_path: str | Path, hub_repo: str, directory: str | Path,
-                    comparison: str | Path | None = None, report: str | Path | None = None,
-                    minimum_better: float = 0.5, force: bool = False) -> str:
-    """
-    Publish the stage-B model as the release (``model.safetensors``, ``config.json``, ``normalizer.json``
-    at the top of the repository, what :func:`naturev1.from_pretrained` reads) -- but only if it earned
-    it: when ``comparison`` (from stage B) shows it better than the model it started from on fewer than
-    ``minimum_better`` of the (lead, metric) pairs on the test storms, it goes to ``candidates/0.12/``
-    instead and the current release is left alone. ``force`` publishes regardless. Returns where it went.
-    """
-    from dataclasses import asdict
-    import hashlib
-
-    from huggingface_hub import HfApi
-    from safetensors.torch import save_file
-
-    from .hub import from_pretrained
-    from .sattrain import build_model
-
-    payload = torch.load(checkpoint, map_location="cpu", weights_only=False)
-    config = payload["config"]
-    model = build_model(str(checkpoint), satnet_embed=config.get("satnet_embed", 0),
-                        retrieval_layers=config.get("retrieval_layers", 0), ri2=config.get("ri2", False),
-                        hemisphere_frame=config.get("hemisphere_frame", False))
-    verdict, share = "release", None
-    if comparison is not None and Path(comparison).exists():
-        share = json.loads(Path(comparison).read_text()).get("better_share_global")
-        if share is not None and share < minimum_better and not force:
-            verdict = "candidate"
-    out = Path(directory)
-    out.mkdir(parents=True, exist_ok=True)
-    state = {k: v.detach().cpu().contiguous() for k, v in model.state_dict().items()}
-    digest = hashlib.sha256()
-    for name in sorted(state):
-        digest.update(name.encode())
-        digest.update(state[name].numpy().tobytes() if state[name].dtype != torch.bfloat16
-                      else state[name].float().numpy().tobytes())
-    save_file(state, out / "model.safetensors", metadata={"format": "pt", "tensor_sha256": digest.hexdigest()})
-    torch.save(model.state_dict(), out / "model.safetensors.pt")
-    (out / "config.json").write_text(json.dumps(asdict(model.config), indent=2, default=list))
-    (out / "normalizer.json").write_text(Path(stats_path).read_text())
-    (out / "training_record.json").write_text(json.dumps(
-        {"trained_steps_per_output": model.trained_heads(), "released_from": str(checkpoint),
-         "better_share_on_test_storms": share, "parameters": model.num_parameters()}, indent=2))
-    for extra in (report, comparison):
-        if extra is not None and Path(extra).exists():
-            (out / Path(extra).name).write_text(Path(extra).read_text())
-    prefix = "" if verdict == "release" else "candidates/0.12/"
-    api = HfApi(token=os.environ.get("HF_TOKEN") or None)
-    api.create_repo(hub_repo, repo_type="model", exist_ok=True)
-    api.upload_folder(folder_path=str(out), repo_id=hub_repo, repo_type="model", path_in_repo=prefix or None,
-                      commit_message=f"NatureV1 0.12 {'release' if verdict == 'release' else 'candidate'}")
-    if verdict == "release":
-        loaded, _, _ = from_pretrained(hub_repo, device="cpu")
-        same = all(torch.equal(loaded.state_dict()[k].cpu(), v) for k, v in state.items())
-        print(f"[b300] released to {hub_repo}; reloaded with from_pretrained: "
-              f"{'identical' if same else 'DIFFERENT -- check the upload'}", flush=True)
-    else:
-        print(f"[b300] better than the starting model on only {100 * (share or 0):.0f}% of test comparisons: "
-              f"uploaded to {hub_repo}/candidates/0.12/ and left the current release in place "
-              "(pass force=True to override)", flush=True)
-    return prefix or "/"
-
-
-__all__ = ["follow", "publish_release", "memmap_tendency", "running", "stage_era5_record", "start_job", "stop_job"]

naturev1/besttrack.py

@@ -1,239 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Best-track labels: HURDAT2 and IBTrACS, and the rapid-intensification events derived from them.
-
-This is the *label* source, not the training corpus, and the difference matters. HURDAT2 holds about
-eighty thousand six-hourly rows across 174 years of Atlantic storms; IBTrACS about seven times that
-globally. Against an 88M-parameter network those numbers are nothing, and a model fit to them directly
-will memorise storms rather than learn weather.
-
-What they are good for is supervising a small number of storm-specific heads on top of a backbone that
-learned the atmosphere somewhere else -- from reanalysis, where the label is simply the next state and
-the corpus is millions of times larger. See :mod:`naturev1.corpora` for that side.
-
-Rapid intensification is scarcer still. The National Hurricane Center's threshold is a 30-knot increase
-in maximum sustained wind within 24 hours; across the whole Atlantic record that fires on a low
-single-digit percentage of track points. Any honest RI model has to start from that base rate, so
-:func:`rapid_intensification` reports it rather than leaving you to assume.
-"""
-
-from __future__ import annotations
-
-import datetime as dt
-import urllib.request
-from dataclasses import dataclass
-from pathlib import Path
-
-import numpy as np
-
-
-HURDAT2_ATLANTIC = "https://www.nhc.noaa.gov/data/hurdat/hurdat2-1851-2024-040425.txt"
-HURDAT2_PACIFIC = "https://www.nhc.noaa.gov/data/hurdat/hurdat2-nepac-1949-2024-040425.txt"
-IBTRACS_ALL = (
-    "https://www.ncei.noaa.gov/data/international-best-track-archive-for-climate-stewardship-ibtracs/"
-    "v04r01/access/csv/ibtracs.ALL.list.v04r01.csv"
-)
-
-#: HURDAT2 sentinel for "not reported".
-MISSING = -999
-
-
-@dataclass
-class Track:
-    """One storm's best track. Arrays are parallel, one entry per synoptic time."""
-
-    storm_id: str
-    name: str
-    time: np.ndarray            # (T,) datetime64[s]
-    latitude: np.ndarray        # (T,) degrees
-    longitude: np.ndarray       # (T,) degrees, -180..180
-    max_wind_kt: np.ndarray     # (T,) knots, 1-minute sustained
-    min_pressure_hpa: np.ndarray
-    status: np.ndarray          # (T,) two-letter classification
-    rmw_nmi: np.ndarray         # (T,) radius of maximum wind -- the eyewall's radius
-    wind_radii_nmi: np.ndarray  # (T, 3, 4) thresholds 34/50/64 kt by NE/SE/SW/NW quadrant
-    record: np.ndarray          # (T,) record identifier; "L" marks a landfall
-    # Filled by the global IBTrACS reader (naturev1.ibtracs); HURDAT2 tracks leave them unset.
-    basin: str = ""                                  # NA, EP, WP, NI, SI, SP, SA
-    interpolated: np.ndarray | None = None           # (T,) True where IBTrACS interpolated the fix
-    wind_source: np.ndarray | None = None            # (T,) 0 US 1-min, 1 WMO 10-min converted, 2 WMO 1-min
-    distance_to_land_km: np.ndarray | None = None    # (T,)
-
-    def __len__(self) -> int:
-        return self.time.shape[0]
-
-    @property
-    def landfall(self) -> np.ndarray:
-        """
-        ``(T,)`` boolean: did the centre cross a coastline at this point.
-
-        HURDAT2 marks landfalls explicitly in its record-identifier column, so this is an observation
-        rather than something inferred from a land mask -- which would otherwise have to guess at
-        resolution the archive already settled.
-        """
-        return self.record == "L"
-
-    @property
-    def year(self) -> int:
-        return int(str(self.time[0])[:4])
-
-    @property
-    def peak_wind_kt(self) -> float:
-        valid = self.max_wind_kt[self.max_wind_kt > 0]
-        return float(valid.max()) if valid.size else float("nan")
-
-    def __repr__(self) -> str:
-        return f"Track({self.storm_id} {self.name} {self.year}, {len(self)} points, peak {self.peak_wind_kt:.0f} kt)"
-
-
-def download(url: str, destination: str | Path) -> Path:
-    """Fetch a best-track file, skipping the download when it is already on disk."""
-    destination = Path(destination)
-    if destination.exists() and destination.stat().st_size > 0:
-        return destination
-    destination.parent.mkdir(parents=True, exist_ok=True)
-    temporary = destination.with_suffix(destination.suffix + ".part")
-    urllib.request.urlretrieve(url, temporary)
-    temporary.replace(destination)
-    return destination
-
-
-def _parse_latitude(token: str) -> float:
-    value = float(token[:-1])
-    return value if token[-1] == "N" else -value
-
-
-def _parse_longitude(token: str) -> float:
-    value = float(token[:-1])
-    value = value if token[-1] == "E" else -value
-    return (value + 180.0) % 360.0 - 180.0
-
-
-def parse_hurdat2(path: str | Path) -> list[Track]:
-    """
-    Parse a HURDAT2 file into :class:`Track` objects.
-
-    The format is a header line naming the storm and how many rows follow, then that many data rows. The
-    trailing column is the radius of maximum wind, which is the one direct observation of eyewall size in
-    the archive -- and is ``-999`` for most of the record, so treat its absence as the norm.
-
-    The third column is the record identifier, which carries an ``L`` at every landfall. It is the only
-    place the archive states landfall directly, so it is kept: inferring landfall from a land mask
-    instead means guessing at a resolution the archive has already settled.
-    """
-    tracks: list[Track] = []
-    with open(path) as handle:
-        lines = [line.rstrip("\n") for line in handle if line.strip()]
-
-    index = 0
-    while index < len(lines):
-        header = [part.strip() for part in lines[index].split(",")]
-        storm_id, name, count = header[0], header[1], int(header[2])
-        rows = lines[index + 1 : index + 1 + count]
-        index += 1 + count
-
-        times, lats, lons, winds, pressures, statuses, rmws, radii, records = [], [], [], [], [], [], [], [], []
-        for row in rows:
-            field = [part.strip() for part in row.split(",")]
-            stamp = dt.datetime.strptime(field[0] + field[1], "%Y%m%d%H%M")
-            times.append(np.datetime64(stamp, "s"))
-            records.append(field[2])
-            statuses.append(field[3])
-            lats.append(_parse_latitude(field[4]))
-            lons.append(_parse_longitude(field[5]))
-            winds.append(float(field[6]))
-            pressures.append(float(field[7]))
-            radii.append([[float(field[8 + group * 4 + quadrant]) for quadrant in range(4)] for group in range(3)])
-            rmws.append(float(field[20]) if len(field) > 20 else MISSING)
-
-        def as_nan(values):
-            return np.where(np.asarray(values, dtype=np.float32) == MISSING, np.nan, values)
-
-        tracks.append(
-            Track(
-                storm_id=storm_id, name=name, time=np.array(times),
-                latitude=np.asarray(lats, dtype=np.float32), longitude=np.asarray(lons, dtype=np.float32),
-                max_wind_kt=as_nan(winds), min_pressure_hpa=as_nan(pressures),
-                status=np.asarray(statuses), rmw_nmi=as_nan(rmws),
-                wind_radii_nmi=as_nan(np.asarray(radii, dtype=np.float32)),
-                record=np.asarray(records),
-            )
-        )
-    return tracks
-
-
-def rapid_intensification(
-    tracks: list[Track], threshold_kt: float = 30.0, window_hours: int = 24, tropical_only: bool = True
-) -> dict:
-    """
-    Label rapid intensification and report how rare it actually is.
-
-    The National Hurricane Center defines RI as an increase in maximum sustained wind of at least 30 kt
-    in 24 hours. This walks every track, marks the points from which that happens, and returns both the
-    labels and the base rate -- because the base rate is the number that decides how the head must be
-    trained. A classifier that always says "no" will score in the high nineties on this task and be
-    worthless, so accuracy is not the metric and class weighting is not optional.
-
-    Args:
-        tracks: parsed best tracks.
-        threshold_kt: intensification that counts as rapid.
-        window_hours: the window it must happen within.
-        tropical_only: restrict to tropical classifications (TD/TS/HU), which is the usual convention --
-            extratropical transition can show a wind rise that is not intensification in this sense.
-
-    Returns:
-        ``{"labels": {storm_id: bool array}, "base_rate": float, "positives": int, "eligible": int,
-        "delta": {storm_id: float array}}``
-    """
-    tropical = {"TD", "TS", "HU"}
-    labels, deltas, positives, eligible = {}, {}, 0, 0
-
-    for track in tracks:
-        wind = track.max_wind_kt
-        seconds = track.time.astype("datetime64[s]").astype(np.int64)
-        change = np.full(len(track), np.nan, dtype=np.float32)
-        for i in range(len(track)):
-            if tropical_only and track.status[i] not in tropical:
-                continue
-            if not np.isfinite(wind[i]):
-                continue
-            horizon = seconds[i] + window_hours * 3600
-            reachable = np.where((seconds > seconds[i]) & (seconds <= horizon))[0]
-            if reachable.size == 0:
-                continue
-            future = wind[reachable]
-            if not np.isfinite(future).any():
-                continue
-            change[i] = float(np.nanmax(future) - wind[i])
-        flag = np.isfinite(change) & (change >= threshold_kt)
-        labels[track.storm_id] = flag
-        deltas[track.storm_id] = change
-        positives += int(flag.sum())
-        eligible += int(np.isfinite(change).sum())
-
-    return {
-        "labels": labels, "delta": deltas, "positives": positives, "eligible": eligible,
-        "base_rate": positives / max(eligible, 1),
-        "threshold_kt": threshold_kt, "window_hours": window_hours,
-    }
-
-
-def split_by_storm(
-    tracks: list[Track], validation_years: tuple[int, ...] = (2017, 2019, 2021, 2023),
-    test_years: tuple[int, ...] = (2018, 2020, 2022, 2024),
-) -> dict[str, list[Track]]:
-    """
-    Split by *season*, never by track point.
-
-    This is the one that quietly ruins best-track models. Six-hourly points from the same storm are
-    almost the same picture: split them at random and near-duplicates land on both sides, validation
-    looks superb, and the model has memorised storms rather than learned anything. Holding out whole
-    seasons also keeps a storm's environment -- that year's ENSO state, that year's sea-surface
-    temperatures -- out of training entirely, which is the honest test.
-    """
-    groups = {"train": [], "validation": [], "test": []}
-    for track in tracks:
-        year = track.year
-        key = "validation" if year in validation_years else "test" if year in test_years else "train"
-        groups[key].append(track)
-    return groups

naturev1/checkpoint.py

@@ -1,408 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Checkpointing that assumes the process will be killed without warning.
-
-On a hosted notebook that is not a worst case, it is the normal case: the cell is reclaimed, the runtime
-recycles, the tab closes. So every save here is written to a temporary file and then renamed into place,
-because rename is atomic on every filesystem that matters -- there is no instant at which the live
-checkpoint is half-written. A process killed mid-save leaves a stray temporary file and an intact
-previous checkpoint, which is the outcome you want.
-
-Resuming restores everything that makes a run reproducible, not just the weights: optimizer moments,
-the learning-rate schedule, the gradient scaler, the epoch and step counters, and the random states of
-Python, NumPy and Torch. Restoring weights alone gives you a run that silently reshuffles its data and
-restarts its schedule, which looks like it resumed and did not.
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import random
-import shutil
-import time
-from dataclasses import dataclass
-from pathlib import Path
-
-import torch
-
-from .safeio import atomic_copy, atomic_torch_save, atomic_write_text, remove_stale_temporaries
-
-
-@dataclass
-class TrainingState:
-    """Everything needed to continue a run exactly where it stopped."""
-
-    step: int = 0
-    epoch: int = 0
-    samples_seen: int = 0
-    best_loss: float = float("inf")
-    wall_seconds: float = 0.0
-    history: list = None
-
-    def __post_init__(self) -> None:
-        if self.history is None:
-            self.history = []
-
-    def to_dict(self) -> dict:
-        return {
-            "step": self.step, "epoch": self.epoch, "samples_seen": self.samples_seen,
-            "best_loss": self.best_loss, "wall_seconds": self.wall_seconds,
-            "history": self.history[-500:],
-        }
-
-
-def _rng_state() -> dict:
-    state = {"python": random.getstate(), "torch": torch.get_rng_state()}
-    try:
-        import numpy as np
-
-        state["numpy"] = np.random.get_state()
-    except ImportError:
-        pass
-    if torch.cuda.is_available():
-        state["cuda"] = torch.cuda.get_rng_state_all()
-    return state
-
-
-def _restore_rng(state: dict) -> None:
-    if not state:
-        return
-    random.setstate(state["python"])
-    torch.set_rng_state(state["torch"].cpu() if torch.is_tensor(state["torch"]) else state["torch"])
-    if "numpy" in state:
-        import numpy as np
-
-        np.random.set_state(state["numpy"])
-    if "cuda" in state and torch.cuda.is_available():
-        try:
-            torch.cuda.set_rng_state_all([s.cpu() for s in state["cuda"]])
-        except (RuntimeError, ValueError):
-            # A different GPU count than the run that saved it: keep going with fresh CUDA seeds.
-            pass
-
-
-class CheckpointManager:
-    """
-    Periodic, crash-safe checkpoints with optional mirroring to the Hugging Face Hub.
-
-    Args:
-        directory: where checkpoints live. On Colab, point this at Google Drive so it outlives the VM.
-        every_seconds: minimum wall time between saves. Saving is cheap next to a training step, so a
-            minute is a reasonable default; the cost is bounded by the size of the model, not the data.
-        keep: how many recent checkpoints to retain, oldest pruned first.
-        repo_id: Hub repository to mirror to, e.g. ``"you/NatureV1"``. Needs ``HF_TOKEN`` in the
-            environment or a prior ``huggingface-cli login``.
-        push_every_seconds: uploads are slower than local writes, so they get their own, longer interval.
-        snapshot_every_seconds: how often a numbered copy is kept beside ``latest.pt``. With the
-            optimizer state a checkpoint of the full model is about a gigabyte; copying it on every
-            one-minute save wrote two gigabytes a minute to Google Drive and left the GPU waiting on
-            the disk. ``latest.pt`` is still rewritten every ``every_seconds``.
-        backup_dir: a second folder that gets its own copy of the checkpoint, as often as the numbered
-            snapshots, in ``<backup_dir>/<tag>/latest.pt`` -- so deleting or damaging the run's folder
-            does not lose the run. Defaults to the ``NATUREV1_BACKUP_DIR`` environment variable, which
-            the cell sets; empty turns it off. Loading falls back to it when nothing local is usable.
-    """
-
-    LATEST = "latest.pt"
-
-    def __init__(
-        self,
-        directory: str | Path,
-        every_seconds: float = 60.0,
-        keep: int = 3,
-        repo_id: str | None = None,
-        push_every_seconds: float = 900.0,
-        private: bool = False,
-        snapshot_every_seconds: float = 1800.0,
-        backup_dir: str | Path | None = None,
-    ) -> None:
-        self.directory = Path(directory)
-        self.directory.mkdir(parents=True, exist_ok=True)
-        self.every_seconds = every_seconds
-        self.keep = keep
-        self.repo_id = repo_id
-        self.push_every_seconds = push_every_seconds
-        self.snapshot_every_seconds = snapshot_every_seconds
-        self.private = private
-        self._last_save = 0.0
-        self._last_push = 0.0
-        self._last_snapshot = 0.0
-        self._upload = None
-        self._warned_token = False
-        self._warned_disk = 0.0
-        backup_dir = os.environ.get("NATUREV1_BACKUP_DIR") if backup_dir is None else backup_dir
-        self.backup = Path(backup_dir) / self.tag / self.LATEST if backup_dir else None
-        # A save killed part-way leaves a gigabyte-sized temporary behind; restarted runs piled them up.
-        freed = remove_stale_temporaries(self.directory)
-        if self.backup is not None and self.backup.parent.exists():
-            freed += remove_stale_temporaries(self.backup.parent)
-        if freed:
-            print(f"[checkpoint] removed {freed / 1e9:.2f} GB of half-written saves from killed runs", flush=True)
-
-    @property
-    def tag(self) -> str:
-        """Which run this directory holds -- ``stage1``, ``stage2``, ``rollout`` -- for the Hub path."""
-        return self.directory.name or "run"
-
-    @property
-    def hub_path(self) -> str:
-        """
-        Where this run's checkpoint lives in the Hub repository.
-
-        One path per run. Every stage used to push to the same ``latest.pt``, so on a fresh machine a
-        stage pulled whichever stage had pushed last: stage two resumed from stage one's step count,
-        found itself past its own ``max_steps`` and stopped without training anything.
-        """
-        return f"checkpoints/{self.tag}/{self.LATEST}"
-
-    # ------------------------------------------------------------------ saving --
-
-    def due(self) -> bool:
-        """Whether enough time has passed to warrant another save."""
-        return (time.time() - self._last_save) >= self.every_seconds
-
-    def save(
-        self,
-        model: torch.nn.Module,
-        optimizer: torch.optim.Optimizer | None,
-        scheduler=None,
-        scaler=None,
-        state: TrainingState | None = None,
-        config: dict | None = None,
-        force: bool = False,
-    ) -> Path | None:
-        """
-        Write a checkpoint if one is due. Returns the path written, or None if it was skipped.
-
-        The write goes to a temporary file first and is renamed into place, so an interrupted save can
-        never leave a corrupt ``latest.pt`` behind.
-        """
-        if not force and not self.due():
-            return None
-        state = state or TrainingState()
-        payload = {
-            "model": model.state_dict(),
-            "optimizer": optimizer.state_dict() if optimizer is not None else None,
-            "scheduler": scheduler.state_dict() if scheduler is not None else None,
-            "scaler": scaler.state_dict() if scaler is not None else None,
-            "state": state.to_dict(),
-            "config": config or {},
-            "rng": _rng_state(),
-            "saved_at": time.time(),
-            "format": 2,
-            "tag": self.tag,
-        }
-
-        target = self.directory / self.LATEST
-        record = json.dumps(state.to_dict(), indent=2, default=str) + "\n"
-        try:
-            atomic_torch_save(payload, target)  # atomic; readers see either the old file or the new one
-            if force or (time.time() - self._last_snapshot) >= self.snapshot_every_seconds:
-                self._prune(make_room=True)
-                atomic_copy(target, self.directory / f"step_{state.step:09d}.pt")
-                self._prune()
-                self._last_snapshot = time.time()
-                self._back_up(target, record)
-            atomic_write_text(self.directory / "state.json", record)
-        except OSError as error:
-            # A full disk used to crash the run here, and every restart crashed again at its first
-            # save. The previous checkpoint is intact (the write is atomic), so keep training and say so.
-            self._last_save = time.time()
-            if time.time() - self._warned_disk > 600:
-                print(f"[checkpoint] !! could not save ({type(error).__name__}: {error}). Training goes on "
-                      f"and the last good checkpoint is kept; free some disk space in {self.directory}.",
-                      flush=True)
-                self._warned_disk = time.time()
-            return None
-        self._last_save = time.time()
-        self._maybe_push(target, state)
-        return target
-
-    def _back_up(self, target: Path, record: str) -> None:
-        if self.backup is None:
-            return
-        try:
-            atomic_copy(target, self.backup)
-            atomic_write_text(self.backup.parent / "state.json", record)
-        except OSError as error:
-            print(f"[checkpoint] backup to {self.backup.parent} skipped ({type(error).__name__}: {error})",
-                  flush=True)
-
-    def _prune(self, make_room: bool = False) -> None:
-        """Keep the newest ``keep`` snapshots -- one fewer just before writing another, so a full disk
-        is not needed to hold ``keep + 1`` of them at once."""
-        numbered = sorted(self.directory.glob("step_*.pt"))
-        keep = max(self.keep - 1, 1) if make_room else self.keep
-        for stale in numbered[: max(0, len(numbered) - keep)]:
-            stale.unlink(missing_ok=True)
-
-    def push_now(self, state: TrainingState, timeout: float = 120.0) -> bool:
-        """
-        Push the latest checkpoint to the Hub right now and wait for it -- for the end of a session.
-
-        A hosted notebook that is being shut down sends SIGTERM and gives a process a little time. The
-        regular push is on a timer and runs on a thread that would die with the process; this one
-        ignores the timer and blocks, so the last checkpoint reaches the Hub. Returns whether it did.
-        """
-        if not self.repo_id or not (self.directory / self.LATEST).exists():
-            return False
-        if self._upload is not None and self._upload.is_alive():
-            self._upload.join(timeout)
-        self._last_push = 0.0
-        self._maybe_push(self.directory / self.LATEST, state)
-        if self._upload is None:
-            return False
-        self._upload.join(timeout)
-        return not self._upload.is_alive()
-
-    def _maybe_push(self, path: Path, state: TrainingState) -> None:
-        """
-        Mirror the checkpoint to the Hub, in the background, at most every ``push_every_seconds``.
-
-        Two things this used to get wrong. A failed push -- no token, no network -- did not reset the
-        timer, so it was retried and reported on every one-minute save for the rest of the run. And a
-        successful one ran on the training thread: a gigabyte upload stopped training for minutes
-        every quarter hour. Now a failure waits a full interval like a success, and the upload runs
-        on its own thread from a copy, so ``latest.pt`` can keep being replaced underneath it.
-        """
-        if not self.repo_id or (time.time() - self._last_push) < self.push_every_seconds:
-            return
-        self._last_push = time.time()
-        if self._upload is not None and self._upload.is_alive():
-            return                                    # the previous upload is still going; skip this one
-        try:
-            from huggingface_hub import get_token
-        except ImportError:
-            get_token = None
-        if get_token is not None and not (os.environ.get("HF_TOKEN") or get_token()):
-            if not self._warned_token:
-                print("[checkpoint] no Hugging Face token: checkpoints stay local (set HF_TOKEN to mirror "
-                      "them to the Hub)", flush=True)
-                self._warned_token = True
-            return
-
-        snapshot = self.directory / ".push.pt"
-        try:
-            shutil.copy2(path, snapshot)
-        except OSError as error:
-            print(f"[checkpoint] Hub push skipped: {type(error).__name__}: {error}", flush=True)
-            return
-        step, tag, repo, hub_path, private = state.step, self.tag, self.repo_id, self.hub_path, self.private
-
-        def upload() -> None:
-            began = time.time()
-            try:
-                from huggingface_hub import HfApi
-
-                try:
-                    # The upload library draws two progress bars straight into the training log, a few
-                    # hundred lines per push. One line saying it happened is what the log needs.
-                    from huggingface_hub.utils import disable_progress_bars
-
-                    disable_progress_bars()
-                except ImportError:
-                    pass
-                api = HfApi()
-                api.create_repo(repo, repo_type="model", exist_ok=True, private=private)
-                api.upload_file(path_or_fileobj=str(snapshot), path_in_repo=hub_path, repo_id=repo,
-                                repo_type="model", commit_message=f"{tag} step {step}")
-                print(f"[checkpoint] pushed {tag} step {step:,} to {repo} "
-                      f"({snapshot.stat().st_size / 1e9:.2f} GB in {time.time() - began:.0f} s)", flush=True)
-            except Exception as error:  # a failed upload must never kill a training run
-                print(f"[checkpoint] Hub push skipped: {type(error).__name__}: {error}", flush=True)
-
-        import threading
-
-        self._upload = threading.Thread(target=upload, name="hub-push", daemon=True)
-        self._upload.start()
-
-    # ----------------------------------------------------------------- loading --
-
-    def load(
-        self,
-        model: torch.nn.Module,
-        optimizer: torch.optim.Optimizer | None = None,
-        scheduler=None,
-        scaler=None,
-        map_location: str = "cpu",
-        strict: bool = True,
-    ) -> TrainingState | None:
-        """
-        Restore the newest usable checkpoint, falling back through older ones if the newest is damaged.
-
-        Returns the :class:`TrainingState` to continue from, or None when there is nothing to resume.
-        """
-        for path in self._candidates():
-            try:
-                payload = torch.load(path, map_location=map_location, weights_only=False)
-            except Exception as error:
-                print(f"[checkpoint] {path.name} unreadable ({type(error).__name__}), trying an older one", flush=True)
-                continue
-            try:
-                model.load_state_dict(payload["model"], strict=strict)
-            except RuntimeError as error:
-                # A checkpoint from a different configuration -- 24 input channels where the model now
-                # has 96, say -- cannot be resumed. Crashing here strands the user; resuming into it is
-                # impossible. Set it aside where it can still be recovered, say so, and move on.
-                self._quarantine(path, error)
-                continue
-            if optimizer is not None and payload.get("optimizer"):
-                try:
-                    optimizer.load_state_dict(payload["optimizer"])
-                except (ValueError, KeyError, RuntimeError) as error:
-                    print(f"[checkpoint] optimizer state not restored ({type(error).__name__}: the set of "
-                          "trainable parameters changed); weights are restored, moments restart", flush=True)
-            if scheduler is not None and payload.get("scheduler"):
-                scheduler.load_state_dict(payload["scheduler"])
-            if scaler is not None and payload.get("scaler"):
-                scaler.load_state_dict(payload["scaler"])
-            _restore_rng(payload.get("rng", {}))
-            state = TrainingState(**payload["state"])
-            self._last_save = time.time()
-            where = f"the backup in {path.parent}" if path == self.backup else path.name
-            print(f"[checkpoint] resumed {where} at step {state.step} (epoch {state.epoch})", flush=True)
-            return state
-        return None
-
-    def _quarantine(self, path: Path, error: Exception) -> None:
-        """Move an incompatible checkpoint out of the way, keeping it recoverable."""
-        aside = self.directory / "incompatible"
-        aside.mkdir(exist_ok=True)
-        destination = aside / f"{int(time.time())}_{path.name}"
-        shutil.move(str(path), destination)
-        reason = str(error).splitlines()[0][:200]
-        print(f"[checkpoint] {path.name} was trained with a different configuration and cannot be "
-              f"resumed ({reason}). Moved to {destination}; starting this run fresh.", flush=True)
-
-    def _candidates(self) -> list[Path]:
-        latest = self.directory / self.LATEST
-        numbered = sorted(self.directory.glob("step_*.pt"), reverse=True)
-        backup = [self.backup] if self.backup is not None and self.backup.exists() else []
-        return ([latest] if latest.exists() else []) + numbered + backup
-
-    def fetch_from_hub(self) -> bool:
-        """
-        Pull this run's checkpoint from the Hub when the local directory is empty -- a fresh VM, same run.
-
-        Reads :attr:`hub_path`. Releases before 0.8 pushed every stage to a bare ``latest.pt``; that
-        file is accepted only for ``stage1``, the one stage it can safely be assumed to belong to.
-        """
-        if not self.repo_id or (self.directory / self.LATEST).exists():
-            return False
-        if self.backup is not None and self.backup.exists():
-            return False                              # a backup on this machine comes before a download
-        from huggingface_hub import hf_hub_download
-
-        sources = [self.hub_path] + ([self.LATEST] if self.tag == "stage1" else [])
-        for filename in sources:
-            try:
-                downloaded = hf_hub_download(repo_id=self.repo_id, filename=filename, repo_type="model")
-            except Exception as error:
-                last = error
-                continue
-            shutil.copy2(downloaded, self.directory / self.LATEST)
-            print(f"[checkpoint] pulled {filename} from {self.repo_id}", flush=True)
-            return True
-        print(f"[checkpoint] nothing to pull from the Hub for {self.tag} ({type(last).__name__})", flush=True)
-        return False

naturev1/corpora.py

@@ -1,174 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The corpora, and why there are two of them.
-
-Best-track archives are labels, not a training set. HURDAT2 holds 55,230 Atlantic track points across
-174 years; rapid intensification at the 30-knot threshold fires on 1,839 of them; radius of maximum wind
-is reported on 2,587. Fitting 89M parameters to that would memorise storms and call it learning, and the
-validation score would look wonderful right up until a storm it had not seen.
-
-So the model is trained twice.
-
-**Stage one is self-supervised on reanalysis**, where the label is free: given the atmosphere now,
-predict it six hours from now. ERA5 covers 1959 to 2022 at hourly resolution, which is 561,024 timesteps
-and, at a modest 240x121 grid with 84 variables, about 2.3e11 values. That is roughly three million times
-the size of the best-track record, it needs no annotation, and it is where the backbone actually learns
-what the atmosphere does.
-
-**Stage two fine-tunes the storm heads** on best tracks with the backbone frozen, so the parameters
-actually fitted to those scarce labels number under a million rather than eighty-nine.
-
-There is also a free multiplier available here that most architectures do not get. This model is exactly
-equivariant to rotating the globe about its axis -- verified to float64 round-off -- so shifting a storm
-in longitude produces a genuinely different sample that is guaranteed physically consistent, rather than
-the approximate augmentation a pixel-grid model would be forced to settle for.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-import numpy as np
-import torch
-
-
-@dataclass(frozen=True)
-class Corpus:
-    """One public dataset, with the numbers that decide whether it is worth the bandwidth."""
-
-    name: str
-    uri: str
-    span: str
-    cadence: str
-    approx_samples: int
-    role: str
-    notes: str
-
-
-#: Everything below is public and needs no account except ERA5 via Copernicus (free registration).
-CORPORA = (
-    Corpus(
-        "WeatherBench 2 (ERA5)", "gs://weatherbench2/datasets/era5/", "1959-2022", "1h and 6h",
-        561_024, "pretraining",
-        "Analysis-ready Zarr from 64x32 up to 1440x721. The 6-hourly 240x121 store holds 92,040 verified "
-        "timesteps; the hourly stores hold six times that. Start here.",
-    ),
-    Corpus(
-        "ARCO-ERA5", "gs://gcp-public-data-arco-era5/ar/", "1940-present", "1h",
-        745_000, "pretraining",
-        "Same data, longer span, chunked for random access. Use when you outgrow WeatherBench 2.",
-    ),
-    Corpus(
-        "GOES-19 / GOES-18 ABI", "s3://noaa-goes19/, s3://noaa-goes18/", "2017-present", "5-10 min",
-        1_800_000, "pretraining + live",
-        "16 bands, both hemispheres of the Americas. GOES-16 is retired and its bucket returns nothing.",
-    ),
-    Corpus(
-        "TC-PRIMED", "s3://noaa-nesdis-tcprimed-pds/v01r01/", "1998-present", "per overpass",
-        180_000, "storm fine-tuning",
-        "Satellite overpasses already paired with best-track position and intensity. Purpose-built for "
-        "exactly this task and the single highest-value dataset for the storm heads.",
-    ),
-    Corpus(
-        "IBTrACS v04r01",
-        "https://www.ncei.noaa.gov/data/international-best-track-archive-for-climate-stewardship-ibtracs/"
-        "v04r01/access/csv/ibtracs.ALL.list.v04r01.csv",
-        "1842-present", "3-6h", 585_000, "labels",
-        "Global, every basin. About seven times the Atlantic-only HURDAT2 record -- use this, not HURDAT2, "
-        "unless you specifically want Atlantic.",
-    ),
-    Corpus(
-        "HURDAT2 Atlantic", "https://www.nhc.noaa.gov/data/hurdat/", "1851-2024", "6h",
-        55_230, "labels",
-        "Highest-quality reanalysed Atlantic tracks. Carries radius of maximum wind and wind radii, which "
-        "IBTrACS does less consistently -- but only on ~5% of points.",
-    ),
-    Corpus(
-        "SHIPS developmental data", "https://rammb2.cira.colostate.edu/research/tropical-cyclones/ships/",
-        "1982-present", "6h", 120_000, "storm fine-tuning",
-        "The environmental predictors operational RI forecasting is built on: shear, ocean heat content, "
-        "mid-level humidity, persistence. Precomputed per storm. Feed these as the environment channels.",
-    ),
-    Corpus(
-        "OISST v2.1 sea-surface temperature", "s3://noaa-cdr-sea-surface-temp-optimum-interpolation-pds/",
-        "1981-present", "daily", 16_000, "environment",
-        "Sea-surface temperature drives intensification. Daily quarter-degree, the standard choice.",
-    ),
-)
-
-
-def catalogue() -> str:
-    """A printable summary of the corpora, their sizes and what each is for."""
-    lines = [f"{'dataset':28} {'span':16} {'cadence':10} {'samples':>10}  role"]
-    lines.append("-" * 88)
-    for corpus in CORPORA:
-        lines.append(
-            f"{corpus.name:28} {corpus.span:16} {corpus.cadence:10} {corpus.approx_samples:>10,}  {corpus.role}"
-        )
-    return "\n".join(lines)
-
-
-def open_weatherbench(
-    resolution: str = "1959-2022-6h-240x121_equiangular_with_poles_conservative.zarr",
-    variables: tuple[str, ...] = (
-        "2m_temperature", "mean_sea_level_pressure", "10m_u_component_of_wind",
-        "10m_v_component_of_wind", "total_precipitation_6hr", "sea_surface_temperature",
-    ),
-):
-    """
-    Open the WeatherBench 2 ERA5 archive straight from cloud storage, lazily.
-
-    Nothing downloads until a chunk is actually read, so a training run streams what it needs instead of
-    staging terabytes first. ``pip install zarr gcsfs xarray`` and no credentials are required.
-
-    Args:
-        resolution: one of the WeatherBench 2 store names. 240x121 six-hourly is the sensible default;
-            drop to 64x32 to debug a pipeline, rise to 1440x721 when you have the bandwidth.
-        variables: which fields to keep.
-    """
-    import xarray as xr
-
-    store = f"gs://weatherbench2/datasets/era5/{resolution}"
-    dataset = xr.open_zarr(store, storage_options={"token": "anon"}, consolidated=True)
-    keep = [name for name in variables if name in dataset]
-    missing = set(variables) - set(keep)
-    if missing:
-        print(f"[corpora] not in this store, skipping: {sorted(missing)}")
-    return dataset[keep]
-
-
-def latlon_to_coords(latitudes: np.ndarray, longitudes: np.ndarray) -> torch.Tensor:
-    """Turn a latitude/longitude mesh in degrees into the radian coordinate pairs a grid expects."""
-    lat_mesh, lon_mesh = np.meshgrid(latitudes, longitudes, indexing="ij")
-    return torch.tensor(
-        np.stack([np.radians(lat_mesh.ravel()), np.radians(lon_mesh.ravel()) % (2 * np.pi)], -1),
-        dtype=torch.float64,
-    )
-
-
-def rotate_longitude(coords: torch.Tensor, radians: float) -> torch.Tensor:
-    """
-    Shift every sample in longitude -- an augmentation that is exact for this architecture.
-
-    The local strand reads displacements in each sample's own east/north/up frame, which turns with the
-    sample, so a longitude shift produces identical arithmetic on genuinely different data. A pixel-grid
-    model has to roll an array and accept the seam; here the operation is a symmetry of the model, which
-    makes it free and physically honest. Because it preserves latitude it also preserves the Coriolis
-    parameter and the climate zone, so the augmented sample is still a possible atmosphere.
-    """
-    shifted = coords.clone()
-    shifted[:, 1] = torch.remainder(shifted[:, 1] + radians, 2 * torch.pi)
-    return shifted
-
-
-def augment_batch(coords: torch.Tensor, generator: torch.Generator | None = None) -> torch.Tensor:
-    """Apply a random longitude rotation, the safe augmentation for a global field."""
-    angle = float(torch.rand((), generator=generator) * 2 * torch.pi)
-    return rotate_longitude(coords, angle)
-
-
-def estimate_epoch(num_samples: int, samples_per_second: float) -> dict:
-    """Wall time for one pass over a corpus at a measured throughput."""
-    seconds = num_samples / max(samples_per_second, 1e-9)
-    return {"samples": num_samples, "samples_per_second": samples_per_second,
-            "hours": seconds / 3600, "days": seconds / 86400}

naturev1/cyclone/__init__.py

@@ -1,53 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Tropical-cyclone physics that needs no neural network -- tracks, intensity, genesis -- built to beat
-extrapolation at every lead, and measured doing so on seasons it never saw.
-
-Every module is one idea:
-
-==========================  =================================================================================
-geometry                    great-circle moves and storm-centred frames; NHC along/cross-track errors
-fields                      analysis boxes with spherical calculus and pressure-weighted layer means
-data                        hindcast cases from IBTrACS + WeatherBench 2 ERA5 boxes, chunk-aware and resumable
-verify                      homogeneous verification with storm-block bootstrap confidence intervals
-baselines                   every extrapolation (6 h, 12 h, great-circle) and the strongest of them per lead
-kalman                      robust (Huber) Kalman motion estimate with damped acceleration
-cliper                      CLIPER rebuilt: poleward frame, three motion windows, exact local displacements
-analogs                     track-shape analogs rotated to the storm's heading, as departures from persistence
-vortex                      the storm removed from the analysis by local Biot-Savart inversion
-steering                    eight steering layers, intensity-dependent layer, case-adaptive optimal layer
-beta                        beta drift from the vortex's outer strength and the absolute-vorticity gradient
-trajectory                  RK4 on the sphere through flows sampled where the storm will be
-bogus                       vortex bogus specified by outer circulation, for the barotropic model
-barotropic                  limited-area barotropic vorticity model (Arakawa Jacobian, exact sine-transform
-                            Poisson solver, sponge): beta gyres emerge, the environment evolves
-vorticity_advection         motion from the vorticity budget, independent of the best track
-climatology                 ERA5 1981-2010 flow climatology; steering anomalies damped with lead time
-stall                       cols and stagnation points of the steering flow: Dorian's stall, detected
-ridge                       subtropical ridge axis, strength, tendency, weakness and the upstream trough
-shear                       vertical shear in seven layer pairs, generalised shear, vortex tilt
-reformation                 competing centres and downshear re-formation toward the convection
-ensemble                    physics ensemble with data-void-aware flow perturbations (the Bermuda High problem)
-regimes                     stall / recurve / high / weak / straight classification
-consensus                   along- and cross-track weights per lead, fitted on past seasons
-members                     the member suite computed from one analysis
-ocean                       cold wake under slow storms (the ocean fighting back)
-land                        landfall timing, inland and terrain decay along the forecast track
-intensity                   SHIFOR, SHIPS-style and LGEM-style intensity along the forecast track
-structure                   outermost closed isobar, gale radius, size evolution
-outflow                     200 hPa divergence, eddy flux convergence, outflow channels, trough interaction
-field_tracker               GFDL-style multi-field tracker for any gridded forecast
-teachers                    GraphCast, Pangu, HRES, Aurora, FGN, FuXi, GenCast tracks on the same storms
-genesis                     disturbance detection, tracking and a 48-hour genesis probability
-pouch                       the wave-relative marsupial pouch
-synthetic                   Dorian-type and other hard scenarios with known truth, and balanced vortex implants
-fit / coefficients          the constants, fitted once on disjoint data and shipped as code
-benchmark                   the hindcast benchmark and its report
-forecast                    :func:`physics_forecast`, everything in one call (``swarm=N`` adds
-                            :mod:`naturev1.swarm`, which works alongside it)
-==========================  =================================================================================
-"""
-
-from .forecast import physics_forecast
-
-__all__ = ["physics_forecast"]

naturev1/cyclone/aids.py

@@ -1,213 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The operational guidance blended in.
-
-The NHC's a-deck carries every aid's track and intensity for a cycle minutes after it. Two tables fitted on the
-tuning seasons (``coefficients.ADECK_TRACK``, ``coefficients.ADECK_INTENSITY``) say how much of each aid to take
-beside our own forecast, lead by lead. The weights are renormalised over the members present, so a missing aid never
-breaks the blend, and a retired model's slot can be taken by its successor (``substitutes``: HAFS-A for HWRF, HAFS-B
-for HMON, TVCN for HCCA) -- a stand-in by lineage, reported as such, not a verified member.
-
-Reading the decks is :mod:`naturev1.swarm.adeck`; this module is the arithmetic, with no network.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from . import geometry as geo
-
-
-def resolve(available: dict, members, substitutes: dict | None = None) -> tuple[dict, dict]:
-    """The members present in ``available`` (``{tech: array}``), a substitute standing in for an absent one.
-    Returns ``(chosen {member: array}, substituted {member: stand-in})``; ``"ours"`` is never looked up."""
-    chosen, subs = {}, {}
-    for m in members:
-        if m == "ours":
-            continue
-        v = available.get(m)
-        if v is not None and np.isfinite(np.asarray(v, np.float64)).any():
-            chosen[m] = np.asarray(v, np.float64)
-            continue
-        for s in (substitutes or {}).get(m, ()):
-            v = available.get(s)
-            if v is not None and np.isfinite(np.asarray(v, np.float64)).any():
-                chosen[m] = np.asarray(v, np.float64)
-                subs[m] = s
-                break
-    return chosen, subs
-
-
-def _weights(table: dict, leads) -> np.ndarray:
-    """(L, M) weights at the caller's leads: the nearest lead of the table."""
-    tl = np.asarray(table["leads"], np.float64)
-    W = np.asarray(table["weights"], np.float64)
-    return W[[int(np.argmin(np.abs(tl - float(h)))) for h in leads]]
-
-
-def _share(members, w: np.ndarray, s: np.ndarray) -> dict:
-    share = w / np.maximum(s, 1e-9)[:, None]
-    return {m: float(np.mean(share[:, j])) for j, m in enumerate(members) if share[:, j].any()}
-
-
-def previous_errors(case, previous_time, previous_tracks: dict, leads) -> dict:
-    """
-    How far each member's previous-cycle forecast was from the position now analysed: ``{member: km}`` for the
-    members in ``previous_tracks`` (``{member: (L, 2) track issued at previous_time}``), the previous track
-    interpolated to the gap between the cycles (6-24 h; nothing outside that). This is what the adaptive weights of
-    :func:`blend_track` are earned from -- the member that caught the last turn keeps more of its vote.
-    """
-    out = {}
-    try:
-        gap = float((np.datetime64(case.time, "m") - np.datetime64(previous_time, "m")) / np.timedelta64(60, "m"))
-    except Exception:
-        return out
-    if not (5.5 <= gap <= 24.5):
-        return out
-    hours = np.asarray(leads, np.float64)
-    for member, t in previous_tracks.items():
-        t = np.asarray(t, np.float64) if t is not None else None
-        if t is None or t.ndim != 2 or t.shape[0] != len(hours):
-            continue
-        ok = np.isfinite(t[:, 0]) & np.isfinite(t[:, 1])
-        if ok.sum() < 1 or hours[ok].max() < gap:
-            continue
-        lat = np.interp(gap, hours[ok], t[ok, 0])
-        lon = np.interp(gap, hours[ok], t[ok, 1])
-        out[member] = float(geo.great_circle_km(lat, lon, float(case.lat), float(case.lon)))
-    return out
-
-
-def adaptive_weights(table: dict, leads, previous: dict | None) -> np.ndarray | None:
-    """
-    The weight of ours against the table's first aid, per lead, from the previous cycle's verified errors:
-    ``w_ours = clip(sigmoid(b * log((e_aid + eps) / (e_ours + eps))), 1 - cap, cap)``, with ``b`` per lead from
-    ``table["adaptive"]`` (zero where the tuning seasons found nothing to earn). None without the table or the errors.
-    """
-    adaptive = table.get("adaptive")
-    if not adaptive or not previous:
-        return None
-    members = list(table["members"])
-    aid = members[1] if len(members) > 1 else None
-    e_ours, e_aid = previous.get("ours"), previous.get(aid)
-    if e_ours is None or e_aid is None:
-        return None
-    eps = float(adaptive.get("eps_km", 5.0))
-    cap = float(adaptive.get("cap", 0.75))
-    tl = np.asarray(table["leads"], np.float64)
-    b = np.asarray(adaptive["b"], np.float64)[[int(np.argmin(np.abs(tl - float(h)))) for h in leads]]
-    r = np.log((float(e_aid) + eps) / (float(e_ours) + eps))
-    return np.clip(1.0 / (1.0 + np.exp(-b * r)), 1.0 - cap, cap)
-
-
-def outlier_gate(table: dict, leads, X: np.ndarray, cone_km) -> np.ndarray | None:
-    """
-    The disagreement gate: when ours and the first aid sit further apart than ``start`` cone radii, up to ``gamma`` of
-    the pair's weight moves away from whichever of the two is further from the tie-breaker aid (TVCN) -- on the
-    tuning seasons a tie, on held-out 1-2% at 12-120 h, a loss at 6 h, so it starts at ``min_lead_h``. Returns the
-    signed shift of ours' share per lead (negative: away from ours), or None without the table entry, the
-    tie-breaker or the cone.
-    """
-    gate = table.get("gate")
-    if not gate or cone_km is None:
-        return None
-    members = list(table["members"])
-    tb = gate.get("tiebreaker", "TVCN")
-    if len(members) < 2 or tb not in members:
-        return None
-    k = members.index(tb)
-    cone = np.asarray(cone_km, np.float64)
-    if cone.shape != (len(leads),):
-        return None
-    d_oh = np.hypot(X[:, 0, 0] - X[:, 1, 0], X[:, 0, 1] - X[:, 1, 1])
-    d_ot = np.hypot(X[:, 0, 0] - X[:, k, 0], X[:, 0, 1] - X[:, k, 1])
-    d_ht = np.hypot(X[:, 1, 0] - X[:, k, 0], X[:, 1, 1] - X[:, k, 1])
-    ok = np.isfinite(d_oh) & np.isfinite(d_ot) & np.isfinite(d_ht) & np.isfinite(cone) & (cone > 0) & (np.asarray(leads, np.float64) >= float(gate.get("min_lead_h", 12)))
-    shift = float(gate.get("gamma", 0.1)) * np.clip(np.where(ok, d_oh / np.maximum(cone, 1e-6), 0.0) - float(gate.get("start_cone_radii", 1.5)), 0.0, 1.0)
-    return np.where(ok, np.where(d_ot > d_ht, -shift, shift), 0.0)
-
-
-def blend_track(case, track, aids: dict, leads, table: dict, previous_errors: dict | None = None, cone_km=None) -> tuple[np.ndarray, dict | None]:
-    """
-    Our track blended with the aids' tracks in local displacement space (km east and north of the analysis
-    position), weights per lead renormalised over the members present at that lead.
-
-    Args:
-        track: our (L, 2) latitude/longitude at ``leads``.
-        aids: ``{tech: (L, 2)}`` at the same leads (:func:`naturev1.swarm.adeck.aids_at`).
-        table: ``{"members": ["ours", ...], "leads", "weights" (L, M), "substitutes": {member: [stand-ins]},
-            "adaptive": {"b": per lead, "cap", "eps_km"}}``.
-        previous_errors: ``{member: km}`` from :func:`previous_errors` -- with the table's ``adaptive`` entry the
-            split between ours and the first aid is earned from them (the other aids keep their table weights).
-        cone_km: this forecast's cone radius per lead -- with the table's ``gate`` entry the split also moves away
-            from whichever of ours and the first aid stands alone against the tie-breaker (:func:`outlier_gate`).
-
-    Returns:
-        ``(track, used)``: the blended track and ``{"members", "substituted", "weight_share", "disagreement_km"
-        (ours against the first aid, per lead), "adaptive_w_ours" (when earned), "gate_shift" (when applied)}``, or
-        ``(track unchanged, None)`` when none of the table's aids is present.
-    """
-    members = list(table["members"])
-    chosen, subs = resolve(aids or {}, members, table.get("substitutes"))
-    track = np.asarray(track, np.float64)
-    if not chosen:
-        return track, None
-    L, M = len(leads), len(members)
-    la0, lo0 = float(case.lat), float(case.lon)
-    X = np.full((L, M, 2), np.nan)
-    for j, m in enumerate(members):
-        t = track if m == "ours" else chosen.get(m)
-        if t is None or np.asarray(t).shape != (L, 2):
-            continue
-        e, n = geo.local_displacement_km(la0, lo0, np.asarray(t)[:, 0], np.asarray(t)[:, 1])
-        X[:, j, 0], X[:, j, 1] = e, n
-    W = _weights(table, leads).copy()
-    used: dict = {"members": [m for m in members if m in chosen], "substituted": subs}
-    if M > 1:
-        pair = W[:, 0] + W[:, 1]                               # the ours / first-aid share, split by what was earned ...
-        split = np.where(pair > 0, W[:, 0] / np.maximum(pair, 1e-9), 0.5)
-        w_ours = adaptive_weights(table, leads, previous_errors)
-        if w_ours is not None:
-            split = w_ours
-            used["adaptive_w_ours"] = w_ours
-            used["previous_errors_km"] = dict(previous_errors)
-        shift = outlier_gate(table, leads, X, cone_km)          # ... and moved away from the member that stands alone
-        if shift is not None and np.any(shift != 0):
-            split = np.clip(split + shift, 0.0, 1.0)
-            used["gate_shift"] = shift
-        W[:, 0], W[:, 1] = pair * split, pair * (1.0 - split)
-    ok = np.isfinite(X).all(-1)
-    w = np.where(ok, W, 0.0)
-    s = w.sum(-1)
-    D = (np.nan_to_num(X) * w[..., None]).sum(1) / np.maximum(s, 1e-9)[:, None]
-    lat, lon = geo.move(la0, lo0, D[:, 0], D[:, 1])
-    out = np.where((s > 0)[:, None], np.stack([np.asarray(lat, np.float64), np.asarray(lon, np.float64)], -1), track)
-    used["weight_share"] = _share(members, w, s)
-    if M > 1 and ok[:, 1].any():
-        used["disagreement_km"] = np.where(ok[:, 0] & ok[:, 1], np.hypot(X[:, 0, 0] - X[:, 1, 0], X[:, 0, 1] - X[:, 1, 1]), np.nan)
-    return out, used
-
-
-def blend_intensity(intensity, aids: dict, leads, table: dict) -> tuple[np.ndarray, dict | None]:
-    """Our intensity (kt at ``leads``) blended with the aids' intensities, as :func:`blend_track`; clipped to 15-200 kt."""
-    members = list(table["members"])
-    chosen, subs = resolve(aids or {}, members, table.get("substitutes"))
-    intensity = np.asarray(intensity, np.float64)
-    if not chosen:
-        return intensity, None
-    L, M = len(leads), len(members)
-    X = np.full((L, M), np.nan)
-    for j, m in enumerate(members):
-        v = intensity if m == "ours" else chosen.get(m)
-        if v is not None and np.asarray(v).shape == (L,):
-            X[:, j] = v
-    W = _weights(table, leads)
-    ok = np.isfinite(X)
-    w = np.where(ok, W, 0.0)
-    s = w.sum(-1)
-    out = np.where(s > 0, (np.nan_to_num(X) * w).sum(-1) / np.maximum(s, 1e-9), intensity)
-    out = np.where(np.isfinite(out), np.clip(out, 15.0, 200.0), out)
-    return out, {"members": [m for m in members if m in chosen], "substituted": subs, "weight_share": _share(members, w, s)}
-
-
-__all__ = ["adaptive_weights", "blend_intensity", "blend_track", "outlier_gate", "previous_errors", "resolve"]

naturev1/cyclone/analogs.py

@@ -1,136 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Track-shape analogs: storms that were moving *like this one*, turned to face the same way.
-
-The idea: CLIPER is a regression -- it averages every storm into one linear rule. Analogs are the
-non-parametric opposite: find the historical storms whose recent track looked most like this one's, and see
-what they did next. Two refinements make it work far from the classic version:
-
-* **rotation to the motion frame** -- each historical case is stored with its future displacements rotated
-  so that its last 12 hours of motion point along the same axis. A storm heading north-west at 5 m/s is then
-  compared with every storm that was turning and accelerating the same way, wherever it was heading, and its
-  future is rotated back onto this storm's heading. Curvature and acceleration -- the shape of the track --
-  are what is matched, not the compass direction;
-* **context still counts** -- latitude, longitude within the basin, season and intensity enter the distance,
-  so a turning storm at 28 N is matched with turning storms near the ridge, not in the deep tropics.
-
-What is stored and averaged is each analog's *departure from persistence* (its future minus carrying on at its
-own current speed and heading), added back onto this storm's own current motion -- so the first hours inherit
-the storm's exact motion and the analogs contribute the turns and speed changes that follow.
-
-Futures are combined with Gaussian kernel weights over the nearest analogs; the poleward frame mirrors the
-southern hemisphere so both share one database. The database is built from best tracks
-(:meth:`AnalogDatabase.from_cases`) -- for the benchmark, 1980-2014 only.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .geometry import from_local, local_displacement_km, rotate, wrap_longitude
-
-#: Feature scales (one unit of distance per scale).
-SCALES = {"lat": 4.0, "lon": 15.0, "season": 0.5, "wind": 30.0, "speed": 6.0, "turn": 15.0, "accel": 4.0, "turn24": 20.0}
-
-
-def _shape_features(case):
-    """``(features, heading_deg)`` in the poleward frame, or None without a 12-hour history."""
-    from .cliper import GROUPS
-    from .data import HISTORY_HOURS
-
-    h = list(HISTORY_HOURS)
-    lat, lon = case.history["lat"], case.history["lon"]
-    sign = -1.0 if case.lat < 0 else 1.0
-
-    def leg(a, b):
-        i, j = h.index(a), h.index(b)
-        if not (np.isfinite(lat[i]) and np.isfinite(lat[j])):
-            return None
-        e, n = local_displacement_km(lat[i], lon[i], lat[j], lon[j])
-        return np.array([e, sign * n]) / ((b - a))
-    m0 = leg(-6, 0)
-    m1 = leg(-12, -6)
-    if m0 is None or m1 is None:
-        return None
-    m2 = leg(-24, -12)
-    heading = np.degrees(np.arctan2(m0[0], m0[1]))
-    def angle(a, b):
-        return float((np.degrees(np.arctan2(a[0], a[1]) - np.arctan2(b[0], b[1])) + 180.0) % 360.0 - 180.0)
-    turn = angle(m0, m1)
-    turn24 = angle(m0, m2) if m2 is not None else turn
-    speed = float(np.hypot(*m0)) / 3.6
-    accel = speed - float(np.hypot(*m1)) / 3.6
-    _, reference = GROUPS.get(case.basin, ("NA", 0.0))
-    day = (np.datetime64(case.time, "D") - np.datetime64(str(case.time)[:4] + "-01-01", "D")).astype(int)
-    phase = 2 * np.pi * ((day + (182 if sign < 0 else 0)) % 365) / 365.0
-    wind = case.wind_kt if np.isfinite(case.wind_kt) else 50.0
-    f = np.array([abs(case.lat) / SCALES["lat"], wrap_longitude(case.lon - reference) / SCALES["lon"],
-                  np.cos(phase) / SCALES["season"], np.sin(phase) / SCALES["season"], wind / SCALES["wind"],
-                  speed / SCALES["speed"], turn / SCALES["turn"], accel / SCALES["accel"], turn24 / SCALES["turn24"]])
-    return f, float(heading)
-
-
-class AnalogDatabase:
-    """Historical cases' shape features and their futures in the motion-aligned poleward frame."""
-
-    def __init__(self, features: np.ndarray, futures: np.ndarray, groups: np.ndarray, leads) -> None:
-        self.features, self.futures, self.groups, self.leads = features, futures, groups, list(leads)
-
-    @classmethod
-    def from_cases(cls, cases, leads) -> "AnalogDatabase":
-        from .cliper import group_of
-
-        feats, futs, groups = [], [], []
-        for c in cases:
-            got = _shape_features(c)
-            if got is None:
-                continue
-            f, heading = got
-            sign = -1.0 if c.lat < 0 else 1.0
-            speed_kmh = f[5] * SCALES["speed"] * 3.6
-            fut = np.full((len(leads), 2), np.nan)
-            for k in range(len(leads)):
-                if c.truth["valid"][k]:
-                    e, n = local_displacement_km(c.lat, c.lon, c.truth["lat"][k], c.truth["lon"][k])
-                    # Rotate so the storm's current heading points north, then keep only what departs from
-                    # carrying on straight at the current speed: the analog's *deviation* from persistence.
-                    re, rn = rotate(e, sign * n, heading)
-                    fut[k] = re, rn - speed_kmh * leads[k]
-            feats.append(f)
-            futs.append(fut)
-            groups.append(group_of(c))
-        return cls(np.asarray(feats), np.asarray(futs), np.asarray(groups), leads)
-
-    def forecast(self, case, neighbours: int = 60, bandwidth: float = 1.0, same_group: bool = True) -> np.ndarray:
-        """``(L, 2)`` lat/lon: the kernel-weighted mean future of the nearest analogs, rotated to this heading."""
-        from .cliper import group_of
-
-        out = np.full((len(self.leads), 2), np.nan)
-        got = _shape_features(case)
-        if got is None or len(self.features) == 0:
-            return out
-        f, heading = got
-        speed_kmh = f[5] * SCALES["speed"] * 3.6
-        pool = self.groups == group_of(case) if same_group else np.ones(len(self.groups), bool)
-        if pool.sum() < neighbours:
-            pool = np.ones(len(self.groups), bool)
-        idx = np.nonzero(pool)[0]
-        d2 = ((self.features[idx] - f) ** 2).sum(1)
-        order = idx[np.argsort(d2)[:neighbours]]
-        weights = np.exp(-0.5 * np.sort(d2)[:neighbours] / bandwidth ** 2)
-        sign = -1.0 if case.lat < 0 else 1.0
-        for k in range(len(self.leads)):
-            fut = self.futures[order, k]
-            ok = np.isfinite(fut[:, 0])
-            if ok.sum() < 5:
-                continue
-            w = weights[ok] / weights[ok].sum()
-            east, north = (fut[ok] * w[:, None]).sum(0)
-            north = north + speed_kmh * self.leads[k]
-            east, north = rotate(east, north, -heading)
-            lat, lon = from_local(case.lat, case.lon, east, sign * north)
-            out[k] = lat, lon
-        return out
-
-
-__all__ = ["AnalogDatabase", "SCALES"]

naturev1/cyclone/barotropic.py

@@ -1,240 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-A limited-area barotropic vorticity model: the storm and its environment evolving together.
-
-The idea (NHC's LBAR, Vic Ooyama's barotropic legacy): a frozen steering flow is wrong by day three, because
-ridges and troughs move. The deep-layer flow is, to a good first approximation, barotropic, so it can be
-*forecast* by conserving absolute vorticity -- cheaply, without any of the physics a full model needs. And a
-vortex embedded in that flow develops its own beta gyres and drifts with them; nothing about beta drift has
-to be prescribed. This model:
-
-* lives on a square grid in the storm-centred azimuthal-equidistant plane (exact distances from the storm,
-  no pole problem), with the true Coriolis parameter at every point (not a beta-plane approximation);
-* starts from the analysis's deep-layer environmental wind (vortex removed, winds rotated into the grid's
-  frame), plus a bogus vortex whose outer circulation matches the analysis's (:mod:`naturev1.cyclone.bogus`);
-* steps ``dzeta/dt = -J(psi, zeta + f) - nu4 del^4 zeta`` with Arakawa's energy- and enstrophy-conserving
-  Jacobian and a third-order strong-stability-preserving Runge-Kutta scheme;
-* inverts vorticity for the streamfunction exactly, every stage, with a fast sine transform (Dirichlet
-  boundary values from the analysis flow integrated around the domain's edge, held fixed: the large scale
-  outside the box does not change -- the limitation LBAR also had);
-* relaxes a sponge at the edge back to the analysis, so waves leave instead of reflecting;
-* tracks the vortex as the maximum of cyclonic vorticity near its previous position, refined to sub-grid
-  precision by a quadratic fit.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .bogus import alpha_for_size, bogus_vorticity
-from .fields import Environment
-from .geometry import OMEGA, bearing_deg, from_local, hemisphere
-
-GRID_KM = 80.0
-CELLS = 73                        # 5760 km across
-STEP_S = 900.0
-SPONGE_CELLS = 6
-SPONGE_TAU_S = 3 * 3600.0
-#: Grid-scale damping time of the hyperdiffusion, s.
-DAMPING_S = 6 * 3600.0
-#: Deep-layer mean used for the environment (top, bottom) hPa, and the bogus's share of the 850 hPa outer wind.
-LAYER = (300.0, 850.0)
-DEEP_FRACTION = 0.8
-
-
-def dst1(a: np.ndarray, axis: int = -1) -> np.ndarray:
-    """Type-I discrete sine transform along ``axis`` via an odd extension and the FFT (no scipy needed)."""
-    a = np.moveaxis(a, axis, -1)
-    n = a.shape[-1]
-    zero = np.zeros(a.shape[:-1] + (1,))
-    extended = np.concatenate([zero, a, zero, -a[..., ::-1]], -1)
-    spectrum = np.fft.rfft(extended, axis=-1)
-    out = -spectrum[..., 1:n + 1].imag / 2.0
-    return np.moveaxis(out, -1, axis)
-
-
-class PoissonSolver:
-    """Exact solution of the 5-point ``del^2 psi = zeta`` with Dirichlet boundary values on a square grid."""
-
-    def __init__(self, cells: int, spacing_m: float) -> None:
-        self.n, self.h = cells, spacing_m
-        m = cells - 2
-        k = np.arange(1, m + 1)
-        lam = (2.0 * np.cos(np.pi * k / (m + 1)) - 2.0) / spacing_m ** 2
-        self.eigen = lam[:, None] + lam[None, :]
-        self.norm = (2.0 / (m + 1)) ** 2
-
-    def solve(self, zeta: np.ndarray, boundary: np.ndarray) -> np.ndarray:
-        """``zeta`` and ``boundary`` are full ``(n, n)``; boundary values are read from the edge of ``boundary``."""
-        h2 = self.h ** 2
-        rhs = zeta[1:-1, 1:-1].copy()
-        rhs[0, :] -= boundary[0, 1:-1] / h2
-        rhs[-1, :] -= boundary[-1, 1:-1] / h2
-        rhs[:, 0] -= boundary[1:-1, 0] / h2
-        rhs[:, -1] -= boundary[1:-1, -1] / h2
-        spec = dst1(dst1(rhs, 0), 1) / self.eigen
-        inner = dst1(dst1(spec, 0), 1) * self.norm
-        psi = boundary.copy()
-        psi[1:-1, 1:-1] = inner
-        return psi
-
-
-def arakawa_jacobian(psi: np.ndarray, q: np.ndarray, h: float) -> np.ndarray:
-    """J(psi, q) = psi_x q_y - psi_y q_x on interior points (Arakawa 1966), rows = y, columns = x."""
-    p, z = psi, q
-    pe, pw, pn, ps = p[1:-1, 2:], p[1:-1, :-2], p[2:, 1:-1], p[:-2, 1:-1]
-    qe, qw, qn, qs = z[1:-1, 2:], z[1:-1, :-2], z[2:, 1:-1], z[:-2, 1:-1]
-    pne, pnw, pse, psw = p[2:, 2:], p[2:, :-2], p[:-2, 2:], p[:-2, :-2]
-    qne, qnw, qse, qsw = z[2:, 2:], z[2:, :-2], z[:-2, 2:], z[:-2, :-2]
-    j1 = (pe - pw) * (qn - qs) - (pn - ps) * (qe - qw)
-    j2 = pe * (qne - qse) - pw * (qnw - qsw) - pn * (qne - qnw) + ps * (qse - qsw)
-    j3 = qn * (pne - pnw) - qs * (pse - psw) - qe * (pne - pse) + qw * (pnw - psw)
-    out = np.zeros_like(psi)
-    out[1:-1, 1:-1] = (j1 + j2 + j3) / (12.0 * h * h)
-    return out
-
-
-def laplacian(f: np.ndarray, h: float) -> np.ndarray:
-    out = np.zeros_like(f)
-    out[1:-1, 1:-1] = (f[1:-1, 2:] + f[1:-1, :-2] + f[2:, 1:-1] + f[:-2, 1:-1] - 4 * f[1:-1, 1:-1]) / (h * h)
-    return out
-
-
-class BarotropicModel:
-    """
-    One storm's barotropic forecast. Build from an analysis (vortex already removed), then :meth:`run`.
-
-    Args:
-        env: the environmental analysis (``remove_vortex(...).environment``).
-        lat0, lon0: the storm's position.
-        outer_ms: the outer strength of its vortex at 850 hPa (:func:`naturev1.cyclone.beta.outer_strength`).
-        r34_nmi: best-track gale radius, for the profile's outer decay (NaN for the default).
-    """
-
-    def __init__(self, env: Environment, lat0: float, lon0: float, outer_ms: float, r34_nmi: float = float("nan"),
-                 cells: int = CELLS, grid_km: float = GRID_KM, rmax_km: float | None = None) -> None:
-        self.lat0, self.lon0 = float(lat0), float(lon0)
-        self.n, self.h = cells, grid_km * 1000.0
-        half = (cells - 1) / 2.0
-        axis = (np.arange(cells) - half) * grid_km
-        self.x, self.y = np.meshgrid(axis, axis)                          # km; rows y (north), columns x (east)
-        lat, lon = from_local(self.lat0, self.lon0, self.x, self.y)
-        self.lat, self.lon = lat, lon
-        self.f = 2.0 * OMEGA * np.sin(np.radians(lat))
-        # The grid's own x-axis direction at each point, as a geographic bearing.
-        lat_e, lon_e = from_local(self.lat0, self.lon0, self.x + 1.0, self.y)
-        theta = np.radians(bearing_deg(lat, lon, lat_e, lon_e))
-        ex_e, ex_n = np.sin(theta), np.cos(theta)
-        u = env.sample(env.layer_mean("u", *LAYER), lat, lon)
-        v = env.sample(env.layer_mean("v", *LAYER), lat, lon)
-        ux = u * ex_e + v * ex_n
-        uy = -u * ex_n + v * ex_e
-        self.sign = float(hemisphere(self.lat0))
-        # Environmental vorticity on the grid, and the boundary streamfunction from the edge flow.
-        zeta_env = np.zeros_like(ux)
-        zeta_env[1:-1, 1:-1] = ((uy[1:-1, 2:] - uy[1:-1, :-2]) - (ux[2:, 1:-1] - ux[:-2, 1:-1])) / (2 * self.h)
-        zeta_env[0, :], zeta_env[-1, :], zeta_env[:, 0], zeta_env[:, -1] = (zeta_env[1, :], zeta_env[-2, :],
-                                                                           zeta_env[:, 1], zeta_env[:, -2])
-        self.boundary = self._edge_streamfunction(ux, uy)
-        r = np.hypot(self.x, self.y)
-        rmax = max(rmax_km or 0.0, 2.5 * grid_km)
-        self.zeta_env = zeta_env
-        self.zeta0 = zeta_env + bogus_vorticity(r, DEEP_FRACTION * outer_ms, rmax, alpha_for_size(r34_nmi), self.sign)
-        self.solver = PoissonSolver(cells, self.h)
-        k = np.pi / self.h
-        self.nu4 = 1.0 / (DAMPING_S * k ** 4)
-        distance = np.minimum.reduce([np.arange(cells)[None, :] + 0 * self.x, (cells - 1 - np.arange(cells))[None, :] + 0 * self.x,
-                                      np.arange(cells)[:, None] + 0 * self.x, (cells - 1 - np.arange(cells))[:, None] + 0 * self.x])
-        self.sponge = np.where(distance < SPONGE_CELLS, (1.0 - distance / SPONGE_CELLS) ** 2 / SPONGE_TAU_S, 0.0)
-
-    def _edge_streamfunction(self, ux: np.ndarray, uy: np.ndarray) -> np.ndarray:
-        """psi on the edge from d psi = v dx - u dy integrated counter-clockwise; net divergence spread evenly."""
-        n, h = self.n, self.h
-        loop = ([(0, j) for j in range(n)] + [(i, n - 1) for i in range(1, n)]
-                + [(n - 1, j) for j in range(n - 2, -1, -1)] + [(i, 0) for i in range(n - 2, 0, -1)])
-        values = [0.0]
-        for (i0, j0), (i1, j1) in zip(loop[:-1], loop[1:]):
-            um = 0.5 * (ux[i0, j0] + ux[i1, j1])
-            vm = 0.5 * (uy[i0, j0] + uy[i1, j1])
-            dx, dy = (j1 - j0) * h, (i1 - i0) * h
-            values.append(values[-1] + vm * dx - um * dy)
-        i0, j0 = loop[-1]
-        i1, j1 = loop[0]
-        closing = values[-1] + 0.5 * (uy[i0, j0] + uy[i1, j1]) * (j1 - j0) * h - 0.5 * (ux[i0, j0] + ux[i1, j1]) * (i1 - i0) * h
-        boundary = np.zeros((n, n))
-        total = len(loop)
-        for k, (i, j) in enumerate(loop):
-            boundary[i, j] = values[k] - closing * k / total
-        return boundary
-
-    def _tendency(self, zeta: np.ndarray) -> tuple[np.ndarray, np.ndarray]:
-        psi = self.solver.solve(zeta, self.boundary)
-        tend = -arakawa_jacobian(psi, zeta + self.f, self.h)
-        tend -= self.nu4 * laplacian(laplacian(zeta, self.h), self.h)
-        tend -= self.sponge * (zeta - self.zeta_env)
-        tend[0, :] = tend[-1, :] = tend[:, 0] = tend[:, -1] = 0.0
-        return tend, psi
-
-    def _locate(self, zeta: np.ndarray, near: tuple[float, float], search_km: float = 450.0) -> tuple[float, float]:
-        field = self.sign * zeta
-        smooth = field.copy()
-        smooth[1:-1, 1:-1] = (field[1:-1, 1:-1] * 4 + field[1:-1, 2:] + field[1:-1, :-2] + field[2:, 1:-1]
-                              + field[:-2, 1:-1]) / 8.0
-        mask = np.hypot(self.x - near[0], self.y - near[1]) < search_km
-        mask[:2, :] = mask[-2:, :] = mask[:, :2] = mask[:, -2:] = False
-        if not mask.any():
-            return near
-        candidate = np.where(mask, smooth, -np.inf)
-        i, j = np.unravel_index(int(np.argmax(candidate)), candidate.shape)
-        c, e, w, nn, s = smooth[i, j], smooth[i, j + 1], smooth[i, j - 1], smooth[i + 1, j], smooth[i - 1, j]
-        dx = 0.5 * (w - e) / (w - 2 * c + e) if (w - 2 * c + e) < 0 else 0.0
-        dy = 0.5 * (s - nn) / (s - 2 * c + nn) if (s - 2 * c + nn) < 0 else 0.0
-        step = self.h / 1000.0
-        return float(self.x[i, j] + np.clip(dx, -0.5, 0.5) * step), float(self.y[i, j] + np.clip(dy, -0.5, 0.5) * step)
-
-    def run(self, leads, return_fields: bool = False) -> dict:
-        """Integrate to the last lead; returns ``{"track": (L, 2) lat/lon, "xy": (L, 2) km, "speed_ms": (L,)}``."""
-        leads = [float(h) for h in leads]
-        zeta = self.zeta0.copy()
-        position = (0.0, 0.0)
-        out_xy, fields = [], []
-        t, k = 0.0, 0
-        end = max(leads)
-        dt = STEP_S
-        while k < len(leads) and leads[k] <= 0:
-            out_xy.append(position)
-            k += 1
-        steps_per_hour = 3600.0 / dt
-        step = 0
-        while t < end - 1e-9:
-            k1, _ = self._tendency(zeta)
-            z1 = zeta + dt * k1
-            k2, _ = self._tendency(z1)
-            z2 = 0.75 * zeta + 0.25 * (z1 + dt * k2)
-            k3, _ = self._tendency(z2)
-            zeta = zeta / 3.0 + 2.0 / 3.0 * (z2 + dt * k3)
-            step += 1
-            t = step / steps_per_hour
-            if step % int(steps_per_hour) == 0:
-                position = self._locate(zeta, position)
-            while k < len(leads) and leads[k] <= t + 1e-9:
-                position = self._locate(zeta, position)
-                out_xy.append(position)
-                if return_fields:
-                    fields.append(zeta.copy())
-                k += 1
-        xy = np.asarray(out_xy)
-        lat, lon = from_local(self.lat0, self.lon0, xy[:, 0], xy[:, 1])
-        result = {"track": np.stack([lat, lon], -1), "xy": xy}
-        if return_fields:
-            result["zeta"] = fields
-        return result
-
-
-def barotropic_track(env_clean: Environment, case, outer_ms: float, leads) -> np.ndarray:
-    """``(L, 2)`` lat/lon from one barotropic forecast of ``case``."""
-    model = BarotropicModel(env_clean, case.lat, case.lon, outer_ms, getattr(case, "r34_nmi", float("nan")))
-    return model.run(leads)["track"]
-
-
-__all__ = ["BarotropicModel", "PoissonSolver", "arakawa_jacobian", "barotropic_track", "dst1", "laplacian"]

naturev1/cyclone/baselines.py

@@ -1,95 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The baselines a track model has to beat, defined exactly -- and all of them, so "beats extrapolation" is not
-won against a strawman.
-
-* ``xtrp12``: the classic: the last 12 hours of motion continued in a straight line in latitude and
-  longitude (NHC's XTRP; also what :func:`naturev1.steering.extrapolation_track` does).
-* ``xtrp6``: the same with the last 6 hours -- noisier, but closer to now.
-* ``xtrp_gc``: the 12-hour motion continued along the great circle (constant speed, the initial bearing
-  turning as the sphere requires) -- what extrapolation should mean at high latitude.
-* ``persistence``: intensity stays what it is now.
-
-:func:`strongest_extrapolation` returns, per lead, the best of the extrapolations on a given sample, the
-baseline every claim in the benchmark is made against.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .geometry import bearing_deg, destination, great_circle_km, wrap_longitude
-
-
-def _past(case, hours: int):
-    from .data import HISTORY_HOURS
-
-    k = HISTORY_HOURS.index(-hours)
-    lat, lon = case.history["lat"][k], case.history["lon"][k]
-    return (lat, lon) if np.isfinite(lat) and np.isfinite(lon) else None
-
-
-def motion_back(case, hours: int):
-    """``(dlat, dlon)`` degrees per hour over the last ``hours``, falling back to the other window."""
-    for h in (hours, 12 if hours == 6 else 6):
-        past = _past(case, h)
-        if past is not None:
-            dlon = wrap_longitude(case.lon - past[1])
-            return (case.lat - past[0]) / h, dlon / h
-    return None
-
-
-def xtrp_latlon(case, leads, hours: int = 12) -> np.ndarray:
-    """Linear extrapolation in latitude and longitude; ``(L, 2)``."""
-    rate = motion_back(case, hours)
-    out = np.full((len(leads), 2), np.nan)
-    if rate is None:
-        return out
-    for k, lead in enumerate(leads):
-        out[k] = case.lat + rate[0] * lead, wrap_longitude(case.lon + rate[1] * lead)
-    return out
-
-
-def xtrp_great_circle(case, leads, hours: int = 12) -> np.ndarray:
-    past = _past(case, hours) or _past(case, 6 if hours == 12 else 12)
-    out = np.full((len(leads), 2), np.nan)
-    if past is None:
-        return out
-    span = hours if _past(case, hours) is not None else (6 if hours == 12 else 12)
-    speed = great_circle_km(past[0], past[1], case.lat, case.lon) / span
-    # Bearing of motion *at* the current position: the back-bearing to the past fix, reversed.
-    heading = (bearing_deg(case.lat, case.lon, past[0], past[1]) + 180.0) % 360.0
-    for k, lead in enumerate(leads):
-        out[k] = destination(case.lat, case.lon, heading, speed * lead)
-    return out
-
-
-def persistence_intensity(case, leads) -> np.ndarray:
-    return np.full(len(leads), case.wind_kt)
-
-
-def baseline_tracks(cases, leads) -> dict[str, np.ndarray]:
-    return {"xtrp12": np.stack([xtrp_latlon(c, leads, 12) for c in cases]),
-            "xtrp6": np.stack([xtrp_latlon(c, leads, 6) for c in cases]),
-            "xtrp_gc": np.stack([xtrp_great_circle(c, leads, 12) for c in cases])}
-
-
-def strongest_extrapolation(errors: dict[str, np.ndarray], names=("xtrp12", "xtrp6", "xtrp_gc")) -> np.ndarray:
-    """
-    Per case and lead, the error of whichever extrapolation has the lowest *mean* error at that lead on
-    this sample -- chosen per lead with hindsight, which only makes the baseline harder to beat.
-    """
-    mask = None
-    for n in names:
-        ok = np.isfinite(errors[n])
-        mask = ok if mask is None else mask & ok
-    out = np.full_like(errors[names[0]], np.nan)
-    for k in range(out.shape[1]):
-        means = [np.nanmean(np.where(mask[:, k], errors[n][:, k], np.nan)) for n in names]
-        best = names[int(np.nanargmin(means))]
-        out[:, k] = errors[best][:, k]
-    return out
-
-
-__all__ = ["baseline_tracks", "motion_back", "persistence_intensity", "strongest_extrapolation", "xtrp_great_circle",
-           "xtrp_latlon"]

naturev1/cyclone/benchmark.py

@@ -1,105 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The benchmark: every member, the consensus and the baselines on whole seasons -- and the teachers on the same
-storms -- verified homogeneously, with storm-block bootstrap intervals.
-
-:func:`run_season` computes the member suite (:func:`naturev1.cyclone.members.run_members`) for every case of
-a built season in parallel processes and caches the forecasts; :func:`benchmark` scores them against the
-strongest extrapolation, CLIPER and any teacher tracks given, and :func:`report` writes the table a reader
-needs: mean track error per lead, sample sizes, skill and whether its whole 90% interval clears zero.
-"""
-
-from __future__ import annotations
-
-import json
-import multiprocessing as mp
-import pickle
-from pathlib import Path
-
-import numpy as np
-
-from .data import LEADS, Season
-
-_WORKER: dict = {}
-
-
-def _init(season_dir: str, climatology_path: str | None, analogs_path: str | None, members) -> None:
-    from .climatology import Climatology
-
-    _WORKER["season"] = Season(season_dir)
-    _WORKER["climatology"] = Climatology(climatology_path) if climatology_path else None
-    _WORKER["analogs"] = pickle.load(open(analogs_path, "rb")) if analogs_path else None
-    _WORKER["members"] = tuple(members)
-
-
-def _one(i: int):
-    from .members import run_members
-
-    season = _WORKER["season"]
-    case = season.cases[i]
-    try:
-        out = run_members(case, season.environment(i), _WORKER["climatology"], _WORKER["analogs"], names=_WORKER["members"])
-    except Exception as error:                       # one bad case must not end a season
-        return case.key, {"_error": repr(error)}
-    keep = {k: v for k, v in out.items() if not k.startswith("_")}
-    if "_ensemble" in out:
-        keep["ensemble_spread_km"] = out["_ensemble"]["spread_km"]
-    return case.key, keep
-
-
-def run_season(season_dir: str | Path, out_path: str | Path, climatology_path=None, analogs_path=None, members=None,
-               processes: int = 4, log=print) -> dict:
-    """Member forecasts for every case of a season, cached in ``out_path`` (a pickle)."""
-    from .members import DEFAULT_MEMBERS
-
-    out_path = Path(out_path)
-    if out_path.exists():
-        return pickle.load(open(out_path, "rb"))
-    members = members or DEFAULT_MEMBERS
-    season = Season(season_dir)
-    results = {}
-    with mp.Pool(processes, initializer=_init, initargs=(str(season_dir), climatology_path and str(climatology_path),
-                                                          analogs_path and str(analogs_path), members)) as pool:
-        for n, (key, value) in enumerate(pool.imap(_one, range(len(season)), chunksize=8), start=1):
-            results[key] = value
-            if log and n % 250 == 0:
-                log(f"[benchmark] {Path(season_dir).name}: {n}/{len(season)}")
-    pickle.dump(results, open(out_path, "wb"))
-    return results
-
-
-def consensus_tracks(cases, results: dict, table: dict | None = None) -> np.ndarray:
-    """``(N, L, 2)`` the shipped consensus (:data:`naturev1.cyclone.coefficients.CONSENSUS`) of cached members."""
-    from .consensus import apply_consensus
-
-    if table is None:
-        from .coefficients import CONSENSUS as table
-    nan = np.full((len(LEADS), 2), np.nan)
-    stack = np.stack([np.stack([results.get(c.key, {}).get(m, nan) for c in cases]) for m in table["members"]], 2)
-    return apply_consensus(cases, stack, table)
-
-
-def benchmark(cases, forecasts: dict, baseline: str = "best_xtrp", samples: int = 1000) -> dict:
-    """Homogeneous comparison of ``forecasts`` (``{name: (N, L, 2)}``) against the strongest extrapolation."""
-    from .baselines import baseline_tracks, strongest_extrapolation
-    from .verify import compare, track_errors
-
-    base = baseline_tracks(cases, LEADS)
-    errors = {k: track_errors(cases, v) for k, v in base.items()}
-    errors = {"best_xtrp": strongest_extrapolation(errors)}
-    for name, f in forecasts.items():
-        errors[name] = track_errors(cases, f)
-    return compare(cases, errors, baseline, LEADS, samples=samples)
-
-
-def report(result: dict, title: str) -> str:
-    from .verify import format_comparison
-
-    return format_comparison(result, title)
-
-
-def save_result(result: dict, path: str | Path) -> None:
-    Path(path).write_text(json.dumps(result, indent=1, default=float))
-
-
-__all__ = ["benchmark", "consensus_tracks", "report", "run_season", "save_result"]

naturev1/cyclone/beta.py

@@ -1,82 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Beta drift that depends on the storm and on the air around it, not a fixed 1 m/s north-west.
-
-The idea: a vortex on a sphere drifts because its own winds carry planetary vorticity around it, spinning up
-a pair of "beta gyres" whose flow pushes the vortex poleward and westward (Holland 1983; Chan and Williams
-1987; Fiorino and Elsberry 1989). Two facts from that theory are used here, where a fixed vector ignores both:
-
-* **Speed scales with the vortex's outer strength** -- the tangential wind 300-800 km out, not the eyewall --
-  and with the planetary vorticity gradient. A large, strong-outer-wind typhoon drifts at 3-4 m/s; a small,
-  compact hurricane at well under 1. The outer strength is measured from the vortex that
-  :func:`naturev1.cyclone.vortex.remove_vortex` took out of the analysis; the gradient is beta at the storm's
-  latitude.
-* **Direction follows the gradient of absolute vorticity, not just of f** -- the drift is up the gradient of
-  ``sign(f) * (f + zeta_environment)``, turned towards the west by the gyre angle. Where the environment's own
-  vorticity gradient is strong (the flank of a monsoon trough, the edge of a ridge), the drift turns with it.
-
-The scale constants are physical defaults checked on the 2016/2017/2019 seasons only.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .fields import Environment
-from .geometry import beta as beta_at, hemisphere, rotate
-from .steering import disc_smooth
-
-#: Drift speed for a storm at 20 degrees with an outer tangential wind of 6 m/s, m/s.
-DRIFT_MS = 1.6
-#: Angle from the up-gradient direction towards the west, degrees.
-GYRE_ANGLE_DEG = 40.0
-#: Outer-strength radii, km, and the clip on the measured strength, m/s.
-OUTER_RADII_KM = (300.0, 400.0, 500.0, 600.0, 700.0, 800.0)
-OUTER_CLIP_MS = (1.0, 15.0)
-
-
-def outer_strength(split, level_hpa: int = 850) -> float:
-    """Mean cyclonic tangential wind of the removed vortex between 300 and 800 km at ``level_hpa``, m/s."""
-    levels = list(split.environment.levels)
-    k = levels.index(level_hpa) if level_hpa in levels else int(np.argmin([abs(p - level_hpa) for p in levels]))
-    profile = split.tangential_profile(k, OUTER_RADII_KM)
-    value = float(np.nanmean(profile)) if np.isfinite(profile).any() else 4.0
-    return float(np.clip(value, *OUTER_CLIP_MS))
-
-
-class BetaDrift:
-    """
-    Drift velocity anywhere in the box for a vortex of a given outer strength.
-
-    ``eta_gradient`` is the smoothed gradient of the environment's deep-layer absolute vorticity, so the
-    drift direction responds to the environment as well as to the planet.
-    """
-
-    def __init__(self, env: Environment, outer_ms: float, top: float = 300.0, bottom: float = 850.0,
-                 smoothing_km: float = 800.0, drift_ms: float | None = None, angle_deg: float | None = None) -> None:
-        self.env, self.outer_ms = env, outer_ms
-        self.drift_ms = DRIFT_MS if drift_ms is None else drift_ms
-        self.angle_deg = GYRE_ANGLE_DEG if angle_deg is None else angle_deg
-        u = env.layer_mean("u", top, bottom)
-        v = env.layer_mean("v", top, bottom)
-        zeta = env.vorticity(u, v)
-        self.smoothing_km = smoothing_km
-        self.gx = disc_smooth(env, env.ddx(zeta), smoothing_km)
-        self.gy = disc_smooth(env, env.ddy(zeta), smoothing_km)
-
-    def velocity(self, lat, lon) -> tuple[np.ndarray, np.ndarray]:
-        lat = np.atleast_1d(np.asarray(lat, np.float64))
-        lon = np.atleast_1d(np.asarray(lon, np.float64))
-        b = beta_at(lat)
-        gx = self.env.sample(self.gx, lat, lon)
-        gy = self.env.sample(self.gy, lat, lon) + b
-        sign = hemisphere(lat)
-        gx, gy = sign * gx, sign * gy
-        size = np.hypot(gx, gy)
-        speed = self.drift_ms * np.sqrt(np.clip(size / beta_at(20.0), 0.05, 4.0)) * np.sqrt(self.outer_ms / 6.0)
-        ex, ey = gx / np.maximum(size, 1e-15), gy / np.maximum(size, 1e-15)
-        dx, dy = rotate(ex, ey, sign * self.angle_deg)
-        return speed * dx, speed * dy
-
-
-__all__ = ["BetaDrift", "DRIFT_MS", "GYRE_ANGLE_DEG", "outer_strength"]

naturev1/cyclone/bogus.py

@@ -1,78 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The storm a 1.5-degree analysis cannot hold, put back in the shape that matters for its motion.
-
-The idea: at 1.5 degrees a hurricane's core is a smudge, but its *motion* does not depend on the core -- it
-depends on the vortex's outer circulation (300-1000 km), which drives the beta gyres (Fiorino and Elsberry
-1989), and on how deep it is. So the bogus vortex is specified by its outer strength, not its maximum wind:
-
-* a modified-Rankine tangential profile ``V(r) = Vm (r / Rm)`` inside ``Rm`` and ``Vm (Rm / r)^alpha`` outside,
-  tapered to zero beyond ``R_taper`` (a vortex with unbounded circulation would interact with the whole
-  domain);
-* ``Vm`` chosen so the profile's mean tangential wind between 300 and 800 km equals the outer strength
-  measured from the analysis's own vortex (:func:`naturev1.cyclone.beta.outer_strength`), so the bogus has
-  exactly the outer circulation the reanalysis saw, with a core the model grid can resolve;
-* ``Rm`` widened from the best-track radius of maximum wind to at least two grid lengths;
-* the size taken from the best-track gale radius when it exists (larger storms decay more slowly outside).
-
-Returns winds and vorticity on any (x, y) km grid around the centre.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-#: Profile shape outside the radius of maximum wind, and the taper radius, km.
-ALPHA = 0.55
-TAPER_KM = 1400.0
-
-
-def rankine_profile(r_km: np.ndarray, vmax: float, rmax_km: float, alpha: float = ALPHA,
-                    taper_km: float = TAPER_KM) -> np.ndarray:
-    r = np.asarray(r_km, np.float64)
-    inner = vmax * r / rmax_km
-    outer = vmax * (rmax_km / np.maximum(r, 1e-6)) ** alpha
-    profile = np.where(r < rmax_km, inner, outer)
-    return profile * np.exp(-(r / taper_km) ** 4)
-
-
-def vmax_for_outer_strength(outer_ms: float, rmax_km: float, alpha: float = ALPHA,
-                            radii=(300.0, 400.0, 500.0, 600.0, 700.0, 800.0)) -> float:
-    """The peak wind that gives the profile a mean tangential wind of ``outer_ms`` over ``radii``."""
-    unit = rankine_profile(np.asarray(radii), 1.0, rmax_km, alpha).mean()
-    return float(outer_ms / max(unit, 1e-9))
-
-
-def alpha_for_size(r34_nmi: float) -> float:
-    """Outer decay exponent from the gale radius: big storms decay slowly (0.4), small ones fast (0.7)."""
-    if not np.isfinite(r34_nmi) or r34_nmi <= 0:
-        return ALPHA
-    return float(np.clip(0.75 - 0.0025 * r34_nmi, 0.4, 0.7))
-
-
-def bogus_winds(x_km: np.ndarray, y_km: np.ndarray, outer_ms: float, rmax_km: float = 150.0, alpha: float = ALPHA,
-                cyclonic_sign: float = 1.0) -> tuple[np.ndarray, np.ndarray]:
-    """(u, v) m/s of the bogus vortex centred at the origin; ``cyclonic_sign`` -1 in the southern hemisphere."""
-    r = np.hypot(x_km, y_km)
-    vm = vmax_for_outer_strength(outer_ms, rmax_km, alpha)
-    vt = cyclonic_sign * rankine_profile(r, vm, rmax_km, alpha)
-    with np.errstate(invalid="ignore", divide="ignore"):
-        u = np.where(r > 0, -vt * y_km / r, 0.0)
-        v = np.where(r > 0, vt * x_km / r, 0.0)
-    return u, v
-
-
-def bogus_vorticity(r_km: np.ndarray, outer_ms: float, rmax_km: float = 150.0, alpha: float = ALPHA,
-                    cyclonic_sign: float = 1.0) -> np.ndarray:
-    """Relative vorticity (s^-1) of the bogus vortex, ``(1/r) d(r V)/dr``, evaluated by central differences."""
-    r = np.asarray(r_km, np.float64)
-    vm = vmax_for_outer_strength(outer_ms, rmax_km, alpha)
-    h = 1.0
-    rv = lambda rr: rr * rankine_profile(rr, vm, rmax_km, alpha)
-    rr = np.maximum(r, 2 * h)
-    zeta = (rv(rr + h) - rv(rr - h)) / (2 * h) / rr / 1000.0
-    return cyclonic_sign * zeta
-
-
-__all__ = ["ALPHA", "TAPER_KM", "alpha_for_size", "bogus_vorticity", "bogus_winds", "rankine_profile",
-           "vmax_for_outer_strength"]

naturev1/cyclone/climatology.py

@@ -1,101 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The flow a storm will meet in three days is mostly the flow it would meet on an average year -- plus what is
-left of today's anomaly.
-
-The idea: a steering flow frozen at the initial time is the right answer at hour zero and an increasingly
-wrong one after: troughs move on, ridges rebuild, and by day five the analysis's particular pattern has lost
-most of its memory. What is *not* lost is the seasonal circulation -- the subtropical ridge in September is
-where it always is in September. So the flow is split into climatology plus anomaly, and the anomaly is
-**damped with lead time** (the persistence of steering anomalies is a few days; Neumann's CLIPER is the
-fully-damped limit, the frozen flow the undamped one):
-
-``V(x, t) = V_clim(x, doy) + exp(-t / tau) * (V_analysis(x) - V_clim(x, doy))``
-
-The climatology is ERA5 1981-2010 (WeatherBench 2's daily climatology, a 7-day window) -- years that do not
-overlap the 2016-2022 hindcast seasons, so the benchmark is not flattered by its own future. It is cached as a
-day-of-year stack of the winds the steering layers use, plus the 500 hPa height (for the ridge's anomaly) and
-the day-to-day standard deviation of the 500 hPa wind (the natural size of an analysis's flow uncertainty,
-used by the ensemble).
-"""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-import numpy as np
-
-from .fields import Environment
-
-STORE = ("gs://weatherbench2/datasets/era5-daily-climatology/"
-         "daily_clim_daily_mean_1981_to_2010_7_dw-240x121_equiangular_with_poles_conservative.zarr")
-LEVELS = (200, 250, 300, 400, 500, 600, 700, 850)
-CHANNELS = [f"u@{p}" for p in LEVELS] + [f"v@{p}" for p in LEVELS] + ["z@500", "ustd@500", "vstd@500"]
-
-
-def build_climatology(path: str | Path, log=print) -> Path:
-    """Read the day-of-year climatology into ``path`` (``(366, C, 121, 240)`` float16 + ``.json``); idempotent."""
-    import json
-
-    import xarray as xr
-
-    path = Path(path)
-    if path.exists() and path.with_suffix(".json").exists():
-        return path
-    ds = xr.open_zarr(STORE, storage_options={"token": "anon"}, chunks=None)
-    lat = ds.latitude.values
-    out = np.lib.format.open_memmap(path, mode="w+", dtype=np.float16, shape=(366, len(CHANNELS), 121, 240))
-    levels = list(ds.level.values.astype(int))
-    order = [levels.index(p) for p in LEVELS]
-
-    def oriented(array):
-        array = np.swapaxes(np.asarray(array, np.float32), -1, -2)
-        return array[..., ::-1, :] if lat[0] > lat[-1] else array
-
-    for name, slot, idx in (("u_component_of_wind_mean", 0, order), ("v_component_of_wind_mean", len(LEVELS), order)):
-        data = oriented(ds[name].values)                            # (366, L, lat, lon)
-        out[:, slot:slot + len(LEVELS)] = data[:, idx]
-        log(f"[climatology] {name}")
-    out[:, 2 * len(LEVELS)] = oriented(ds["geopotential_mean"].sel(level=500).values) / 100.0   # dam-scaled for fp16
-    out[:, 2 * len(LEVELS) + 1] = oriented(ds["u_component_of_wind_std"].sel(level=500).values)
-    out[:, 2 * len(LEVELS) + 2] = oriented(ds["v_component_of_wind_std"].sel(level=500).values)
-    out.flush()
-    path.with_suffix(".json").write_text(json.dumps({"channels": CHANNELS, "levels": list(LEVELS), "z_scale": 100.0}))
-    return path
-
-
-class Climatology:
-    """Day-of-year climatology, cut into the same boxes as the hindcast analyses."""
-
-    def __init__(self, path: str | Path) -> None:
-        self.data = np.load(path, mmap_mode="r")
-        self.lat = np.linspace(-90.0, 90.0, 121)
-        self.slot = {n: k for k, n in enumerate(CHANNELS)}
-
-    def environment(self, like: Environment, when: np.datetime64, shift_days: float = 0.0) -> Environment:
-        """An :class:`Environment` on ``like``'s box holding the climatological winds (and z500) for ``when``."""
-        day = int((np.datetime64(when, "D") - np.datetime64(str(when)[:4] + "-01-01", "D")).astype(int) + shift_days) % 366
-        rows = np.rint((like.lat - self.lat[0]) / 1.5).astype(int)
-        cols = np.rint((like.lon % 360.0) / 1.5).astype(int) % 240
-        block = self.data[day][:, rows][:, :, cols].astype(np.float64)
-        fields = {"u": np.stack([block[self.slot[f"u@{p}"]] for p in LEVELS]),
-                  "v": np.stack([block[self.slot[f"v@{p}"]] for p in LEVELS]),
-                  "z": np.repeat(block[self.slot["z@500"]][None] * 100.0, len(LEVELS), 0),
-                  "ustd500": block[self.slot["ustd@500"]], "vstd500": block[self.slot["vstd@500"]]}
-        return Environment(lat=like.lat, lon=like.lon, levels=LEVELS, fields=fields, time=like.time)
-
-
-class DampedAnomalyFlow:
-    """``V_clim + exp(-t / tau) (V_analysis - V_clim)`` from two steering flows (``velocity(lat, lon)`` objects)."""
-
-    def __init__(self, analysis_flow, climate_flow, tau_h: float = 72.0) -> None:
-        self.analysis, self.climate, self.tau_h = analysis_flow, climate_flow, tau_h
-
-    def __call__(self, lat, lon, hours):
-        ua, va = self.analysis.velocity(lat, lon)
-        uc, vc = self.climate.velocity(lat, lon)
-        memory = np.exp(-np.asarray(hours, np.float64) / max(self.tau_h, 1e-6))
-        return uc + memory * (ua - uc), vc + memory * (va - vc)
-
-
-__all__ = ["CHANNELS", "Climatology", "DampedAnomalyFlow", "LEVELS", "STORE", "build_climatology"]

naturev1/cyclone/cliper.py

@@ -1,137 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-CLIPER, rebuilt: climatology and persistence as a regression, per basin, in the poleward frame.
-
-The idea (Neumann 1972, still NHC's skill baseline as CLIPER5): where storms in this place, at this time of
-year, moving like this, went next -- from 35 years of best tracks, with no model fields at all. It beats pure
-extrapolation from about a day on because climatology knows storms recurve at the subtropical ridge and
-slow down near it; extrapolation knows only the last six hours.
-
-This version improves on the classic in three ways:
-
-* **Poleward frame**: southern-hemisphere storms are mirrored north-south, so the Southern Indian and South
-  Pacific basins share one model with twice the data, and every "poleward" coefficient means the same thing
-  in both hemispheres.
-* **Three motion windows** (the last 6 h, the 6 h before, the 12 h before that): curvature and acceleration
-  enter as differences of windows, which the regression weighs against climatology lead by lead.
-* **Displacements in an exact local frame** (azimuthal equidistant), not degree differences, so the
-  regression's target means the same at 10 and 40 degrees latitude.
-
-Coefficients are fitted once on 1980-2014 (no overlap with the 2016-2022 seasons the benchmark uses) by
-:mod:`naturev1.cyclone.fit` and stored as constants in :mod:`naturev1.cyclone.coefficients`.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .geometry import from_local, local_displacement_km, wrap_longitude
-
-#: Basin groups sharing one regression, and each group's reference longitude.
-GROUPS = {"NA": ("NA", -60.0), "EP": ("EP", -120.0), "WP": ("WP", 140.0), "NI": ("NI", 85.0),
-          "SI": ("SH", 80.0), "SP": ("SH", 170.0), "SA": ("SH", -30.0)}
-
-PREDICTORS = ("one", "lat", "lat2", "lon", "u6", "v6", "u12", "v12", "u24", "v24", "wind", "dwind", "season_s",
-              "season_c", "lat_u6", "lat_v6", "u6v6", "u6sq", "v6sq", "wind_v6", "lon_v6")
-
-
-def _motion(case, start: int, stop: int):
-    """(east, north) km/h between history offsets ``start`` and ``stop`` hours (negative), or None."""
-    from .data import HISTORY_HOURS
-
-    a, b = HISTORY_HOURS.index(start), HISTORY_HOURS.index(stop)
-    la, loa = case.history["lat"][a], case.history["lon"][a]
-    lb, lob = case.history["lat"][b], case.history["lon"][b]
-    if not (np.isfinite(la) and np.isfinite(lb)):
-        return None
-    east, north = local_displacement_km(la, loa, lb, lob)
-    hours = stop - start
-    return east / hours, north / hours
-
-
-def predictors(case) -> np.ndarray | None:
-    """The CLIPER predictor vector in the poleward frame, or None without a 6- or 12-hour history."""
-    sign = -1.0 if case.lat < 0 else 1.0
-    m6 = _motion(case, -6, 0) or (_motion(case, -12, 0))
-    if m6 is None:
-        return None
-    m12 = _motion(case, -12, -6) or m6
-    m24 = _motion(case, -24, -12) or m12
-    u6, v6 = m6[0], sign * m6[1]
-    u12, v12 = m12[0], sign * m12[1]
-    u24, v24 = m24[0], sign * m24[1]
-    _, reference = GROUPS.get(case.basin, ("NA", -60.0))
-    lat = abs(case.lat) / 30.0
-    lon = wrap_longitude(case.lon - reference) / 60.0
-    wind = (case.wind_kt if np.isfinite(case.wind_kt) else 50.0) / 100.0
-    before = case.history["wind"][-3]                                       # 12 hours ago
-    dwind = ((case.wind_kt - before) / 20.0) if np.isfinite(before) and np.isfinite(case.wind_kt) else 0.0
-    day = (np.datetime64(case.time, "D") - np.datetime64(str(case.time)[:4] + "-01-01", "D")).astype(int)
-    phase = 2 * np.pi * ((day + (182 if sign < 0 else 0)) % 365) / 365.0
-    s = 1.0 / 20.0                                                          # km/h -> order one
-    u6s, v6s = u6 * s, v6 * s
-    return np.array([1.0, lat, lat * lat, lon, u6s, v6s, u12 * s, v12 * s, u24 * s, v24 * s, wind, dwind,
-                     np.sin(phase), np.cos(phase), lat * u6s, lat * v6s, u6s * v6s, u6s * u6s, v6s * v6s,
-                     wind * v6s, lon * v6s])
-
-
-def group_of(case) -> str:
-    return GROUPS.get(case.basin, ("NA", 0.0))[0]
-
-
-def cliper_track(case, leads, table: dict | None = None) -> np.ndarray:
-    """``(L, 2)`` lat/lon from the stored coefficients (NaN where the leads or the group are not covered)."""
-    if table is None:
-        from .coefficients import CLIPER as table
-    out = np.full((len(leads), 2), np.nan)
-    x = predictors(case)
-    group = table.get(group_of(case))
-    if x is None or group is None:
-        return out
-    sign = -1.0 if case.lat < 0 else 1.0
-    stored_leads = list(table["leads"])
-    weights = np.asarray(group, np.float64)                                  # (L, 2, P)
-    for k, lead in enumerate(leads):
-        if lead not in stored_leads:
-            continue
-        east, north = weights[stored_leads.index(lead)] @ x
-        lat, lon = from_local(case.lat, case.lon, east, sign * north)
-        out[k] = lat, lon
-    return out
-
-
-def fit_cliper(cases, leads, ridge: float = 1e-2) -> dict:
-    """
-    Least squares (with a small ridge) of the poleward-frame displacement at each lead on :func:`predictors`,
-    one regression per basin group. Returns ``{"leads": [...], group: (L, 2, P) nested lists}``.
-    """
-    rows: dict[str, list] = {}
-    for case in cases:
-        x = predictors(case)
-        if x is None:
-            continue
-        sign = -1.0 if case.lat < 0 else 1.0
-        target = np.full((len(leads), 2), np.nan)
-        for k in range(len(leads)):
-            if case.truth["valid"][k]:
-                east, north = local_displacement_km(case.lat, case.lon, case.truth["lat"][k], case.truth["lon"][k])
-                target[k] = east, sign * north
-        rows.setdefault(group_of(case), []).append((x, target))
-    table = {"leads": [int(h) for h in leads]}
-    for group, items in rows.items():
-        x = np.stack([i[0] for i in items])
-        y = np.stack([i[1] for i in items])
-        weights = np.zeros((len(leads), 2, x.shape[1]))
-        for k in range(len(leads)):
-            ok = np.isfinite(y[:, k, 0])
-            if ok.sum() < 5 * x.shape[1]:
-                weights[k] = np.nan
-                continue
-            a = x[ok]
-            gram = a.T @ a + ridge * ok.sum() * np.diag([0.0] + [1.0] * (x.shape[1] - 1))
-            weights[k] = np.linalg.solve(gram, a.T @ y[ok, k]).T
-        table[group] = weights.round(5).tolist()
-    return table
-
-
-__all__ = ["GROUPS", "PREDICTORS", "cliper_track", "fit_cliper", "group_of", "predictors"]

naturev1/cyclone/coefficients.py

@@ -1,770 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Hard-coded constants of the tropical-cyclone physics, generated by :mod:`naturev1.cyclone.fit`.
-
-Do not edit by hand: regenerate with ``naturev1.cyclone.fit.write_coefficients``. Provenance of every table is in
-:data:`PROVENANCE`; nothing here was fitted on the 2018, 2020, 2021 or 2022 seasons the benchmark reports.
-"""
-
-nan = float("nan")
-
-LEADS = [6, 12, 24, 36, 48, 72, 96, 120]
-
-CLIPER = {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'SH': [[[-6.89849, 4.55311, 5.27073, -0.6131, 94.40557, -4.42295, 5.76681, 0.295, -4.2088, 4.68075, 2.09058, 0.46463,
-          -0.25732, 0.29081, 24.15884, 3.00957, 2.13546, 0.0907, 0.6306, 1.90969, 1.06164],
-         [9.86812, -4.73926, -5.52023, 1.11141, 11.44614, 67.94021, -3.64462, 3.85791, -3.30421, -0.58698, -0.86277,
-          0.91485, -1.66603, -1.45924, -3.81025, 31.49136, 1.69392, 0.08787, 2.88735, 21.22811, 0.23959]],
-        [[-18.41425, 12.81992, 15.52967, -1.4921, 187.19514, -14.70217, 9.04517, 3.66699, -11.08835, 9.79055, 5.20326,
-          1.52524, -0.11925, 1.92083, 44.74067, 10.55012, 4.61026, 0.72396, 3.46313, 8.45619, 2.70911],
-         [22.28041, -10.80969, -9.28192, 2.52104, 27.51898, 119.72323, -9.23941, 7.20763, -8.02007, -2.56349, 1.22476,
-          2.41026, -4.46188, -4.1664, -8.82557, 63.81331, 7.02853, 2.13998, 6.82641, 48.68957, 3.76544]],
-        [[-52.46231, 40.13144, 51.15546, -4.60957, 358.21768, -36.8936, 22.53576, 13.34013, -32.60534, 14.82684,
-          13.62215, 5.82275, 0.7088, 9.45188, 71.93162, 30.98404, 1.12105, 0.62557, 15.2583, 33.9271, 13.58604],
-         [53.42745, -24.2113, -15.56955, 7.35784, 66.32803, 193.75807, -17.32424, 17.5433, -19.69158, -17.2441,
-          14.30136, 5.64206, -14.15874, -11.95333, -26.34444, 120.17492, 17.01594, 10.47998, 16.16886, 115.50358,
-          13.83153]],
-        [[-94.35612, 73.38788, 90.83379, -10.24711, 500.88914, -61.71059, 31.29922, 14.84663, -51.72601, 22.80821,
-          26.80545, 12.14121, -0.36291, 19.78906, 106.14399, 55.52652, -17.08894, -3.14437, 34.58213, 70.99715,
-          20.24861],
-         [91.93743, -39.65755, -25.20118, 12.90685, 101.23193, 239.4925, -23.84764, 14.31463, -28.40863, -25.54232,
-          40.70569, 10.89734, -27.74962, -23.23559, -34.85518, 162.19301, 15.2109, 21.40256, 22.90112, 187.33009,
-          24.3049]],
-        [[-139.80538, 109.25377, 131.05002, -20.52933, 615.5265, -89.80457, 40.19393, 21.64613, -62.00295, 36.19187,
-          45.44497, 17.18632, -4.42606, 29.85471, 121.08593, 65.97433, -40.64935, -15.89213, 56.61788, 98.93821,
-          19.55115],
-         [141.33508, -65.07264, -46.0827, 18.5825, 129.44505, 253.8835, -27.39761, 23.58675, -36.63969, -30.4526,
-          78.74436, 17.08254, -46.20355, -39.26373, -38.95082, 177.20303, 0.6972, 26.41611, 25.01441, 245.48092,
-          29.40196]],
-        [[-228.75069, 166.68038, 190.23038, -53.49356, 748.18585, -111.63548, 51.69735, 24.31313, -37.98832, 40.61027,
-          85.72059, 37.67029, -13.2301, 44.13079, 129.046, 94.20008, -67.12184, -38.44348, 82.07731, 90.69575,
-          -9.86827],
-         [271.87026, -158.54519, -140.65643, 26.95161, 135.4888, 268.79865, -27.57028, 28.76617, -47.75765, -41.24527,
-          158.18148, 48.38695, -98.02939, -81.48959, -7.2034, 170.93914, -12.54187, 24.45127, 36.33418, 277.34997,
-          36.88958]],
-        [[-311.91764, 217.3, 242.4542, -99.0233, 804.36005, -160.92961, 54.02222, 8.24152, -18.95993, 44.45592,
-          94.54263, 69.5194, -14.26466, 65.18202, 187.74659, 101.84084, -77.68017, -51.41698, 124.25634, 60.72763,
-          -63.30426],
-         [432.47081, -280.35791, -260.64893, 31.11299, 124.67457, 267.04998, -37.55164, 21.34623, -66.13774,
-          -61.25982, 192.55883, 85.81275, -147.05231, -125.48425, 49.87659, 124.45063, -44.3798, 26.85232, 33.17025,
-          246.04304, 2.22019]],
-        [[-395.8374, 222.13794, 276.2057, -171.77674, 801.86338, -176.19246, 59.64088, 16.02142, 26.4853, 38.237,
-          89.26081, 72.6628, -11.63199, 81.12329, 245.69749, 85.97211, -102.31933, -51.39082, 128.7768, -3.17239,
-          -120.85532],
-         [609.71396, -427.99459, -403.71133, 20.82984, 77.72191, 253.14287, -37.77152, 23.97872, -55.89085, -81.56886,
-          181.08041, 122.80727, -188.94111, -173.77959, 88.6667, 26.22527, -109.42297, 36.82808, -7.22977, 185.34796,
-          -37.09241]]],
- 'WP': [[[-16.20677, 15.63998, 10.06914, -3.74299, 93.75863, -5.40601, 8.19762, 5.1524, -8.56842, 6.9766, -2.31176,
-          -1.71704, 3.18447, 3.66333, 21.32686, -0.95038, 5.77288, -1.55543, -3.04609, 9.97277, -5.07394],
-         [13.50039, -1.81948, -6.73653, 5.45262, 12.99839, 69.60777, -8.73442, 7.36191, -5.79528, -4.65655, -3.29464,
-          0.42635, -1.17755, -3.87253, 5.35639, 28.44964, -0.02443, -0.6877, -0.56882, 21.28817, -2.37855]],
-        [[-43.33451, 39.26894, 30.74485, -12.23165, 184.65042, -18.97883, 14.70594, 15.94676, -22.16473, 17.49647,
-          -7.21557, -4.54139, 9.90573, 11.14076, 43.7145, 2.17248, 13.02577, -1.36712, -5.6229, 30.98623, -9.81739],
-         [30.54725, -4.91513, -10.12713, 13.96885, 28.0555, 124.03229, -20.27628, 14.36824, -13.64905, -11.69131,
-          -5.1331, 1.01649, -2.77651, -9.94192, 14.08919, 61.94014, 4.76309, -0.21385, 0.21013, 49.42618, -4.14531]],
-        [[-128.40854, 105.06989, 98.52555, -42.83307, 347.43636, -57.58312, 22.01075, 34.27455, -55.26274, 46.96565,
-          -17.68337, -13.07826, 31.88054, 34.41883, 92.24259, 28.43562, 34.34689, 1.15779, 4.09304, 95.40397,
-          -22.14084],
-         [72.46964, -10.07829, -9.80993, 36.48727, 57.5315, 192.58188, -43.93762, 22.39047, -27.52741, -21.33891,
-          -0.97934, 2.30881, -5.72227, -26.32042, 37.01298, 131.14381, 20.2822, 5.6267, 12.1905, 120.17773,
-          -7.2647]],
-        [[-246.22865, 192.82272, 190.36649, -94.7955, 481.98355, -94.53456, 24.68945, 52.83694, -84.01519, 68.41848,
-          -24.3452, -23.35148, 63.58966, 64.59874, 123.74873, 71.06015, 52.32938, 1.78221, 22.653, 188.57723,
-          -43.03743],
-         [125.15148, -12.39789, -6.66224, 67.34554, 77.14063, 225.02866, -57.74292, 29.03936, -40.45363, -35.74492,
-          17.71042, 3.3196, -7.31209, -48.42763, 59.27303, 193.01925, 29.30954, 10.76265, 30.22705, 193.2349,
-          -23.00858]],
-        [[-378.0917, 296.36841, 287.33006, -170.44207, 594.94495, -104.02902, 13.86768, 64.71427, -87.95867, 74.47373,
-          -21.74208, -32.72182, 101.69244, 91.20896, 112.25741, 109.15678, 52.52173, -5.88387, 22.23961, 286.06762,
-          -65.45707],
-         [198.08326, -16.94066, -20.40089, 105.97841, 98.78439, 250.97908, -69.98445, 22.31221, -41.24996, -46.28173,
-          49.59685, 5.57246, -9.78638, -80.81538, 61.09144, 221.52819, 11.05386, 12.50686, 28.91994, 253.61661,
-          -41.74733]],
-        [[-653.59538, 506.70533, 419.20707, -370.4655, 730.69148, -78.22394, 17.6356, 56.58439, -68.66478, 84.54675,
-          25.0756, -24.89897, 171.35518, 107.47726, 28.82199, 138.79654, 19.88845, -30.49115, 15.25375, 405.77192,
-          -70.72863],
-         [379.12461, -61.82457, -125.34344, 185.66916, 96.34344, 268.93865, -76.29996, 7.4685, -28.81106, -39.44926,
-          133.74491, 31.26702, -26.61039, -179.85099, 62.614, 182.42887, -43.63986, 0.94889, 33.52414, 304.65999,
-          -39.47807]],
-        [[-897.67447, 670.04154, 480.55428, -601.62708, 801.01675, -11.31436, 30.84273, 50.90279, -25.13451, 78.57773,
-          69.23942, -14.80544, 200.28509, 74.18916, -85.18752, 128.03856, 26.93606, -26.69193, -18.08332, 432.09076,
-          -84.24039],
-         [604.07426, -179.57362, -306.29838, 275.8111, 71.16481, 273.13995, -63.82291, 15.87954, -27.59178, -49.02211,
-          195.00731, 79.65092, -62.25121, -309.14757, 79.73423, 84.02348, -86.25105, -6.95591, 36.97797, 276.84592,
-          -7.45035]],
-        [[-1117.40609, 770.74186, 506.26311, -839.01551, 862.67992, 2.35721, 30.69398, 61.28793, -36.92812, 50.84527,
-          118.99847, -34.31243, 180.78113, -0.10516, -143.39981, 95.68428, -17.60192, -30.87194, -26.08792, 433.79439,
-          -147.2518],
-         [851.06251, -366.06152, -511.15683, 374.00238, 66.7686, 273.08502, -40.82897, 28.79323, -64.79473, -59.64446,
-          220.17852, 92.48093, -117.03989, -451.59675, 120.11612, -29.31688, -77.35583, 8.34809, 45.64576, 220.87016,
-          42.26594]]],
- 'EP': [[[-14.10155, 10.7506, 10.93923, 4.04594, 78.00045, -2.38971, 14.87339, 0.08937, -5.30831, 6.78377, -0.43682,
-          -0.3926, 1.61448, 5.22697, 28.24363, 1.17719, 6.41496, -3.87028, 1.42438, 2.76606, -6.42886],
-         [8.8687, -3.0245, -1.53857, 1.08307, 4.30622, 57.6545, 0.22957, 11.5313, -5.49554, -6.03769, -1.49113,
-          2.31404, -1.04613, -0.51434, 6.25738, 30.01525, -6.10255, -0.23447, 8.80973, 19.96839, -1.91677]],
-        [[-34.85265, 25.45339, 27.88811, 11.00401, 155.88499, -8.79767, 24.69022, 3.9085, -14.0247, 16.85116, -2.0146,
-          -0.25681, 4.11728, 14.51727, 59.23789, 6.299, 13.29241, -6.41778, 2.42611, 7.0105, -20.35959],
-         [19.11693, -6.31076, -0.1908, 2.74093, 11.93734, 109.40368, -3.46368, 15.65958, -12.59234, -14.66074,
-          -1.95992, 6.48166, -3.16552, -1.53529, 16.91493, 61.58156, -7.69779, 0.83476, 17.65171, 44.72503,
-          -5.11928]],
-        [[-94.07023, 66.06869, 73.65271, 31.10041, 300.51449, -20.21636, 46.21104, 12.87457, -42.92967, 35.59433,
-          -10.36306, 0.41671, 11.24113, 44.12991, 116.71825, 27.24361, 27.27627, -8.16348, 14.73383, 19.87556,
-          -65.7655],
-         [45.34318, -14.86517, 4.49271, 5.88653, 26.30837, 185.53952, -13.92399, 21.48984, -25.4368, -33.46387,
-          -0.73858, 17.88958, -10.91001, -4.84443, 42.16668, 117.78172, -0.55086, 6.5768, 41.99272, 92.51631,
-          -18.77148]],
-        [[-172.78613, 113.91341, 122.06318, 51.65896, 440.8733, -34.47618, 60.24896, 19.85061, -80.00821, 53.35082,
-          -23.25532, -0.10875, 16.93984, 84.41628, 149.62937, 46.68605, 8.47969, -11.06512, 29.00573, 36.81206,
-          -115.24421],
-         [84.42589, -30.80777, -2.64203, 4.62837, 28.4251, 233.43171, -24.01027, 23.43787, -33.42158, -52.08475,
-          2.88012, 28.76511, -21.99061, -8.60319, 53.01886, 149.51026, -7.61571, 3.99682, 60.80214, 128.1721,
-          -38.61486]],
-        [[-267.69028, 165.66531, 169.99404, 75.41722, 546.79914, -45.53888, 70.58117, 16.35894, -96.30306, 66.90357,
-          -36.24983, 2.29243, 19.93098, 130.2162, 158.66875, 65.0486, -54.24025, -18.70754, 15.90572, 53.32363,
-          -168.36153],
-         [139.40898, -57.62791, -27.561, 0.24818, 17.72865, 253.69821, -24.28178, 13.21468, -33.02873, -60.72511,
-          8.39666, 38.89736, -37.06063, -14.5925, 42.94765, 161.36429, -43.33423, -2.58853, 60.56868, 146.59029,
-          -62.70576]],
-        [[-511.1468, 251.50406, 243.42129, 109.49582, 632.4447, -59.47003, 77.36327, 16.60987, -60.91765, 49.01528,
-          -61.92422, 10.56417, 2.36614, 201.39689, 126.61161, 74.4434, -141.53288, -54.37215, 43.72297, 82.33669,
-          -217.59884],
-         [254.75358, -129.58295, -108.71395, -24.3251, 0.21155, 231.55942, -18.52024, 8.75631, -35.37236, -60.83596,
-          25.7126, 60.84015, -72.79191, -47.39666, 25.2762, 144.87154, -117.12103, -3.83355, 88.41045, 127.32908,
-          -98.96257]],
-        [[-766.90219, 307.83642, 303.60288, 140.14602, 679.08811, -97.8231, 102.63709, -30.21819, 3.64232, 47.42414,
-          -89.66976, -3.45734, -61.30598, 238.50877, 103.50796, 41.9625, -238.54794, -65.4156, 35.87017, 114.32341,
-          -310.17189],
-         [362.67025, -215.41649, -207.36841, -56.91425, -31.81393, 217.62739, -18.65506, 3.30264, -63.08998,
-          -41.12408, 25.73649, 72.91571, -113.83786, -92.33626, 67.69776, 101.02156, -111.44527, -0.27672, 127.04858,
-          126.36957, -149.8012]],
-        [[-1057.72533, 371.27592, 410.23032, 147.57668, 743.81289, -185.15576, 136.97215, -59.87554, 33.41684,
-          45.71323, -115.78355, -15.10783, -174.7672, 237.93246, 210.94902, 2.78143, -374.73489, -55.6333, -52.73704,
-          148.00718, -406.68044],
-         [446.57062, -320.73884, -318.99586, -108.73124, -84.30502, 185.2249, -44.19411, 10.44054, -85.61826,
-          -62.82437, 33.34707, 40.12021, -165.32924, -156.53856, 155.54921, 60.78069, -140.97183, 1.80045, 186.71327,
-          126.64964, -162.31242]]],
- 'NA': [[[-19.7397, 14.92792, 8.28093, -6.12276, 90.9361, -1.7382, 11.56228, 3.23465, -10.1254, 7.94461, -0.66331,
-          0.0269, 0.31266, 6.53544, 20.3387, -0.52592, 0.89, -1.70758, 1.14218, -1.98799, -7.52874],
-         [14.64359, 0.50116, -8.20719, 0.74821, 17.7035, 61.28995, -5.42721, 5.10377, -9.03081, -5.79328, -4.96155,
-          0.5542, -2.72867, -2.45076, -1.21414, 31.93361, -2.3194, -0.02424, 3.60817, 21.16033, 2.50119]],
-        [[-50.6297, 34.55303, 27.92063, -15.4313, 181.45277, -7.74589, 19.8419, 10.42758, -28.4207, 19.14275,
-          -4.60102, -0.53944, 1.24463, 18.28998, 40.80277, 7.10197, 3.99405, -3.59454, 3.19958, -4.19619, -17.55586],
-         [31.05824, 2.10531, -14.1071, 1.16249, 43.34005, 108.99681, -13.93417, 10.98735, -22.16962, -18.00755,
-          -9.79642, 1.28715, -7.9456, -6.02374, -3.05803, 65.41266, -3.77653, 1.70732, 9.23992, 50.73953, 7.28982]],
-        [[-141.54223, 82.34601, 99.11153, -43.18294, 355.73482, -30.64933, 20.3621, 27.3561, -66.58324, 45.54927,
-          -20.02348, -3.79037, 1.71088, 52.15413, 74.26414, 55.20514, -4.93865, -10.70825, 20.52591, -8.93112,
-          -42.67116],
-         [70.50493, 10.87541, -26.0053, 6.11513, 109.93085, 188.15395, -44.24787, 14.44529, -44.81098, -51.60302,
-          -14.11999, 1.83004, -26.62172, -20.05412, -12.042, 118.01404, -6.71696, 6.76635, 28.44459, 120.52326,
-          4.80817]],
-        [[-261.22824, 144.74105, 195.13376, -89.60911, 506.87602, -49.60913, 20.79732, 57.23271, -101.71518, 58.35085,
-          -41.8696, -11.59963, -2.01073, 91.61068, 81.03763, 117.59619, -19.69545, -19.93342, 38.91485, 3.57093,
-          -57.02817],
-         [127.68728, 25.59671, -54.75308, 11.42159, 181.857, 235.77496, -58.82489, 16.5011, -63.00386, -78.39415,
-          -5.31764, -2.17082, -58.70125, -47.88312, -42.95628, 138.78454, -36.24036, 10.73129, 50.47223, 181.90725,
-          -13.22026]],
-        [[-405.4043, 220.17132, 301.43824, -160.0718, 646.66092, -53.72306, -8.07799, 57.50692, -112.66158, 78.84926,
-          -68.15473, -13.57639, -14.1496, 128.01225, 54.61582, 165.59779, -46.14126, -32.95471, 69.67783, 39.97092,
-          -57.21088],
-         [201.10028, 41.99469, -109.22198, 5.21129, 241.27225, 263.3353, -77.89816, 1.69393, -56.37484, -80.2929,
-          14.18586, -11.04127, -96.07297, -88.91099, -96.2007, 127.82502, -73.57562, 11.32393, 71.57404, 233.97845,
-          -17.9474]],
-        [[-691.64733, 388.95659, 469.78782, -357.82076, 805.17452, -66.59878, -7.87234, 68.01242, -89.21878, 70.82546,
-          -150.75366, 8.37021, -79.94989, 184.81859, -67.61334, 226.54426, -160.80337, -65.33925, 74.40014, 209.37993,
-          -13.01405],
-         [390.47994, 58.83516, -267.46859, -30.9205, 278.28722, 269.38136, -70.93147, -4.13945, -30.27543, -64.69202,
-          63.47772, -11.6303, -167.51813, -186.7325, -202.32758, -4.02372, -158.63774, -0.66526, 75.93318, 372.17822,
-          56.56196]],
-        [[-953.05098, 537.87041, 551.8665, -607.87374, 897.83015, -46.18598, 0.78403, 75.73439, -65.2684, 42.84475,
-          -198.20381, -1.75547, -185.01742, 195.66753, -154.03784, 155.2259, -260.22738, -98.46607, 127.25818,
-          365.5767, 19.55962],
-         [613.95029, 20.63313, -444.47182, -41.88751, 266.62887, 270.36036, -36.25045, 25.08128, -71.77993, -64.45922,
-          122.61241, -10.47869, -214.9661, -286.61729, -197.92851, -178.52325, -198.56748, -15.7277, 94.45912,
-          454.05165, 105.29334]],
-        [[-1095.29946, 647.61768, 558.5217, -793.06032, 1048.80267, 76.3199, 40.63491, 93.74903, -64.07158, 15.05188,
-          -159.80678, -13.94131, -189.713, 185.20489, -390.37736, 14.58833, -323.5125, -127.31392, 126.68583,
-          452.64929, -15.98189],
-         [810.0692, -51.11922, -580.16376, 8.15322, 271.43572, 371.27445, -33.00497, 54.81563, -133.06933, -71.30383,
-          200.96844, -13.13643, -217.75833, -387.55524, -241.95566, -303.27907, -161.43052, -26.82786, 69.937,
-          388.13546, 25.6288]]]}
-
-SHIFOR = {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'SH': [[1.76007, -0.90077, 2.32674, 0.42115, -1.30162, -0.02532, -0.53499, -0.54332, -0.26904, -0.08504, -1.66244,
-         -3.06006],
-        [4.09508, -1.48605, 4.02743, 0.75198, -3.1553, -0.05986, -1.22806, -1.22248, -0.66239, -0.35764, -4.76723,
-         -6.49058],
-        [9.88996, -2.86549, 6.0916, 1.12335, -8.15216, -0.10467, -2.89685, -2.9604, -1.79756, -1.03137, -12.88379,
-         -13.37389],
-        [16.45586, -5.73433, 6.36939, 1.50715, -13.59456, 0.12029, -4.60118, -4.73173, -2.92609, -1.78443, -20.86682,
-         -18.98281],
-        [23.24285, -10.60723, 5.67503, 1.81966, -18.49634, 0.5858, -6.13469, -6.21274, -3.91867, -2.7779, -26.74283,
-         -23.32109],
-        [34.91492, -22.64959, 4.5837, 1.32516, -26.19189, 1.84623, -8.40239, -8.46128, -5.10437, -4.86784, -32.69072,
-         -28.44295],
-        [42.14955, -33.17887, 2.43926, 0.92393, -30.23285, 2.72906, -9.69778, -9.66652, -4.84368, -6.44235, -34.56102,
-         -29.74156],
-        [44.99802, -40.83523, 1.28041, 0.34374, -30.45204, 2.68992, -9.96993, -9.58373, -3.93063, -6.77259, -34.69276,
-         -28.11705]],
- 'WP': [[2.21411, 0.40398, 2.56884, 0.26312, -1.54928, 2.22279, -0.70958, -0.57175, -0.14949, -0.18877, -1.68926,
-         -2.94357],
-        [5.28234, 1.29639, 4.27834, 0.55566, -3.88038, 5.15965, -1.6828, -1.30171, -0.33372, -0.56369, -4.63631,
-         -6.31083],
-        [13.16827, 2.92199, 6.04146, 0.92332, -9.89103, 11.35858, -4.24041, -3.11133, -0.81991, -1.53392, -11.8276,
-         -13.84501],
-        [22.07979, 3.05388, 5.70915, 1.51251, -16.08309, 16.82707, -6.96511, -4.81219, -1.23466, -2.32386, -19.00725,
-         -20.91063],
-        [31.07652, 0.31897, 4.6837, 2.09066, -21.55483, 21.47013, -9.36483, -6.22239, -1.49956, -3.18045, -24.33408,
-         -26.13634],
-        [47.22438, -11.00067, 3.1879, 2.545, -29.61875, 29.83476, -12.3836, -7.85842, -1.37074, -4.7943, -29.85482,
-         -31.94801],
-        [58.71765, -23.92176, 2.14552, 1.99125, -34.21927, 37.13748, -13.7553, -8.50005, -0.44011, -5.64727,
-         -31.58945, -33.21763],
-        [63.93141, -34.14055, 1.06048, 1.64987, -34.66421, 41.22994, -13.47819, -8.15688, 1.13342, -4.77211,
-         -32.27454, -32.12786]],
- 'EP': [[2.19012, -0.84295, 2.94455, 0.17367, -2.54225, 0.00364, -0.64069, -0.1806, -0.45782, -0.10985, -1.49099,
-         -2.57433],
-        [5.29755, -1.97529, 5.05806, 0.33555, -6.02778, -0.04648, -1.54176, -0.36721, -1.0904, -0.39132, -3.86724,
-         -5.79627],
-        [13.93435, -5.80117, 7.53045, 0.51995, -14.68916, -0.18744, -3.49323, -0.54622, -2.30369, -1.36716, -9.21523,
-         -12.93402],
-        [23.93544, -11.61159, 8.06456, 0.76308, -23.57601, -0.69842, -5.42339, -0.76196, -3.03569, -2.8418, -14.03622,
-         -19.64002],
-        [33.28129, -18.11303, 8.0925, 0.54536, -31.07787, -1.61092, -7.08132, -1.22438, -3.32052, -4.04584, -17.83046,
-         -25.19716],
-        [46.54852, -29.01323, 5.57758, 0.45074, -39.30633, -4.34583, -9.2534, -1.5847, -1.76018, -5.13272, -22.60284,
-         -31.59354],
-        [51.18926, -36.09798, 4.20598, -0.00089, -40.42125, -7.74327, -10.69798, -1.68099, 0.193, -6.00398, -24.50991,
-         -32.24391],
-        [50.93793, -40.61493, 2.35584, 0.0867, -36.75436, -10.96966, -11.95292, -1.7968, 1.3075, -8.54996, -25.6835,
-         -31.53106]],
- 'NA': [[1.51128, 0.0948, 3.22709, -0.5008, -0.44459, 0.7917, -0.55248, -0.14997, -0.07728, -0.12045, -1.78307,
-         -2.21302],
-        [3.67149, 0.20315, 4.57082, -0.66572, -0.99601, 1.82278, -1.37483, -0.3758, -0.23001, -0.34222, -4.58774,
-         -5.10333],
-        [8.38714, -0.42911, 4.36906, -0.16208, -1.87212, 3.27129, -3.58989, -0.67827, -0.72355, -0.80377, -10.13454,
-         -11.36066],
-        [12.72618, -3.2875, 3.72623, 0.52978, -2.02156, 4.4073, -5.8223, -0.88602, -1.38303, -1.27749, -13.64035,
-         -17.11837],
-        [16.80352, -6.61127, 3.28779, 1.0925, -2.24077, 5.2732, -7.6675, -1.11268, -2.20605, -2.14458, -16.77665,
-         -21.44993],
-        [22.51545, -11.81332, 4.02639, 0.36408, -1.90706, 7.71557, -9.40935, -1.46537, -4.28497, -3.27487, -21.93892,
-         -26.98143],
-        [26.73661, -15.35052, 3.15588, -0.38738, -2.23523, 11.21103, -9.78587, -2.16465, -5.16989, -2.50045,
-         -26.24888, -29.62563],
-        [31.90237, -21.86714, 1.05514, 0.23431, -4.87391, 15.09835, -9.48598, -4.24274, -5.24929, -2.8807, -26.30648,
-         -30.69178]]}
-
-CONSENSUS = {'members': ['xtrp6', 'cliper', 'analog', 'budget_mix', 'evo12', 'med_anom48', 'int_anom48', 'budget_anom96',
-             'evo_anom48', 'evo_anom96', 'ens48_mean', 'baro_res12', 'baro'],
- 'reference': 1,
- 'along': [[0.00021, 0.01934, 0.15259, 0.11654, 0.0057, 0.00019, 0.00028, 0.08891, 0.21448, 0.2435, 0.07794, 0.07163,
-            0.0227],
-           [0.0226, 0.0749, 0.0, 0.13872, 0.16053, 0.0, 0.1026, 0.0, 0.0, 0.34861, 0.0, 0.05783, 0.11964],
-           [0.04657, 0.06086, 0.0, 0.04709, 0.13328, 0.0, 0.12294, 0.0, 0.0, 0.2309, 0.0, 0.16366, 0.24898],
-           [0.0, 0.16694, 0.0, 0.00963, 0.1108, 0.0, 0.05164, 0.0, 0.0, 0.25396, 0.0, 0.18252, 0.26465],
-           [0.0, 0.22451, 0.0, 0.0, 0.03734, 0.0, 0.0, 0.0, 0.0, 0.34537, 0.00701, 0.10732, 0.29571],
-           [0.0, 0.28684, 0.0, 0.0, 0.12786, 0.0, 0.0, 0.0, 0.22918, 0.0, 0.042, 0.0, 0.2981],
-           [0.0, 0.37101, 0.0, 0.0, 0.09724, 0.0, 0.08262, 0.0, 0.16738, 0.0, 0.03124, 0.0, 0.21771],
-           [0.0, 0.52248, 0.0, 0.0, 0.01603, 0.0, 0.15546, 0.0, 0.13808, 0.02426, 0.0182, 0.0, 0.10473]],
- 'cross': [[0.0, 0.0, 0.33787, 0.00179, 0.1248, 0.0, 0.0, 0.1246, 0.13298, 0.26711, 0.0, 0.0, 0.01085],
-           [0.0, 0.0, 0.26022, 0.0744, 0.0, 0.0, 0.0, 0.0, 0.09196, 0.52375, 0.0, 0.0, 0.04968],
-           [0.0, 0.0, 0.16694, 0.0327, 0.0, 0.0, 0.0, 0.0, 0.14503, 0.43359, 0.0, 0.06027, 0.16148],
-           [0.0, 0.0119, 0.13084, 0.0, 0.0, 0.0, 0.0, 0.0, 0.10335, 0.43103, 0.01842, 0.11755, 0.1869],
-           [0.0, 0.08731, 0.12105, 0.0, 0.0, 0.0, 0.0, 0.0, 0.07608, 0.39105, 0.0, 0.04151, 0.28301],
-           [0.0, 0.2554, 0.07573, 0.0, 0.0063, 0.0, 0.0, 0.0, 0.0, 0.42361, 0.0, 0.0, 0.23895],
-           [0.0, 0.4164, 0.09732, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.3536, 0.0, 0.0, 0.13268],
-           [0.0, 0.63458, 0.03286, 0.0, 0.0, 0.0, 0.0125, 0.0, 0.00596, 0.21784, 0.0, 0.0, 0.09626]],
- 'leads': [6, 12, 24, 36, 48, 72, 96, 120]}
-
-CONSENSUS_BASIC = {'members': ['xtrp6', 'cliper', 'budget_mix', 'evo12', 'baro_res12', 'baro'],
- 'reference': 1,
- 'along': [[0.0, 0.0, 0.35055, 0.59572, 0.0, 0.05108], [0.0, 0.09401, 0.08682, 0.56344, 0.1178, 0.16503],
-           [0.00737, 0.14174, 0.17161, 0.29753, 0.17979, 0.24077], [0.0, 0.21182, 0.0681, 0.27717, 0.18486, 0.28244],
-           [0.0, 0.30195, 0.00589, 0.26211, 0.08425, 0.34754], [0.0, 0.43549, 0.0, 0.20768, 0.0, 0.3227],
-           [0.0, 0.58243, 0.0, 0.14713, 0.0, 0.23043], [0.0, 0.78737, 0.05386, 0.03008, 0.0, 0.10951]],
- 'cross': [[0.0, 0.07939, 0.40468, 0.49114, 0.0, 0.02479], [0.0, 0.09729, 0.43163, 0.36452, 0.03493, 0.07163],
-           [0.0, 0.13878, 0.20812, 0.35892, 0.14325, 0.15094], [0.02741, 0.20422, 0.07016, 0.32484, 0.19683, 0.17653],
-           [0.01206, 0.30444, 0.01223, 0.28652, 0.14923, 0.23552], [0.0, 0.48332, 0.0, 0.23687, 0.0, 0.27981],
-           [0.0, 0.69491, 0.00613, 0.14618, 0.0, 0.15278], [0.0, 0.82058, 0.03974, 0.03784, 0.0, 0.10184]],
- 'leads': [6, 12, 24, 36, 48, 72, 96, 120]}
-
-ANALOGS = {'neighbours': 100, 'bandwidth': 1.5, 'years': [1980, 2014]}
-
-GENESIS = {'features': ['one', 'vort850', 'vort600', 'dvort24', 'okubo_weiss', 'rh600', 'shear', 'sst', 'depth', 'warm_core',
-              'gpi', 'age', 'lat', 'pouch'],
- 'pairs': [['vort850', 'vort600'], ['vort850', 'dvort24'], ['vort850', 'okubo_weiss'], ['vort850', 'rh600'],
-           ['vort850', 'shear'], ['vort850', 'sst'], ['vort850', 'depth'], ['vort850', 'warm_core'],
-           ['vort850', 'gpi'], ['vort850', 'age'], ['vort850', 'lat'], ['vort850', 'pouch'], ['vort600', 'dvort24'],
-           ['vort600', 'okubo_weiss'], ['vort600', 'rh600'], ['vort600', 'shear'], ['vort600', 'sst'],
-           ['vort600', 'depth'], ['vort600', 'warm_core'], ['vort600', 'gpi'], ['vort600', 'age'], ['vort600', 'lat'],
-           ['vort600', 'pouch'], ['dvort24', 'okubo_weiss'], ['dvort24', 'rh600'], ['dvort24', 'shear'],
-           ['dvort24', 'sst'], ['dvort24', 'depth'], ['dvort24', 'warm_core'], ['dvort24', 'gpi'], ['dvort24', 'age'],
-           ['dvort24', 'lat'], ['dvort24', 'pouch'], ['okubo_weiss', 'rh600'], ['okubo_weiss', 'shear'],
-           ['okubo_weiss', 'sst'], ['okubo_weiss', 'depth'], ['okubo_weiss', 'warm_core'], ['okubo_weiss', 'gpi'],
-           ['okubo_weiss', 'age'], ['okubo_weiss', 'lat'], ['okubo_weiss', 'pouch'], ['rh600', 'shear'],
-           ['rh600', 'sst'], ['rh600', 'depth'], ['rh600', 'warm_core'], ['rh600', 'gpi'], ['rh600', 'age'],
-           ['rh600', 'lat'], ['rh600', 'pouch'], ['shear', 'sst'], ['shear', 'depth'], ['shear', 'warm_core'],
-           ['shear', 'gpi'], ['shear', 'age'], ['shear', 'lat'], ['shear', 'pouch'], ['sst', 'depth'],
-           ['sst', 'warm_core'], ['sst', 'gpi'], ['sst', 'age'], ['sst', 'lat'], ['sst', 'pouch'],
-           ['depth', 'warm_core'], ['depth', 'gpi'], ['depth', 'age'], ['depth', 'lat'], ['depth', 'pouch'],
-           ['warm_core', 'gpi'], ['warm_core', 'age'], ['warm_core', 'lat'], ['warm_core', 'pouch'], ['gpi', 'age'],
-           ['gpi', 'lat'], ['gpi', 'pouch'], ['age', 'lat'], ['age', 'pouch'], ['lat', 'pouch'],
-           ['vort850', 'vort850'], ['vort600', 'vort600'], ['dvort24', 'dvort24'], ['okubo_weiss', 'okubo_weiss'],
-           ['rh600', 'rh600'], ['shear', 'shear'], ['sst', 'sst'], ['depth', 'depth'], ['warm_core', 'warm_core'],
-           ['gpi', 'gpi'], ['age', 'age'], ['lat', 'lat'], ['pouch', 'pouch']],
- 'weights': [-7.58249, 0.19861, 0.32566, 0.04204, 0.04884, 0.4964, -0.10314, 0.24073, 0.26262, 0.17275, 0.41731,
-             0.11061, 1.08455, 0.32539, -0.00679, 0.02776, -0.00082, 0.06403, -0.09248, -0.0746, 0.00054, -0.02602,
-             -0.02172, -0.11481, 0.14349, 0.13787, -0.00896, -0.00037, 0.24426, -0.01709, 0.07373, -0.00423, -0.00845,
-             0.0115, -0.06458, 0.13616, -0.08795, 0.00119, -0.3756, 0.0412, -0.0191, 0.01328, 0.12894, 0.06904,
-             0.28895, 0.07189, -0.14992, 0.01504, -0.01308, -0.01191, -0.00238, -0.02039, 0.0068, -0.01226, -0.00065,
-             0.03225, -0.49127, -0.18598, -0.19156, 0.92325, 0.25688, 1.17138, 0.33377, -0.15139, 0.01379, 0.0093,
-             -0.12922, 0.02151, 0.05668, 0.04417, -0.10183, -0.02042, 0.01805, -0.06257, -0.00841, 0.96345, -0.05078,
-             0.0141, -0.2137, -0.04163, -0.02136, 0.1558, 0.48613, -0.31486, -0.1906, 0.49737, 0.17046, 0.13345,
-             0.02198, 0.17818, 0.57605, -0.55852, -0.01018, -0.02851, -0.00499, -0.00012, 1.12441, -0.14708, -0.6432,
-             -0.01274, -0.11505, -0.04481, 0.25813, -0.86029, -0.49477],
- 'l2': 0.001,
- 'window_h': 48,
- 'radius_km': 300}
-
-CONE_KM = {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'radius_km': [30.1, 62.7, 139.7, 228.5, 331.4, 553.2, 761.9, 967.9],
- 'coverage_target': 0.67,
- 'held_out_coverage': [0.621, 0.638, 0.647, 0.65, 0.644, 0.633, 0.602, 0.618]}
-
-SHIPS = {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'weights': [[-1.31313, -1.66457, 2.7483, 2.08196, -0.45915, 0.03452, -0.64158, 1.14775, 0.04853, -1.89071, -1.80528,
-              0.84571, -0.35999, 0.4748, 0.44672, -0.24416],
-             [-3.57171, -3.6942, 3.90705, 4.99396, -1.05255, -0.27807, -0.91958, 2.48292, 0.31477, -5.00068, -4.367,
-              1.79782, -0.253, 1.37527, 1.09845, -0.2809],
-             [-8.89026, -7.68792, 4.22342, 10.60653, -1.52681, -1.74306, -2.8958, 3.14103, 0.4392, -7.34503, -7.72056,
-              3.96753, -0.0593, 3.3196, 2.29822, 1.20836],
-             [-14.05136, -11.16993, 4.0088, 13.65478, -1.06303, -2.8919, -3.44144, 3.70186, 0.15576, -6.73174,
-              -9.85759, 5.67507, 0.68192, 4.96721, 2.81145, 2.9585],
-             [-16.48706, -14.24566, 3.54134, 13.50534, 0.11819, -3.28402, -3.1441, 4.16155, 0.03002, -7.52477,
-              -11.74133, 7.32196, 1.33752, 6.38696, 2.74023, 3.95641],
-             [-17.28843, -19.61155, 1.60223, 11.71886, 1.27779, -1.63354, -4.01854, 5.5052, 1.31705, -6.44989,
-              -13.41993, 9.88744, 4.8081, 8.95286, -0.74586, 5.4121],
-             [-14.33444, -23.3762, 0.86087, 8.84625, 1.50228, 0.13558, -1.24792, 5.50986, 3.09639, -4.66178,
-              -14.09579, 14.12939, 7.93271, 9.89397, -5.1649, 4.70609],
-             [-11.73284, -30.43969, 1.4328, 6.2217, 1.31383, 2.34188, 2.52635, 7.39947, 3.40345, -1.80484, -13.4355,
-              19.48895, 10.86058, 7.99959, -8.20696, 3.65797]]}
-
-LGEM = {'kappa': [0.01998, -0.0056, 0.00753, 0.00599, -0.00472], 'n': 2.5, 'beta_per_h': 0.04167}
-
-INTENSITY_CONSENSUS = {'members': ['shifor', 'decay_shifor', 'ships', 'lgem', 'trend', 'mdl'],
- 'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'weights': [[0.286, 0.2617, 0.3221, 0.0373, 0.0, 0.0929], [0.1238, 0.2622, 0.3851, 0.0776, 0.0, 0.1513],
-             [0.1174, 0.2059, 0.2855, 0.1719, 0.0, 0.2193], [0.2105, 0.0762, 0.2885, 0.1968, 0.0, 0.228],
-             [0.2731, 0.0, 0.2803, 0.1949, 0.0, 0.2517], [0.3726, 0.0, 0.2007, 0.2186, 0.0, 0.2082],
-             [0.5754, 0.0, 0.0, 0.2122, 0.0, 0.2124], [0.6852, 0.0, 0.0, 0.1216, 0.0, 0.1932]],
- 'bias': [0.075, 0.171, 0.177, 0.333, 0.893, 2.41, 3.794, 3.711],
- 'ri_regime': {'cut': 0.15,
-               'weights': [[0.142, 0.1683, 0.213, 0.1966, 0.1388, 0.1413],
-                           [0.0, 0.0853, 0.1761, 0.3104, 0.1725, 0.2557],
-                           [0.0, 0.0406, 0.0931, 0.5375, 0.0216, 0.3072], [0.0, 0.0466, 0.2146, 0.6263, 0.0, 0.1125],
-                           [0.0, 0.2072, 0.1804, 0.5336, 0.0, 0.0788], [0.2607, 0.0301, 0.1053, 0.4325, 0.0, 0.1715],
-                           [0.3568, 0.0, 0.0, 0.3855, 0.0, 0.2577], [0.5113, 0.0, 0.0, 0.1494, 0.0, 0.3393]],
-               'bias': [2.511, 5.505, 9.977, 11.069, 10.605, 7.831, 4.412, 4.25]},
- 'basin_bias': {'EP': [-0.0, -0.27, -0.0, -0.0, -0.0, -0.0, 0.0, 0.0],
-                'NA': [0.57, 1.29, 2.68, 3.56, 3.67, 0.0, 0.0, 0.0],
-                'SI': [0.0, 0.0, 0.0, 0.0, -0.0, -0.0, -0.0, -0.0],
-                'SP': [0.0, 0.0, 0.0, -0.0, -0.0, 0.0, 0.0, 0.0],
-                'WP': [-0.52, -1.11, -2.08, -2.42, -1.61, -0.0, -0.0, -0.0]},
- 'basin_bias_full': {'EP': [-0.23, -0.51, -0.94, -1.45, -1.57, -0.99, -0.11, -0.0],
-                     'NA': [0.59, 1.34, 2.85, 3.82, 4.1, 3.24, 2.44, 3.78],
-                     'SI': [0.23, 0.51, 0.59, 0.46, -0.26, -2.64, -3.96, -4.68],
-                     'SP': [0.14, 0.04, 0.02, -0.09, -0.44, 0.01, 0.0, 0.09],
-                     'WP': [-0.52, -1.12, -2.11, -2.63, -2.19, -0.83, -0.63, -1.05]},
- 'basin_bias_note': "per-basin residual of the dev seasons, shrunk by the seasons' disagreement (zero where the "
-                    'three seasons do not share a sign)'}
-
-SWARM = {'priors': {'fix_sigma_km': 20.0},
- 'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'cone_scale': [0.8158, 0.9239, 0.8595, 0.8029, 0.7465, 0.7748, 0.7233, 0.7292],
- 'coverage_target': 0.67}
-
-TREND = {'tau_h': 24.0}
-
-RI = {'features': ['one', 'dv12', 'dv24', 'wind', 'headroom', 'shear', 'rh', 'sst', 'lat', 'land24', 'model_dp24',
-              'model_dp48', 'has_model', 'heat_potential', 'warm_depth', 'size', 'has_size'],
- 'threshold_kt': 30.0,
- 'weights': [-3.7741, 0.39038, 0.13388, 0.02863, 0.41741, -0.63661, 0.01293, 0.40512, -0.10709, -0.10695, 0.51014,
-             0.3428, 0.08111, -0.04398, 0.16124, 0.15615, 0.58521],
- 'base_rate': 0.08814,
- 'cases': 2462}
-
-CONSENSUS_FF = {'members': ['xtrp6', 'cliper', 'analog', 'budget_mix', 'evo12', 'med_anom48', 'int_anom48', 'budget_anom96',
-             'evo_anom48', 'evo_anom96', 'ens48_mean', 'baro_res12', 'baro', 'fflow'],
- 'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'along': [[0.0, 0.0087, 0.1577, 0.0, 0.0718, 0.0, 0.0, 0.0, 0.0882, 0.5273, 0.0, 0.0, 0.0126, 0.1422],
-           [0.0, 0.0, 0.0, 0.0212, 0.0, 0.0, 0.0, 0.0, 0.0, 0.4357, 0.0, 0.0111, 0.0985, 0.4501],
-           [0.0, 0.0, 0.0, 0.0056, 0.0, 0.0, 0.0, 0.0, 0.0, 0.2311, 0.0, 0.0549, 0.1862, 0.5525],
-           [0.0, 0.0, 0.0, 0.0117, 0.0, 0.0, 0.0, 0.0, 0.0, 0.1623, 0.0, 0.0438, 0.1871, 0.6127],
-           [0.0, 0.0, 0.0, 0.0213, 0.0, 0.0, 0.0, 0.0, 0.0, 0.1453, 0.0, 0.0372, 0.1601, 0.6349],
-           [0.0, 0.0285, 0.0108, 0.0, 0.031, 0.0, 0.0, 0.0, 0.0048, 0.1155, 0.0, 0.0, 0.1243, 0.6602],
-           [0.0, 0.1508, 0.0, 0.0, 0.0587, 0.0, 0.0, 0.0, 0.0793, 0.0, 0.0, 0.0, 0.095, 0.5997],
-           [0.0, 0.3733, 0.0, 0.0, 0.0034, 0.0, 0.0, 0.0, 0.07, 0.0333, 0.0, 0.0, 0.024, 0.5025]],
- 'cross': [[0.0, 0.0, 0.1638, 0.0603, 0.0, 0.0, 0.0, 0.0, 0.0, 0.3952, 0.0, 0.0, 0.0238, 0.357],
-           [0.0, 0.0, 0.0, 0.0956, 0.0, 0.0, 0.0, 0.0, 0.0, 0.3636, 0.0, 0.0, 0.0474, 0.4935],
-           [0.0, 0.0, 0.0, 0.0239, 0.0, 0.0, 0.0, 0.0, 0.0, 0.2741, 0.0, 0.0, 0.1138, 0.5882],
-           [0.0, 0.0, 0.0, 0.0134, 0.0, 0.0, 0.0, 0.0, 0.0, 0.2249, 0.0, 0.0431, 0.1019, 0.6167],
-           [0.0, 0.0, 0.0052, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.2066, 0.0, 0.0612, 0.1102, 0.6167],
-           [0.0, 0.0, 0.0607, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0, 0.1837, 0.0, 0.0, 0.1287, 0.6269],
-           [0.0, 0.0, 0.1465, 0.0, 0.0, 0.0, 0.0, 0.0, 0.018, 0.1575, 0.0, 0.0, 0.0809, 0.5971],
-           [0.0, 0.2311, 0.0819, 0.0, 0.0, 0.0, 0.0, 0.0, 0.0334, 0.0913, 0.0, 0.0, 0.0545, 0.5079]],
- 'reference': 1,
- 'model_blend': {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
-                 'alpha': [0.2, 0.45, 0.7, 0.8, 0.85, 0.9, 0.9, 0.9],
-                 'offset_tau_h': None,
-                 'alpha_multi': [0.25, 0.5, 0.775, 0.875, 0.95, 0.95, 0.95, 0.975]}}
-
-CONSENSUS_BASIC_FF = {'members': ['xtrp6', 'cliper', 'budget_mix', 'evo12', 'baro_res12', 'baro', 'fflow'],
- 'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'along': [[0.0, 0.0, 0.3882, 0.4795, 0.0, 0.05, 0.0814], [0.0, 0.0, 0.2915, 0.1357, 0.0271, 0.1281, 0.4319],
-           [0.0, 0.0, 0.1056, 0.0835, 0.0599, 0.2064, 0.5701], [0.0, 0.0, 0.0667, 0.0698, 0.0457, 0.1972, 0.6306],
-           [0.0, 0.0, 0.0667, 0.0637, 0.048, 0.159, 0.6526], [0.0, 0.0699, 0.0125, 0.0906, 0.0, 0.1297, 0.6682],
-           [0.0, 0.2002, 0.0, 0.0748, 0.0, 0.0968, 0.6103], [0.0, 0.4415, 0.0, 0.0274, 0.0, 0.0235, 0.5166]],
- 'cross': [[0.0, 0.0, 0.3901, 0.1183, 0.0, 0.0259, 0.4656], [0.0, 0.0, 0.3888, 0.0, 0.0, 0.0599, 0.5514],
-           [0.0, 0.0, 0.195, 0.0297, 0.0056, 0.1175, 0.6523], [0.0, 0.0, 0.1129, 0.0558, 0.0836, 0.0832, 0.6645],
-           [0.0, 0.0, 0.0664, 0.0702, 0.1365, 0.0669, 0.66], [0.0198, 0.0612, 0.015, 0.0825, 0.0, 0.1543, 0.6671],
-           [0.0178, 0.2063, 0.0, 0.0545, 0.0, 0.0868, 0.6346], [0.0, 0.3901, 0.0, 0.0224, 0.0, 0.055, 0.5324]],
- 'reference': 1,
- 'model_blend': {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
-                 'alpha': [0.2, 0.45, 0.7, 0.8, 0.85, 0.9, 0.9, 0.9],
-                 'offset_tau_h': None,
-                 'alpha_multi': [0.25, 0.5, 0.775, 0.875, 0.95, 0.95, 0.95, 0.975]}}
-
-CONE_KM_FF = {'leads': [6, 12, 24, 36, 48, 72, 96, 120], 'radius_km': [27.0, 48.4, 80.9, 109.3, 137.7, 212.0, 304.9, 412.7]}
-
-CONE_KM_BASIC_FF = {'leads': [6, 12, 24, 36, 48, 72, 96, 120], 'radius_km': [27.1, 47.9, 80.1, 109.1, 137.4, 213.6, 303.1, 410.4]}
-
-SWARM_FF = {'priors': {'fix_sigma_km': 20.0},
- 'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'cone_scale': [0.7006, 0.7004, 0.5164, 0.4108, 0.3379, 0.2734, 0.2885, 0.3051],
- 'coverage_target': 0.67}
-
-CONE_FLOW = {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'predictors': ['one', 'member_spread_km', 'model_consensus_km', 'fflow_model_km', 'speed_kmh', 'abs_lat', 'wind_kt'],
- 'coef': [[2.96823, 0.59342, 0.00565, 0.12792, 0.23186, 0.10118, -0.0204],
-          [14.95615, 0.22804, 0.21996, 0.06738, 0.00608, 0.07014, -0.0616],
-          [39.00611, -0.00096, 0.39293, 0.03688, -0.25629, -0.59159, -0.0671],
-          [66.14719, 0.06061, 0.3074, -0.03535, -0.20376, -0.62383, -0.15522],
-          [101.59234, 0.11243, 0.14908, -0.03998, -0.38773, -0.38886, -0.27248],
-          [106.22439, 0.1211, 0.12004, 0.00269, -0.20855, 1.44964, -0.494],
-          [89.42837, 0.20677, 0.16346, -0.07412, -0.34735, 4.60663, -0.84788],
-          [110.41666, 0.33869, 0.03837, -0.0704, -2.76008, 6.45517, -0.70091]],
- 'scale': [1.1696, 1.1781, 1.2718, 1.1672, 1.1014, 1.0922, 1.083, 1.1142],
- 'medians': [1.0, 204.81, 157.665, 161.497, 16.417, 18.1, 45.0],
- 'coverage_target': 0.67}
-
-MODEL_INTENSITY = {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'kt_per_hpa': [0.73942, 1.46518, 2.17201, 2.30907, 2.35915, 2.22927, 1.9977, 1.52248]}
-
-INTENSITY_SPREAD = {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'thresholds_kt': [64, 96, 113, 137],
- 'quantile_levels': [0.02, 0.06, 0.1, 0.14, 0.18, 0.22, 0.26, 0.3, 0.34, 0.38, 0.42, 0.46, 0.5, 0.54, 0.58, 0.62,
-                     0.66, 0.7, 0.74, 0.78, 0.82, 0.86, 0.9, 0.94, 0.98],
- 'quantiles': {'normal': [[-10.43, -6.69, -5.33, -4.07, -3.31, -2.69, -2.33, -1.98, -1.6, -1.26, -0.98, -0.68, -0.31,
-                           0.15, 0.59, 1.13, 1.66, 2.24, 2.7, 3.12, 3.6, 4.06, 4.78, 6.92, 11.1],
-                          [-17.63, -11.58, -9.17, -7.6, -6.17, -5.18, -4.48, -3.76, -3.02, -2.44, -1.81, -1.15, -0.45,
-                           0.27, 0.89, 1.63, 2.25, 3.15, 4.18, 5.15, 6.26, 7.48, 9.54, 12.08, 19.38],
-                          [-28.46, -18.99, -14.97, -12.84, -10.9, -9.07, -7.59, -6.47, -5.24, -4.12, -3.22, -2.23,
-                           -1.15, -0.26, 0.98, 2.08, 3.54, 5.27, 6.96, 8.68, 10.66, 12.96, 16.63, 21.97, 32.53],
-                          [-33.51, -24.34, -19.33, -16.14, -13.86, -12.34, -10.71, -9.14, -7.74, -6.31, -4.81, -3.49,
-                           -2.04, -0.63, 0.59, 2.48, 4.16, 6.53, 8.57, 11.28, 14.21, 17.73, 22.08, 28.16, 41.22],
-                          [-36.89, -27.0, -22.05, -19.55, -16.98, -14.65, -12.91, -11.04, -9.39, -7.87, -6.57, -5.02,
-                           -3.4, -1.69, 0.45, 1.97, 4.4, 7.23, 10.21, 13.38, 17.19, 20.9, 26.13, 34.91, 49.16],
-                          [-39.35, -29.83, -26.33, -23.19, -20.56, -18.09, -16.16, -14.49, -12.55, -10.49, -8.99,
-                           -7.48, -5.61, -3.39, -1.38, 0.99, 3.87, 7.26, 11.38, 15.74, 20.65, 28.42, 35.69, 43.84,
-                           58.55],
-                          [-38.57, -31.41, -28.27, -24.46, -22.85, -20.85, -18.32, -16.22, -14.36, -12.56, -10.89,
-                           -9.21, -6.77, -4.81, -2.88, -0.7, 3.04, 6.3, 11.39, 17.49, 23.12, 31.18, 40.74, 49.6,
-                           62.99],
-                          [-37.33, -31.89, -28.37, -26.21, -23.91, -21.92, -20.11, -17.59, -15.7, -14.22, -12.66,
-                           -10.29, -7.86, -5.55, -3.55, -1.47, 3.22, 8.11, 12.88, 19.0, 25.83, 33.36, 43.15, 52.55,
-                           66.84]],
-               'rapid': [[-11.97, -7.07, -6.32, -5.62, -5.07, -4.66, -2.96, -1.93, -1.54, -1.23, -0.93, -0.7, -0.54,
-                          -0.37, -0.22, 0.14, 1.16, 2.41, 3.15, 3.71, 4.29, 5.29, 7.8, 9.06, 13.53],
-                         [-22.3, -14.41, -11.14, -8.95, -7.55, -6.86, -6.27, -5.7, -5.11, -3.96, -2.42, -1.85, -1.08,
-                          -0.26, 0.72, 2.3, 3.1, 3.78, 4.77, 6.61, 7.97, 9.29, 12.56, 18.26, 27.67],
-                         [-36.06, -23.24, -19.03, -16.06, -14.01, -11.51, -10.45, -8.46, -7.17, -5.52, -4.4, -3.39,
-                          -1.41, 0.06, 1.8, 3.5, 5.11, 6.16, 8.07, 10.75, 13.56, 16.72, 21.24, 26.66, 41.8],
-                         [-40.76, -33.14, -25.88, -22.72, -19.23, -17.13, -15.15, -12.7, -11.19, -9.29, -6.28, -4.27,
-                          -1.27, 1.02, 3.85, 5.66, 8.15, 10.2, 13.61, 17.42, 19.78, 25.54, 30.02, 36.7, 49.91],
-                         [-49.34, -39.31, -31.15, -28.72, -25.44, -22.51, -18.39, -15.23, -11.37, -8.74, -6.12, -3.8,
-                          -0.84, 1.3, 4.76, 6.62, 10.26, 13.5, 17.08, 21.95, 24.74, 27.54, 35.25, 42.19, 55.38],
-                         [-53.39, -42.0, -34.72, -31.21, -26.81, -24.07, -20.73, -17.13, -14.77, -12.89, -9.57, -6.58,
-                          -4.33, -0.04, 3.64, 7.79, 10.28, 15.26, 20.12, 23.03, 28.46, 34.22, 40.92, 46.85, 66.41],
-                         [-48.14, -39.93, -34.17, -27.87, -25.33, -23.18, -21.87, -18.84, -15.88, -13.81, -12.1,
-                          -8.68, -6.41, -3.4, 0.82, 6.0, 10.37, 14.95, 18.98, 21.9, 27.54, 36.55, 44.2, 48.48,
-                          60.49],
-                         [-48.96, -37.56, -32.83, -28.22, -25.98, -23.5, -19.21, -16.26, -14.51, -12.72, -10.36,
-                          -7.66, -5.96, -4.35, -1.14, 1.09, 4.98, 11.67, 17.23, 23.53, 27.91, 35.48, 43.4, 49.2,
-                          59.64]]}}
-
-OCEAN = {'d26_reference_m': 50.0,
- 'd26_power': 0.0,
- 'sst_anomaly_per_c': 0.0,
- 'source': 'WOA23 decadal-average monthly temperature, 1 degree'}
-
-RI_PATH = {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'threshold_kt': 30.0,
- 'cases': 217,
- 'mean_change_kt': [8.89, 19.31, 39.79, 44.19, 37.28, 22.71, 12.6, 8.41],
- 'p75_change_kt': [10.0, 25.0, 45.0, 60.0, 60.0, 46.25, 35.0, 30.0]}
-
-PEAK = {'thresholds_kt': [64.0, 96.0, 113.0, 137.0],
- 'features': ['one', 'v0', 'cons_rise', 'cons_max', 'headroom72', 'tchp48', 'shear48', 'rh48', 'p_ri', 'logit_p',
-              'dp24', 'has_dp', 'land72', 'abslat'],
- 'mean': [54.35838, 12.04692, 66.4053, 91.12471, 28.25157, 10.53359, 0.6865, 0.07466, -3.27858, -0.88102, 0.95414,
-          0.12388, 19.46433],
- 'std': [28.01184, 14.80723, 24.62294, 48.01961, 26.90911, 6.39609, 0.15142, 0.08733, 1.53582, 4.07612, 0.20917,
-         0.25617, 7.26468],
- 'weights': {'64': [-0.34656, 0.40907, 0.07791, 0.51222, 0.03019, 0.2608, -0.43828, 0.13844, 0.49819, 0.37792,
-                    -0.45497, 0.2156, -0.2234, 0.04331],
-             '96': [-1.53113, 0.51111, 0.17933, 0.6893, 0.07005, 0.08913, -0.26839, -0.09395, 0.26191, 0.29463,
-                    -0.19445, 0.14694, -0.10294, -0.02554],
-             '113': [-2.35718, 0.46554, 0.23991, 0.67389, -0.01198, 0.18414, -0.08776, -0.15367, 0.27805, 0.27366,
-                     -0.19527, 0.09465, -0.15963, -0.21935],
-             '137': [-3.97029, 0.3479, 0.08509, 0.44695, -0.02151, 0.487, -0.00123, -0.32133, 0.21329, 0.21602,
-                     0.00164, 0.0329, -0.15872, -0.24077]}}
-
-TRACK_FEEDBACK = {'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'max_lead_h': 48,
- 'beta': {'12': [0.043, 0.239, 0.624, 0.653, 0.632, 0.0, 0.0, 0.0],
-          '24': [0.01, 0.083, 0.254, 0.335, 0.342, 0.0, 0.0, 0.0]},
- 'note': "share of the previous cycle's error (its forecast for the analysis time minus the analysis) subtracted "
-         'from the new blended track; fitted on the 2016/2017/2019 HRES blends; held-out gain on the multi-model '
-         'blend about 1% at 12-36 h, none beyond 48 h'}
-
-RAIN_SCALE = {'multiplier': 1.19,
- 'tail': 1.5,
- 'asymmetry': 0.3,
- 'asymmetry_phase_deg': 45.0,
- 'rule': 'R-CLIPER along the observed track of 24 US landfalls against MRMS gauge-corrected radar; the exponential '
-         'tail widened 1.5x and a front-right wavenumber-1 asymmetry of 0.3 added, the multiplier then set so the 8 '
-         "tuning storms' total rain is unbiased",
- 'dev_storms': ['hermine2016', 'matthew2016', 'harvey2017', 'irma2017', 'nate2017', 'barry2019', 'imelda2019',
-                'dorian2019'],
- 'test_storms': ['gordon2018', 'florence2018', 'michael2018', 'hanna2020', 'isaias2020', 'laura2020', 'sally2020',
-                 'delta2020', 'claudette2021', 'elsa2021', 'fred2021', 'henri2021', 'ida2021', 'nicholas2021',
-                 'ian2022', 'nicole2022'],
- 'held_out': {'as_published_x1': {'mae': 37.7527,
-                                  'bias': 11.7949,
-                                  'area100': 1.353,
-                                  'area250': 1.7405,
-                                  'csi100': 0.2876,
-                                  'csi250': 0.2952,
-                                  'corr': 0.5733,
-                                  'mae_heavy': 72.2621,
-                                  'p995': 1.1062},
-              'standard_profile_x1.91': {'mae': 37.7527,
-                                         'bias': 11.7949,
-                                         'area100': 1.353,
-                                         'area250': 1.7405,
-                                         'csi100': 0.2876,
-                                         'csi250': 0.2952,
-                                         'corr': 0.5733,
-                                         'mae_heavy': 72.2621,
-                                         'p995': 1.1062},
-              'shipped': {'mae': 37.512,
-                          'bias': 13.6903,
-                          'area100': 1.4198,
-                          'area250': 1.5873,
-                          'csi100': 0.2958,
-                          'csi250': 0.3477,
-                          'corr': 0.5876,
-                          'mae_heavy': 65.9236,
-                          'p995': 1.017},
-              'strong_storms_standard_x1.91': {'mae': 40.5859,
-                                               'bias': 5.2125,
-                                               'area100': 1.2833,
-                                               'area250': 3.1788,
-                                               'csi100': 0.2734,
-                                               'csi250': 0.1706,
-                                               'corr': 0.4895,
-                                               'mae_heavy': 67.5825,
-                                               'p995': 1.2093},
-              'strong_storms_shipped': {'mae': 40.4345,
-                                        'bias': 7.7117,
-                                        'area100': 1.4292,
-                                        'area250': 1.7325,
-                                        'csi100': 0.2781,
-                                        'csi250': 0.1213,
-                                        'corr': 0.4687,
-                                        'mae_heavy': 58.6596,
-                                        'p995': 0.9877}}}
-
-PEAK_QUANTILES = {'features': ['one', 'v0', 'cons_rise', 'cons_max', 'headroom72', 'tchp48', 'shear48', 'rh48', 'p_ri', 'logit_p',
-              'dp24', 'has_dp', 'land72', 'abslat', 'scen_rise'],
- 'mean': [54.35838, 12.04692, 66.4053, 91.12471, 28.25157, 10.53359, 0.6865, 0.07466, -3.27858, -0.88102, 0.95414,
-          0.12388, 19.46433, 33.36314],
- 'std': [28.01184, 14.80723, 24.62294, 48.01961, 26.90911, 6.39609, 0.15142, 0.08733, 1.53582, 4.07612, 0.20917,
-         0.25617, 7.26468, 16.53708],
- 'quantiles': {'0.5': [15.98992, -3.98112, 11.54093, 2.4112, 1.02477, 2.45392, -2.12953, 0.56947, 5.62092, -1.67897,
-                       -1.14164, 5.05584, -1.45962, -0.18116, -0.22434],
-               '0.75': [30.39761, -5.33318, 14.14135, 2.43683, 2.82383, 2.93821, -1.81273, 0.17093, 1.75926, 2.4545,
-                        -1.39718, 5.06781, -1.54468, -0.22826, 0.02534],
-               '0.9': [46.41835, -6.40701, 12.41642, 0.17791, 4.61604, 4.64533, -2.62747, -1.07527, -2.5048, 6.03149,
-                       -0.94617, 9.08334, -2.70622, -1.98146, 0.77281],
-               '0.95': [55.89355, -5.76505, 8.15522, -1.65429, 6.7332, 8.27783, -3.56078, -1.46701, -1.37289, 4.86184,
-                        -0.45709, 7.24641, -5.0844, -1.33421, -0.45249]},
- 'note': 'linear pinball-loss fits of (true 120 h peak - analysis wind) on the standardised PEAK features plus the '
-         'RI-path peak rise; dev 2016/2017/2019'}
-
-PEAK_IF_RI = {'features': ['one', 'v0', 'cons_rise', 'cons_max', 'headroom72', 'tchp48', 'shear48', 'rh48', 'p_ri', 'logit_p',
-              'dp24', 'has_dp', 'land72', 'abslat', 'scen_rise'],
- 'weights': [53.1333, -3.89744, 9.0371, 1.00069, 8.10017, 3.15362, 1.76969, -1.45009, 0.2314, -6.3153, 0.86357, -0.0,
-             -8.76211, -4.40894, -4.77421],
- 'mean': [54.35838, 12.04692, 66.4053, 91.12471, 28.25157, 10.53359, 0.6865, 0.07466, -3.27858, -0.88102, 0.95414,
-          0.12388, 19.46433, 33.36314],
- 'std': [28.01184, 14.80723, 24.62294, 48.01961, 26.90911, 6.39609, 0.15142, 0.08733, 1.53582, 4.07612, 0.20917,
-         0.25617, 7.26468, 16.53708]}
-
-ARRIVAL_TIME_ERROR = {'hours': {'24': {'all': {'mean_h': 1.2, 'median_h': 0.3, 'mae_h': 3.55, 'n': 3432, 'never_crosses': 1015},
-                  'by_forecast_speed': {'< 3 m/s': {'mean_h': 3.54, 'mae_h': 7.3, 'n': 794},
-                                        '3-5': {'mean_h': 0.82, 'mae_h': 3.02, 'n': 1152},
-                                        '5-8': {'mean_h': 0.29, 'mae_h': 1.88, 'n': 1213},
-                                        '> 8': {'mean_h': 0.09, 'mae_h': 2.22, 'n': 273}}},
-           '48': {'all': {'mean_h': 0.87, 'median_h': 0.66, 'mae_h': 5.65, 'n': 2685, 'never_crosses': 1762},
-                  'by_forecast_speed': {'< 3 m/s': {'mean_h': -0.05, 'mae_h': 9.91, 'n': 666},
-                                        '3-5': {'mean_h': 1.67, 'mae_h': 5.28, 'n': 949},
-                                        '5-8': {'mean_h': 0.95, 'mae_h': 3.24, 'n': 935},
-                                        '> 8': {'mean_h': -0.84, 'mae_h': 3.99, 'n': 135}}}},
- 'speed_bins_ms': {'< 3 m/s': [0, 3], '3-5': [3, 5], '5-8': [5, 8], '> 8': [8, 99]},
- 'sign': 'forecast arrival minus truth, hours; positive = the forecast arrives late',
- 'source': 'held-out 2018 / 2020-2022, multi-model blend, crossing of the line through the truth position at 24 / 48 '
-           "h perpendicular to the truth motion; speed = the forecast's mean speed to that lead"}
-
-ADECK_TRACK = {'members': ['ours', 'HCCA', 'TVCN', 'AEMI', 'AVNI'],
- 'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'weights': [[0.5, 0.5, 0.0, 0.0, 0.0], [0.5, 0.5, 0.0, 0.0, 0.0], [0.5, 0.5, 0.0, 0.0, 0.0],
-             [0.5, 0.5, 0.0, 0.0, 0.0], [0.5, 0.5, 0.0, 0.0, 0.0], [0.5, 0.5, 0.0, 0.0, 0.0],
-             [0.5, 0.5, 0.0, 0.0, 0.0], [0.5, 0.5, 0.0, 0.0, 0.0]],
- 'choice': 'mean(ours, HCCA)',
- 'fitted_weights': [[0.7215, 0.1061, 0.0928, 0.0, 0.0796], [0.5115, 0.3462, 0.1423, 0.0, 0.0],
-                    [0.5168, 0.385, 0.0982, 0.0, 0.0], [0.4952, 0.4472, 0.0576, 0.0, 0.0],
-                    [0.5233, 0.3573, 0.1195, 0.0, 0.0], [0.4718, 0.3265, 0.2017, 0.0, 0.0],
-                    [0.4351, 0.4838, 0.0, 0.0811, 0.0], [0.3687, 0.279, 0.3523, 0.0, 0.0]],
- 'dev_loso_gain_pct': {'mean(ours, HCCA)': [0.09, 1.69, 2.1, 2.38, 2.15, 2.05, 2.34, 1.96],
-                       'mean(ours, HCCA, TVCN)': [-1.33, 1.49, 2.02, 2.31, 1.91, 2.0, 2.52, 2.33],
-                       'mean(ours, all aids)': [-3.21, 0.32, 0.85, 1.03, 0.57, 0.61, 1.43, 1.21],
-                       'ours 1/3 + HCCA 2/3': [-1.52, 1.29, 1.87, 2.24, 1.88, 1.82, 2.32, 1.98],
-                       'fitted': [1.06, 1.73, 2.08, 2.18, 1.89, 1.81, 2.24, 2.16]},
- 'note': "our blended track and the NHC a-deck's early-cycle consensus aids, weights renormalised over the members "
-         'present; the rule chosen on the tuning seasons (2016/2017/2019, our own track cross-fitted by season) was '
-         'the plain mean of ours and HCCA; TVCN stands in when HCCA is absent (the three-way mean scored within 0.2% '
-         'of the pair on the tuning seasons)',
- 'substitutes': {'HCCA': ['TVCN']},
- 'held_out_gain_pct': [2.8, 11.0, 13.0, 11.9, 6.4, 11.4, 12.6, 12.7],
- 'held_out_vs_ofcl_pct': [22.0, 15.9, 15.5, 14.6, 18.1, 11.7, 5.8, 4.7],
- 'adaptive': {'b': [0.5, 0.5, 0.5, 0.0, 0.0, 0.0, 0.0, 0.0],
-              'cap': 0.75,
-              'eps_km': 5.0,
-              'note': 'w_ours = clip(sigmoid(b log((e_HCCA + eps)/(e_ours + eps))), 1 - cap, cap) from the previous '
-                      "cycle's 6-24 h forecast errors for the position now analysed; b and cap chosen per lead on "
-                      'the tuning seasons (zero from 36 h on, where nothing was earned); held-out gain +0.9% at 12 h '
-                      '(significant), +1.1% at 24 h'},
- 'gate': {'gamma': 0.1,
-          'start_cone_radii': 1.5,
-          'min_lead_h': 12,
-          'tiebreaker': 'TVCN',
-          'note': 'up to 10% of the ours/HCCA share moves away from whichever of the two is further from TVCN, once '
-                  'they sit more than 1.5 cone radii apart (the full shift at 2.5); on the tuning seasons a tie with '
-                  'the plain mean (88.5 vs 88.4 km mean error at 12-72 h) and a loss at 6 h in every season, hence '
-                  'from 12 h; held-out with the earned weights: 1.4-2.5% lower error at 12-36 h, 1-2% at 48-120 h, '
-                  'every lead significant'}}
-
-ADECK_INTENSITY = {'members': ['ours', 'IVCN', 'HWFI', 'HMNI', 'DSHP', 'LGEM', 'AVNI', 'HCCA'],
- 'leads': [6, 12, 24, 36, 48, 72, 96, 120],
- 'weights': [[0.7767, 0.0, 0.1386, 0.0847, 0.0, 0.0, 0.0, 0.0], [0.5388, 0.0, 0.1083, 0.2756, 0.0, 0.0, 0.0, 0.0773],
-             [0.2001, 0.0, 0.2488, 0.2078, 0.0, 0.0, 0.0, 0.3433],
-             [0.0657, 0.1857, 0.25, 0.2599, 0.0017, 0.0, 0.0, 0.2372],
-             [0.0, 0.0003, 0.0, 0.275, 0.008, 0.0, 0.0085, 0.7082],
-             [0.0, 0.7262, 0.0994, 0.034, 0.0, 0.0, 0.0801, 0.0603],
-             [0.0, 0.175, 0.2236, 0.0002, 0.0, 0.0, 0.0, 0.6012],
-             [0.0454, 0.3921, 0.1216, 0.1015, 0.0, 0.0, 0.0581, 0.2813]],
- 'loso_gain_pct': {'2016': [2.81, 0.94, 13.24, 21.77, 28.5, 26.92, 28.2, 21.85],
-                   '2017': [3.44, 9.74, 17.61, 23.98, 26.54, 32.53, 30.57, 23.09],
-                   '2019': [0.43, 5.66, 13.28, 23.5, 22.03, 28.94, 24.6, 1.91]},
- 'note': "simplex weights per lead over the 0.15 consensus and the a-deck's early-cycle intensity aids, smooth-L1 "
-         'fit on the tuning seasons 2016/2017/2019 (leave-one-season-out gains 13-28% at 24-96 h in every season); '
-         'members missing live are renormalised away; HAFS-A and HAFS-B stand in for HWRF and HMON when those are '
-         'absent (successor models, a lineage stand-in that the archive could not verify)',
- 'substitutes': {'HWFI': ['HFAI'], 'HMNI': ['HFBI']},
- 'held_out_gain_pct': [2.9, 9.9, 26.0, 30.6, 31.4, 35.1, 32.0, 32.3],
- 'held_out_vs_ofcl_pct': [6.4, -7.9, 4.9, 4.5, 5.9, 6.1, -0.7, 4.6]}
-
-PROVENANCE = {'generated': '2026-10-19 15:26 UTC',
- 'CLIPER': 'IBTrACS v04r01 best tracks 1980-2014, all basins (82,816 fixes at 00/06/12/18 UTC)',
- 'SHIFOR': 'IBTrACS v04r01 best tracks 1980-2014, all basins',
- 'CONSENSUS': 'hindcasts of the 2016, 2017 and 2019 seasons (3,053 forecasts, NA EP WP SI SP)',
- 'ANALOGS': 'built at run time from 1980-2014 best tracks (100 neighbours, bandwidth 1.5)',
- 'held_out': '2018, 2020, 2021, 2022 -- never used for fitting',
- 'CONSENSUS_BASIC': 'same hindcasts as CONSENSUS; the members that need neither a climatology nor an analog database',
- 'GENESIS': 'northern-hemisphere candidates of June-November 2016, 2017, 2019 (16,929 candidates, 194 formations); '
-            'second-order terms chosen by leave-one-season-out cross-validation',
- 'CONE_KM': 'hindcasts of the 2016, 2017 and 2019 seasons',
- 'SHIPS': 'hindcasts of the 2016, 2017 and 2019 seasons',
- 'LGEM': 'hindcasts of the 2016, 2017 and 2019 seasons',
- 'INTENSITY_CONSENSUS': 'simplex weights per lead on leave-one-season-out members of 2016, 2017 and 2019; the rapid '
-                        'regime fitted where P(RI) >= 0.15; per-basin bias from the dev residuals, shrunk to zero '
-                        'where the three seasons disagree on its sign',
- 'SWARM': 'hindcasts of the 2016, 2017 and 2019 seasons',
- 'CONSENSUS_FF': "hindcasts of the 2016, 2017 and 2019 seasons with ECMWF HRES forecast steering and HRES's own "
-                 'storm tracks (WeatherBench 2, 1.5 degrees); blend weights fitted on leave-one-season-out consensus '
-                 'tracks',
- 'CONSENSUS_BASIC_FF': "hindcasts of the 2016, 2017 and 2019 seasons with ECMWF HRES forecast steering and HRES's "
-                       'own storm tracks (WeatherBench 2, 1.5 degrees); blend weights fitted on leave-one-season-out '
-                       'consensus tracks',
- 'CONE_KM_FF': "hindcasts of the 2016, 2017 and 2019 seasons with ECMWF HRES forecast steering and HRES's own storm "
-               'tracks (WeatherBench 2, 1.5 degrees); blend weights fitted on leave-one-season-out consensus tracks',
- 'CONE_KM_BASIC_FF': "hindcasts of the 2016, 2017 and 2019 seasons with ECMWF HRES forecast steering and HRES's own "
-                     'storm tracks (WeatherBench 2, 1.5 degrees); blend weights fitted on leave-one-season-out '
-                     'consensus tracks',
- 'SWARM_FF': "hindcasts of the 2016, 2017 and 2019 seasons with ECMWF HRES forecast steering and HRES's own storm "
-             'tracks (WeatherBench 2, 1.5 degrees); blend weights fitted on leave-one-season-out consensus tracks; '
-             'the 0.13 perturbation priors kept: quieter ones matched the consensus error on the tuning seasons but '
-             'were worse-calibrated for scenarios on the held-out ones',
- 'RI': 'logistic regression, P(+30 kt in 24 h), hindcasts of the 2016, 2017 and 2019 seasons; predictors: the '
-       "SHIPS-style set, HRES's central-pressure deepening along its own track, ocean heat content and 26 C isotherm "
-       'depth from the WOA23 climatology, the gale radius; held-out Brier skill 0.154, AUC 0.864',
- 'TREND': 'hindcasts of the 2016, 2017 and 2019 seasons',
- 'CONE_FLOW': "hindcasts of the 2016, 2017 and 2019 seasons with ECMWF HRES forecast steering and HRES's own storm "
-              'tracks (WeatherBench 2, 1.5 degrees); blend weights fitted on leave-one-season-out consensus tracks; '
-              'Goerss-style regression of the blended consensus error on member spread, model disagreement, speed, '
-              'latitude and intensity',
- 'MODEL_INTENSITY': "kt per hPa of HRES's central-pressure-deficit change along its track, per lead, least squares "
-                    'on the 2016, 2017 and 2019 seasons',
- 'INTENSITY_SPREAD': "quantiles of the intensity consensus's leave-one-season-out errors on 2016, 2017 and 2019, per "
-                     'lead and regime',
- 'OCEAN': 'WOA23 decadal-average monthly temperature on 1 degree: depth of the 26 C isotherm and tropical cyclone '
-          'heat potential; depth-aware wake cooling and the SST-anomaly depth were tried and rejected on the tuning '
-          'seasons (power 0)',
- 'RI_PATH': 'mean and 75th-percentile intensity change of the 2016, 2017 and 2019 storms whose 24 h change reached '
-            '30 kt (217 cases)',
- 'PEAK': 'logistic regression of P(peak intensity within 120 h >= 64 / 96 / 113 / 137 kt) on the 2016, 2017 and 2019 '
-         'seasons; held-out Brier skill 0.32 / 0.31 / 0.29 / 0.27 against 0.26 / 0.22 / 0.15 / 0.16 for the best '
-         'per-lead category probability',
- 'TRACK_FEEDBACK': "share of the previous cycle's blended-track error subtracted from the new track, least squares "
-                   'per lead on the 2016, 2017 and 2019 HRES blends; about 1% on the held-out multi-model blend at '
-                   '12-36 h, zero beyond 48 h',
- 'RAIN_SCALE': 'R-CLIPER storm totals along the observed track against NOAA MRMS gauge-corrected radar for US '
-               'landfalls of 2016, 2017 and 2019 (fit) and 2018, 2020-2022 (held-out)',
- 'PEAK_QUANTILES': 'linear pinball-loss fits of the 120 h peak rise on the PEAK features plus the RI-path rise, '
-                   '2016/2017/2019; held-out coverage 0.53 / 0.77 / 0.91 / 0.95 at the 50 / 75 / 90 / 95% levels',
- 'PEAK_IF_RI': "ridge fit of the 120 h peak on the tuning seasons' rapid intensifiers (+30 kt / 24 h); held-out RI "
-               'cases bias +0.6 kt, MAE 13 kt',
- 'ARRIVAL_TIME_ERROR': "held-out 2018 / 2020-2022: error of the blended track's crossing of the line through the "
-                       "truth position at 24 and 48 h, by the forecast's translation speed; no systematic bias, slow "
-                       'movers the uncertain ones',
- 'ADECK_TRACK': 'NHC a-deck aids (HCCA, TVCN, AEMI, AVNI) matched to the 2016, 2017 and 2019 Atlantic cases; the '
-                'rule chosen on them (our track cross-fitted by season) is the plain mean of ours and HCCA; held-out '
-                'Atlantic 2018 / 2020-2022: 11-13% lower track error than ours at 12-120 h, 12-22% lower than the '
-                "official forecast at 6-72 h; the split between ours and HCCA earned from the previous cycle's "
-                'verified errors at 6-24 h and moved away from the member that stands alone against TVCN beyond 1.5 '
-                'cone radii from 12 h (together +1.4-2.5% held-out at 12-36 h, +1-2% at 48-120 h)',
- 'ADECK_INTENSITY': 'NHC a-deck intensity aids (IVCN, HWRF, HMON, SHIPS, LGEM, GFS, HCCA) matched to the 2016, 2017 '
-                    'and 2019 Atlantic cases, smooth-L1 simplex weights per lead; held-out Atlantic 2018 / '
-                    '2020-2022: 26-35% lower intensity error than ours at 24-120 h and 4-6% lower than the official '
-                    'forecast at 24-120 h'}

naturev1/cyclone/consensus.py

@@ -1,234 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-A consensus that weighs speed and direction separately.
-
-The idea: forecast members are good at different things. Extrapolation knows how fast the storm is going
-right now; a steering trajectory knows where the flow will turn it; climatology knows that storms slow down
-near the ridge. Averaging whole positions throws that away -- a member with excellent direction but poor
-speed drags the consensus off in both. So each member's displacement (in the storm-centred frame, km) is
-split into an **along-track** part (along the direction of a reference forecast) and a **cross-track** part,
-and the two get their own weights at every lead, fitted on past seasons:
-
-* cross-track weights are non-negative and sum to one (a convex blend of directions);
-* along-track weights are non-negative but free in sum, which lets the consensus correct the systematic
-  slowness or quickness that every physics member has (a scale of 1.05 is a 5% speed-up);
-* members missing for a case drop out and the rest renormalise (cross-track) or rescale by the fitted
-  total (along-track).
-
-Weights are fitted by projected gradient descent on the squared error in km (convex; the projection is onto the
-simplex for cross-track and onto the non-negative orthant for along-track). Then, optionally, a
-**selective** step (Goerss's "selective consensus") drops members that disagree with the median by more
-than ``k`` times the members' spread before blending.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from . import geometry
-
-from .geometry import from_local, to_local
-
-
-def to_displacements(cases, forecasts: np.ndarray) -> np.ndarray:
-    """``(N, L, M, 2)`` lat/lon -> ``(N, L, M, 2)`` (east, north) km from each case's initial position."""
-    lat0 = np.array([c.lat for c in cases])[:, None, None]
-    lon0 = np.array([c.lon for c in cases])[:, None, None]
-    east, north = to_local(lat0, lon0, forecasts[..., 0], forecasts[..., 1])
-    out = np.stack([east, north], -1)
-    out[~np.isfinite(forecasts).all(-1)] = np.nan
-    return out
-
-
-def from_displacements(cases, displacement: np.ndarray) -> np.ndarray:
-    """``(N, L, 2)`` km -> lat/lon."""
-    lat0 = np.array([c.lat for c in cases])[:, None]
-    lon0 = np.array([c.lon for c in cases])[:, None]
-    lat, lon = from_local(lat0, lon0, displacement[..., 0], displacement[..., 1])
-    out = np.stack([lat, lon], -1)
-    out[~np.isfinite(displacement).all(-1)] = np.nan
-    return out
-
-
-def project_simplex(w: np.ndarray) -> np.ndarray:
-    """Nearest point on the probability simplex (Duchi et al. 2008)."""
-    u = np.sort(w)[::-1]
-    css = np.cumsum(u) - 1.0
-    k = np.arange(1, w.size + 1)
-    rho = np.nonzero(u - css / k > 0)[0][-1]
-    return np.maximum(w - css[rho] / (rho + 1.0), 0.0)
-
-
-def _reference_direction(displacements: np.ndarray, reference: int) -> np.ndarray:
-    """``(N, L, 2)`` unit vector of the reference member (falling back to the member mean)."""
-    ref = displacements[:, :, reference]
-    mean = np.nanmean(displacements, axis=2)
-    ref = np.where(np.isfinite(ref), ref, mean)
-    length = np.linalg.norm(ref, axis=-1, keepdims=True)
-    unit = ref / np.maximum(length, 1e-6)
-    unit[(length[..., 0] < 1e-6)] = np.array([0.0, 1.0])
-    return unit
-
-
-def _fit_one(a: np.ndarray, b: np.ndarray, simplex: bool, steps: int = 4000) -> np.ndarray:
-    """
-    Weights minimising the mean of ``(a w - b)^2`` (members missing from a case, NaN in ``a``, are renormalised
-    away), by accelerated projected gradient (FISTA) with the exact Lipschitz step ``1 / lambda_max(a^T a / n)`` --
-    nearly collinear members make a cruder step diverge.
-    """
-    n, m = a.shape
-    ok = np.isfinite(a)
-    filled = np.where(ok, a, 0.0)
-    lipschitz = float(np.linalg.eigvalsh(filled.T @ filled / n)[-1])
-    lr = 1.0 / max(lipschitz, 1e-12)
-    project = project_simplex if simplex else (lambda x: np.maximum(x, 0.0))
-    w = np.full(m, 1.0 / m)
-    z, t = w.copy(), 1.0
-    for _ in range(steps):
-        active = ok @ z
-        norm = np.where(active > 0, active / max(float(z.sum()), 1e-9), 1.0)
-        resid = (filled @ z) / norm - b
-        grad = (filled / norm[:, None]).T @ resid / n
-        w_next = project(z - lr * grad)
-        t_next = 0.5 * (1.0 + np.sqrt(1.0 + 4.0 * t * t))
-        z = w_next + ((t - 1.0) / t_next) * (w_next - w)
-        if not simplex:
-            z = np.maximum(z, 0.0)
-        w, t = w_next, t_next
-    return w
-
-
-def fit_consensus(cases, forecasts: np.ndarray, reference: int, valid_members: np.ndarray | None = None) -> dict:
-    """
-    Fit along- and cross-track weights per lead. ``forecasts``: ``(N, L, M, 2)`` lat/lon of every member.
-
-    Returns ``{"along": (L, M), "cross": (L, M), "reference": int}``.
-    """
-    disp = to_displacements(cases, forecasts)
-    truth = to_displacements(cases, np.stack([np.stack([c.truth["lat"], c.truth["lon"]], -1) for c in cases])[:, :, None])[:, :, 0]
-    unit = _reference_direction(disp, reference)
-    normal = np.stack([-unit[..., 1], unit[..., 0]], -1)
-    along = (disp * unit[:, :, None]).sum(-1)            # (N, L, M)
-    cross = (disp * normal[:, :, None]).sum(-1)
-    t_along = (truth * unit).sum(-1)
-    t_cross = (truth * normal).sum(-1)
-    leads, members = disp.shape[1], disp.shape[2]
-    wa, wc = np.zeros((leads, members)), np.zeros((leads, members))
-    for k in range(leads):
-        ok = np.isfinite(t_along[:, k]) & np.isfinite(along[:, k]).any(-1)
-        if valid_members is not None:
-            ok &= valid_members
-        if ok.sum() < 20:
-            wa[k] = wc[k] = 1.0 / members
-            continue
-        wa[k] = _fit_one(along[ok, k], t_along[ok, k], simplex=False)
-        wc[k] = _fit_one(cross[ok, k], t_cross[ok, k], simplex=True)
-    return {"along": wa, "cross": wc, "reference": int(reference)}
-
-
-def apply_consensus(cases, forecasts: np.ndarray, weights: dict, selective_k: float | None = None) -> np.ndarray:
-    """``(N, L, 2)`` lat/lon: the fitted blend of whichever members each case has."""
-    disp = to_displacements(cases, forecasts)
-    if selective_k is not None:
-        median = np.nanmedian(disp, axis=2, keepdims=True)
-        distance = np.linalg.norm(disp - median, axis=-1)
-        spread = np.nanmedian(distance, axis=2, keepdims=True)
-        drop = distance > selective_k * np.maximum(spread, 25.0)
-        disp = np.where(drop[..., None], np.nan, disp)
-    unit = _reference_direction(disp, weights["reference"])
-    normal = np.stack([-unit[..., 1], unit[..., 0]], -1)
-    along = (disp * unit[:, :, None]).sum(-1)
-    cross = (disp * normal[:, :, None]).sum(-1)
-    ok = np.isfinite(along)
-    wa = np.asarray(weights["along"])[None]
-    wc = np.asarray(weights["cross"])[None]
-    total_a = wa.sum(-1)
-    cover_a = (wa * ok).sum(-1)
-    cover_c = (wc * ok).sum(-1)
-    with np.errstate(invalid="ignore", divide="ignore"):
-        a = (np.where(ok, along, 0.0) * wa).sum(-1) * total_a / np.where(cover_a > 0, cover_a, np.nan)
-        c = (np.where(ok, cross, 0.0) * wc).sum(-1) / np.where(cover_c > 0, cover_c, np.nan)
-    blended = a[..., None] * unit + c[..., None] * normal
-    return from_displacements(cases, blended)
-
-
-def blend_with_model(case, track: np.ndarray, model_track: np.ndarray, spec: dict, leads, n_models: int = 1) -> np.ndarray:
-    """
-    The consensus pulled toward a dynamical model's own track of the storm (or several models' mean), by one weight
-    per lead (``spec["alpha"]``, fitted on past seasons: a fifth at 6 h, nine tenths by day 3, where the model knows
-    about the troughs and ridges the physics cannot see yet). With two or more models the mean deserves more
-    (``spec["alpha_multi"]``, fitted where two models existed: 0.78 at 24 h, 0.95 from 48 h; held-out gain 1-3%).
-
-    The model's track may first lose its starting offset (``spec["offset_tau_h"]``; None, as shipped: measured, it
-    made the blend worse). Where the model has lost the storm, the consensus stands.
-    """
-    hours = np.asarray(leads, np.float64)
-    weights = spec.get("alpha_multi") if n_models >= 2 and spec.get("alpha_multi") is not None else spec["alpha"]
-    alpha = np.interp(hours, spec.get("leads", hours), weights)
-    east, north = to_local(case.lat, case.lon, track[:, 0], track[:, 1])
-    me, mn = to_local(case.lat, case.lon, model_track[:, 0], model_track[:, 1])
-    tau = spec.get("offset_tau_h")
-    if tau:
-        f = hours[0] / max(hours[1] - hours[0], 1e-9)
-        p0e, p0n = me[0] - (me[1] - me[0]) * f, mn[0] - (mn[1] - mn[0]) * f
-        decay = np.exp(-hours / float(tau))
-        me, mn = me - p0e * decay, mn - p0n * decay
-    model_ok = np.isfinite(me) & np.isfinite(mn)
-    e = np.where(model_ok, (1 - alpha) * east + alpha * me, east)
-    n = np.where(model_ok, (1 - alpha) * north + alpha * mn, north)
-    lat, lon = from_local(case.lat, case.lon, e, n)
-    out = np.stack([lat, lon], -1)
-    out[~np.isfinite(track).all(-1)] = np.nan
-    return out
-
-
-
-def apply_track_feedback(case, track, previous_track, previous_time, leads, table: dict | None = None, previous_position=None):
-    """
-    Error feedback from the storm's own previous cycle (``coefficients.TRACK_FEEDBACK``): the previous forecast's
-    position for the time now being analysed, minus the analysis, is an error known at analysis time; a fitted share
-    of it per lead is subtracted from the new track at leads up to ``max_lead_h``. Model track errors persist from
-    cycle to cycle (a ridge too strong is still too strong six hours later); fitted on the HRES blends of the tuning
-    seasons, worth about 1% on the held-out multi-model blend at 12-36 h -- small, and nothing beyond 48 h, which
-    is why it stops there.
-
-    Args:
-        track: the new blended track ``(L, 2)``.
-        previous_track: the previous cycle's blended track ``(L, 2)`` at the same ``leads``.
-        previous_time: the previous cycle's analysis time (numpy datetime64 or ISO string).
-        previous_position: that cycle's analysis ``(lat, lon)``, so a gap shorter than the first lead interpolates
-            from the right place.
-    Returns the corrected track; the input unchanged when the previous cycle is not usable.
-    """
-    if table is None:
-        from . import coefficients
-
-        table = getattr(coefficients, "TRACK_FEEDBACK", None)
-    if not table or previous_track is None or previous_time is None:
-        return track
-    gap_h = float((np.datetime64(case.time, "m") - np.datetime64(previous_time, "m")) / np.timedelta64(60, "m"))
-    leads = np.asarray(leads, np.float64)
-    prev = np.asarray(previous_track, np.float64)
-    if gap_h <= 0 or gap_h > 48 or not np.isfinite(prev[:, 0]).any():
-        return track
-    fin = np.isfinite(prev[:, 0])
-    knots, plat, plon = leads[fin], prev[fin, 0], prev[fin, 1]
-    if previous_position is not None and np.all(np.isfinite(previous_position)):       # the previous analysis: lead 0
-        knots, plat, plon = np.r_[0.0, knots], np.r_[previous_position[0], plat], np.r_[previous_position[1], plon]
-    pl = np.interp(gap_h, knots, plat)
-    po = np.degrees(np.interp(gap_h, knots, np.unwrap(np.radians(plon))))
-    e_prev, n_prev = geometry.local_displacement_km(case.lat, case.lon, pl, po)              # the previous error, km
-    keys = sorted(table["beta"], key=lambda k: abs(float(k) - gap_h))
-    beta = np.interp(leads, table["leads"], table["beta"][keys[0]])
-    beta = np.where(leads <= table.get("max_lead_h", 48), beta, 0.0)
-    if gap_h < 9:                                                                                  # a 6 h gap: the 12 h share, scaled
-        beta = beta * gap_h / 12.0
-    out = np.asarray(track, np.float64).copy()
-    ok = np.isfinite(out[:, 0])
-    e, n = geometry.local_displacement_km(case.lat, case.lon, out[ok, 0], out[ok, 1])
-    lat, lon = geometry.move(case.lat, case.lon, e - beta[ok] * e_prev, n - beta[ok] * n_prev)
-    out[ok, 0], out[ok, 1] = lat, lon
-    return out
-
-__all__ = ["apply_track_feedback", "apply_consensus", "blend_with_model", "fit_consensus", "from_displacements", "project_simplex",
-           "to_displacements"]

naturev1/cyclone/data.py

@@ -1,361 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Hindcast cases: every best-track fix that a forecast centre would have issued a forecast from, with the
-analysis around the storm at that moment and what the storm actually did afterwards.
-
-The idea: a track model is judged the way the National Hurricane Center judges its own -- homogeneous
-samples, forecasts only from tropical or subtropical cyclones (depressions included), verified only while
-the system is still one, at fixed leads -- on thousands of cases across every basin, never on a single
-storm. Each case stores only what was knowable at issue time (the best track up to now and the analysis
-now and 12 hours ago), so nothing downstream can peek at the future; the verifying positions are kept
-apart, in ``truth``.
-
-Analysis boxes come from WeatherBench 2's 1.5-degree ERA5 (the grid NatureV1 runs on). Reading is
-chunk-aware -- the store keeps 8 times per chunk, so cases are processed in time order and every chunk is
-read once for all the storms active in it -- and threaded. Boxes are stored as float16 after a per-case,
-per-channel standardisation (geopotential would overflow float16 otherwise), in one memory-mapped array per
-season, resumable season by season.
-"""
-
-from __future__ import annotations
-
-import concurrent.futures as cf
-import json
-from collections import OrderedDict
-from dataclasses import dataclass, field
-from pathlib import Path
-
-import numpy as np
-
-from .fields import Environment
-
-WB2_ERA5 = "gs://weatherbench2/datasets/era5/1959-2023_01_10-6h-240x121_equiangular_with_poles_conservative.zarr"
-LEVELS = (50, 100, 150, 200, 250, 300, 400, 500, 600, 700, 850, 925, 1000)
-PREVIOUS_LEVELS = (200, 250, 300, 400, 500, 600, 700, 850)
-LEVEL_VARIABLES = {"u": "u_component_of_wind", "v": "v_component_of_wind", "z": "geopotential",
-                   "t": "temperature", "q": "specific_humidity"}
-SURFACE_VARIABLES = {"msl": "mean_sea_level_pressure", "sst": "sea_surface_temperature",
-                     "tcwv": "total_column_water_vapour", "u10": "10m_u_component_of_wind",
-                     "v10": "10m_v_component_of_wind"}
-STATIC_VARIABLES = {"lsm": "land_sea_mask", "zs": "geopotential_at_surface"}
-#: Leads verified, hours.
-LEADS = (6, 12, 24, 36, 48, 72, 96, 120)
-#: Box half-widths, degrees, and the grid step.
-HALF_LAT, HALF_LON, STEP = 30.0, 45.0, 1.5
-TROPICAL = ("TD", "TS", "HU", "SS")
-HISTORY_HOURS = (-48, -42, -36, -30, -24, -18, -12, -6, 0)
-
-
-def channel_names() -> list[str]:
-    names = [f"{k}@{p}" for k in LEVEL_VARIABLES for p in LEVELS]
-    names += list(SURFACE_VARIABLES) + list(STATIC_VARIABLES)
-    names += [f"prev_{k}@{p}" for k in ("u", "v") for p in PREVIOUS_LEVELS] + ["prev_z@500", "prev_msl"]
-    return names
-
-
-@dataclass
-class Case:
-    """One forecast opportunity. Everything outside ``truth`` was known at ``time``."""
-
-    storm_id: str
-    name: str
-    basin: str
-    time: np.datetime64
-    lat: float
-    lon: float
-    wind_kt: float
-    pressure_hpa: float
-    status: str
-    history: dict = field(default_factory=dict)      # HISTORY_HOURS -> lat, lon, wind, pressure (NaN where absent)
-    rmw_nmi: float = float("nan")
-    r34_nmi: float = float("nan")                     # mean of the reported quadrants
-    distance_to_land_km: float = float("nan")
-    truth: dict = field(default_factory=dict)         # LEADS -> lat, lon, wind, pressure, valid
-    index: int = -1                                   # row in the season's box array
-
-    @property
-    def year(self) -> int:
-        return int(str(self.time)[:4])
-
-    @property
-    def key(self) -> str:
-        return f"{self.storm_id}@{str(self.time)[:13]}"
-
-
-def _fix_lookup(track) -> dict[int, int]:
-    seconds = track.time.astype("datetime64[s]").astype(np.int64)
-    return {int(s): k for k, s in enumerate(seconds)}
-
-
-def cases_from_tracks(tracks, years, init_hours=(0, 12), leads=LEADS) -> list[Case]:
-    """
-    Every fix at ``init_hours`` UTC in ``years`` (calendar year of the fix) where the system is a tropical or
-    subtropical cyclone and at least one earlier fix 6 or 12 hours back exists (so extrapolation is defined).
-    """
-    years = set(int(y) for y in years)
-    out = []
-    for track in tracks:
-        lookup = _fix_lookup(track)
-        seconds = track.time.astype("datetime64[s]").astype(np.int64)
-        for k in range(len(track)):
-            t = int(seconds[k])
-            if (t // 3600) % 24 not in init_hours or track.status[k] not in TROPICAL:
-                continue
-            if int(str(track.time[k])[:4]) not in years:
-                continue
-            if not (np.isfinite(track.latitude[k]) and np.isfinite(track.longitude[k])):
-                continue
-            if lookup.get(t - 6 * 3600) is None and lookup.get(t - 12 * 3600) is None:
-                continue
-            history = {"lat": [], "lon": [], "wind": [], "pressure": []}
-            for h in HISTORY_HOURS:
-                j = lookup.get(t + h * 3600)
-                for key, arr in (("lat", track.latitude), ("lon", track.longitude), ("wind", track.max_wind_kt),
-                                 ("pressure", track.min_pressure_hpa)):
-                    history[key].append(float(arr[j]) if j is not None else float("nan"))
-            truth = {"lat": [], "lon": [], "wind": [], "pressure": [], "valid": []}
-            for lead in leads:
-                j = lookup.get(t + lead * 3600)
-                ok = j is not None and track.status[j] in TROPICAL and np.isfinite(track.latitude[j])
-                for key, arr in (("lat", track.latitude), ("lon", track.longitude), ("wind", track.max_wind_kt),
-                                 ("pressure", track.min_pressure_hpa)):
-                    truth[key].append(float(arr[j]) if ok else float("nan"))
-                truth["valid"].append(bool(ok))
-            radii = track.wind_radii_nmi[k, 0]
-            out.append(Case(
-                storm_id=track.storm_id, name=track.name, basin=track.basin, time=track.time[k].astype("datetime64[s]"),
-                lat=float(track.latitude[k]), lon=float(track.longitude[k]), wind_kt=float(track.max_wind_kt[k]),
-                pressure_hpa=float(track.min_pressure_hpa[k]), status=str(track.status[k]),
-                history={key: np.asarray(v, np.float64) for key, v in history.items()},
-                rmw_nmi=float(track.rmw_nmi[k]), r34_nmi=float(np.nanmean(radii)) if np.isfinite(radii).any() else float("nan"),
-                distance_to_land_km=float(track.distance_to_land_km[k]) if track.distance_to_land_km is not None else float("nan"),
-                truth={key: np.asarray(v, np.float64 if key != "valid" else bool) for key, v in truth.items()},
-            ))
-    out.sort(key=lambda c: (c.time, c.storm_id))
-    return out
-
-
-# ------------------------------------------------------------------------------------- serialise --
-
-_SCALARS = ("storm_id", "name", "basin", "lat", "lon", "wind_kt", "pressure_hpa", "status", "rmw_nmi", "r34_nmi",
-            "distance_to_land_km", "index")
-
-
-def save_cases(cases: list[Case], path: str | Path) -> None:
-    payload = {key: np.asarray([getattr(c, key) for c in cases]) for key in _SCALARS}
-    payload["time"] = np.asarray([c.time for c in cases], dtype="datetime64[s]").astype(np.int64)
-    for key in ("lat", "lon", "wind", "pressure"):
-        payload[f"history_{key}"] = np.stack([c.history[key] for c in cases]) if cases else np.zeros((0, 9))
-    for key in ("lat", "lon", "wind", "pressure", "valid"):
-        payload[f"truth_{key}"] = np.stack([c.truth[key] for c in cases]) if cases else np.zeros((0, len(LEADS)))
-    np.savez(path, **payload)
-
-
-def load_cases(path: str | Path) -> list[Case]:
-    data = np.load(path, allow_pickle=False)
-    out = []
-    for i in range(len(data["time"])):
-        out.append(Case(
-            storm_id=str(data["storm_id"][i]), name=str(data["name"][i]), basin=str(data["basin"][i]),
-            time=np.datetime64(int(data["time"][i]), "s"), lat=float(data["lat"][i]), lon=float(data["lon"][i]),
-            wind_kt=float(data["wind_kt"][i]), pressure_hpa=float(data["pressure_hpa"][i]), status=str(data["status"][i]),
-            history={key: data[f"history_{key}"][i] for key in ("lat", "lon", "wind", "pressure")},
-            rmw_nmi=float(data["rmw_nmi"][i]), r34_nmi=float(data["r34_nmi"][i]),
-            distance_to_land_km=float(data["distance_to_land_km"][i]),
-            truth={key: data[f"truth_{key}"][i] for key in ("lat", "lon", "wind", "pressure", "valid")},
-            index=int(data["index"][i]),
-        ))
-    return out
-
-
-# --------------------------------------------------------------------------------------- reading --
-
-class WB2Reader:
-    """
-    Chunk-cached, threaded reads of WeatherBench 2 ERA5. ``fields(t)`` returns every variable at time ``t`` as
-    ``(level, lat, lon)`` / ``(lat, lon)`` arrays (latitude ascending, longitude 0..358.5).
-    """
-
-    def __init__(self, store: str = WB2_ERA5, threads: int = 8, cache_chunks: int = 3) -> None:
-        import xarray as xr
-
-        self.ds = xr.open_zarr(store, storage_options={"token": "anon"}, chunks=None)
-        self.t0 = np.datetime64(self.ds.time.values[0], "s").astype(np.int64)
-        self.step = int((np.datetime64(self.ds.time.values[1], "s") - np.datetime64(self.ds.time.values[0], "s"))
-                        / np.timedelta64(1, "s"))
-        self.chunk = int(self.ds["u_component_of_wind"].encoding.get("chunks", (8,))[0])
-        self.levels = tuple(int(p) for p in self.ds.level.values)
-        self.lat = self.ds.latitude.values.astype(np.float64)
-        self.lon = self.ds.longitude.values.astype(np.float64)
-        self.pool = cf.ThreadPoolExecutor(threads)
-        self.cache: OrderedDict[int, dict] = OrderedDict()
-        self.cache_chunks = cache_chunks
-        self.static = {k: self._orient(np.asarray(self.ds[v].values, np.float32)) for k, v in STATIC_VARIABLES.items()}
-
-    def _orient(self, array: np.ndarray) -> np.ndarray:
-        """(..., lon, lat) -> (..., lat, lon), latitude ascending."""
-        array = np.swapaxes(array, -1, -2)
-        if self.lat[0] > self.lat[-1]:
-            array = array[..., ::-1, :]
-        return array
-
-    def _load_chunk(self, number: int) -> dict:
-        start, stop = number * self.chunk, (number + 1) * self.chunk
-
-        def read(item):
-            key, name = item
-            return key, self._orient(np.asarray(self.ds[name].isel(time=slice(start, stop)).values, np.float32))
-
-        items = list(LEVEL_VARIABLES.items()) + list(SURFACE_VARIABLES.items())
-        return dict(self.pool.map(read, items))
-
-    def fields(self, when: np.datetime64) -> dict:
-        index = int((np.datetime64(when, "s").astype(np.int64) - self.t0) // self.step)
-        number, offset = divmod(index, self.chunk)
-        if number not in self.cache:
-            self.cache[number] = self._load_chunk(number)
-            while len(self.cache) > self.cache_chunks:
-                self.cache.popitem(last=False)
-        self.cache.move_to_end(number)
-        chunk = self.cache[number]
-        out = {key: value[offset] for key, value in chunk.items()}
-        out.update(self.static)
-        return out
-
-
-def _box_indices(lat0: float, lon0: float, lat_axis: np.ndarray, lon_step: float, rows: int, cols: int):
-    """Row range (kept inside the globe) and wrapped column indices with continuous box longitudes."""
-    step = lat_axis[1] - lat_axis[0]
-    centre = int(round((lat0 - lat_axis[0]) / step))
-    start = int(np.clip(centre - rows // 2, 0, lat_axis.size - rows))
-    j0 = int(round((lon0 % 360.0) / lon_step))
-    offsets = np.arange(cols) - cols // 2
-    columns = (j0 + offsets) % int(round(360.0 / lon_step))
-    box_lon = (j0 + offsets) * lon_step
-    if box_lon[cols // 2] - lon0 > 180.0:
-        box_lon = box_lon - 360.0
-    return slice(start, start + rows), columns, lat_axis[start:start + rows], box_lon
-
-
-def build_box(now: dict, before: dict | None, lat0: float, lon0: float, lat_axis: np.ndarray, levels) -> tuple:
-    """``(boxes (C, H, W) float32, lat (H,), lon (W,))`` for one case, channels in :func:`channel_names` order."""
-    rows, cols = int(round(2 * HALF_LAT / STEP)) + 1, int(round(2 * HALF_LON / STEP)) + 1
-    rs, cs, box_lat, box_lon = _box_indices(lat0, lon0, lat_axis, STEP, rows, cols)
-    order = [list(levels).index(p) for p in LEVELS]
-    planes = []
-    for key in LEVEL_VARIABLES:
-        planes.extend(now[key][order][:, rs][:, :, cs])
-    for key in list(SURFACE_VARIABLES) + list(STATIC_VARIABLES):
-        planes.append(now[key][rs][:, cs])
-    previous_order = [list(levels).index(p) for p in PREVIOUS_LEVELS]
-    source = before if before is not None else now
-    for key in ("u", "v"):
-        planes.extend(source[key][previous_order][:, rs][:, :, cs])
-    planes.append(source["z"][list(levels).index(500)][rs][:, cs])
-    planes.append(source["msl"][rs][:, cs])
-    return np.stack(planes).astype(np.float32), box_lat, box_lon
-
-
-def _standardise(box: np.ndarray):
-    mean = np.nanmean(box, axis=(1, 2))
-    std = np.nanstd(box, axis=(1, 2))
-    mean = np.where(np.isfinite(mean), mean, 0.0)
-    std = np.where(np.isfinite(std) & (std > 0), std, 1.0)
-    scaled = (box - mean[:, None, None]) / std[:, None, None]
-    return scaled.astype(np.float16), np.stack([mean, std], -1).astype(np.float32)
-
-
-def build_season(cases: list[Case], directory: str | Path, reader: WB2Reader | None = None, log=print) -> Path:
-    """
-    Read the analysis box for every case (in time order, one chunk read for all storms in it) into
-    ``directory``: ``cases.npz``, ``boxes.npy`` (N, C, H, W) float16, ``affine.npy`` (N, C, 2), ``grid.npz``
-    (per-case box latitude and longitude), ``channels.json``. Resumable: a finished directory is left alone.
-    """
-    directory = Path(directory)
-    directory.mkdir(parents=True, exist_ok=True)
-    if (directory / "done").exists():
-        return directory
-    reader = reader or WB2Reader()
-    names = channel_names()
-    rows, cols = int(round(2 * HALF_LAT / STEP)) + 1, int(round(2 * HALF_LON / STEP)) + 1
-    boxes = np.lib.format.open_memmap(directory / "boxes.npy", mode="w+", dtype=np.float16,
-                                      shape=(len(cases), len(names), rows, cols))
-    affine = np.zeros((len(cases), len(names), 2), np.float32)
-    grid_lat = np.zeros((len(cases), rows), np.float32)
-    grid_lon = np.zeros((len(cases), cols), np.float32)
-    for i, case in enumerate(cases):
-        now = reader.fields(case.time)
-        before = reader.fields(case.time - np.timedelta64(12, "h"))
-        box, lat, lon = build_box(now, before, case.lat, case.lon, reader.lat, reader.levels)
-        boxes[i], affine[i] = _standardise(box)
-        grid_lat[i], grid_lon[i] = lat, lon
-        case.index = i
-        if log and (i % 200 == 0 or i == len(cases) - 1):
-            log(f"[cyclone-data] {directory.name}: {i + 1}/{len(cases)} {case.key}")
-    boxes.flush()
-    np.save(directory / "affine.npy", affine)
-    np.savez(directory / "grid.npz", lat=grid_lat, lon=grid_lon)
-    (directory / "channels.json").write_text(json.dumps(names))
-    save_cases(cases, directory / "cases.npz")
-    (directory / "done").write_text("ok")
-    return directory
-
-
-class Season:
-    """A built season: its cases and, on demand, each case's :class:`Environment`."""
-
-    def __init__(self, directory: str | Path) -> None:
-        self.directory = Path(directory)
-        self.cases = load_cases(self.directory / "cases.npz")
-        self.boxes = np.load(self.directory / "boxes.npy", mmap_mode="r")
-        self.affine = np.load(self.directory / "affine.npy")
-        grid = np.load(self.directory / "grid.npz")
-        self.grid_lat, self.grid_lon = grid["lat"], grid["lon"]
-        self.names = json.loads((self.directory / "channels.json").read_text())
-        self.slot = {n: k for k, n in enumerate(self.names)}
-
-    def __len__(self) -> int:
-        return len(self.cases)
-
-    def environment(self, i: int) -> Environment:
-        case = self.cases[i]
-        box = self.boxes[case.index].astype(np.float32)
-        a = self.affine[case.index]
-        box = box * a[:, 1, None, None] + a[:, 0, None, None]
-        take = lambda name: box[self.slot[name]].astype(np.float64)
-        fields = {k: np.stack([take(f"{k}@{p}") for p in LEVELS]) for k in LEVEL_VARIABLES}
-        for k in list(SURFACE_VARIABLES) + list(STATIC_VARIABLES):
-            fields[k] = take(k)
-        previous = {k: np.stack([take(f"prev_{k}@{p}") for p in PREVIOUS_LEVELS]) for k in ("u", "v")}
-        previous["z500"] = take("prev_z@500")
-        previous["msl"] = take("prev_msl")
-        env = Environment(lat=self.grid_lat[case.index].astype(np.float64), lon=self.grid_lon[case.index].astype(np.float64),
-                          levels=LEVELS, fields=fields, previous=previous, time=case.time)
-        env.previous_levels = PREVIOUS_LEVELS
-        return env
-
-
-def build_seasons(ibtracs_paths: dict[str, str], root: str | Path, years, basins=("NA", "EP", "WP", "SI", "SP"),
-                  log=print) -> dict[int, Path]:
-    """Build (or reuse) one :func:`build_season` directory per calendar year, all basins together."""
-    from ..ibtracs import parse_ibtracs
-
-    years = sorted(int(y) for y in years)
-    tracks = []
-    for basin in basins:
-        tracks += parse_ibtracs(ibtracs_paths[basin], since=years[0] - 1, until=years[-1] + 1, basins=(basin,))
-    reader = None
-    out = {}
-    for year in years:
-        directory = Path(root) / str(year)
-        if not (directory / "done").exists():
-            reader = reader or WB2Reader()
-            cases = cases_from_tracks(tracks, [year])
-            log(f"[cyclone-data] {year}: {len(cases)} cases")
-            build_season(cases, directory, reader, log)
-        out[year] = directory
-    return out
-
-
-__all__ = ["Case", "HISTORY_HOURS", "LEADS", "LEVELS", "Season", "WB2Reader", "build_box", "build_season",
-           "build_seasons", "cases_from_tracks", "channel_names", "load_cases", "save_cases"]

naturev1/cyclone/ensemble.py

@@ -1,136 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-An ensemble that knows where the analysis is uncertain -- the Bermuda High problem.
-
-The idea: Dorian's turn depended on the exact strength and edge of the Bermuda High, which sits over open ocean
-where no radiosondes are launched; models had to infer it from satellite retrievals. A single physics forecast
-from that analysis inherits whatever error it holds there. An ensemble spreads the forecast over the
-analysis's plausible errors -- and the ensemble *mean* is, on average, more accurate than any one member,
-because it averages out the unpredictable part. Each member:
-
-* adds a smooth, non-divergent perturbation to the steering flow: a few Gaussian streamfunction blobs
-  (600-1100 km scale) scattered within 2,500 km of the storm, with amplitudes scaled to the climatological
-  day-to-day variability of the 500 hPa wind at each blob (big where the weather is variable, small in the
-  steady trades), **inflated over open ocean far from land** (the data voids where the analysis is least
-  constrained), and growing with lead time as forecast errors do;
-* draws its own steering layer (from the family in :data:`naturev1.cyclone.steering.LAYERS`), its own beta
-  drift strength and its own memory of the initial-motion residual -- the structural uncertainty of the
-  physics, not just of the initial state.
-
-Perturbation winds are evaluated analytically at the members' positions (derivatives of Gaussians), so the
-whole ensemble integrates as one vectorised trajectory.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .geometry import destination, great_circle_km, to_local
-
-MEMBERS = 24
-BLOBS = 6
-#: Perturbation wind as a fraction of the climatological 500 hPa variability, and the open-ocean inflation.
-AMPLITUDE = 0.3
-OCEAN_INFLATION = 1.35
-#: Error growth: the perturbation's size doubles after this many hours.
-DOUBLING_H = 60.0
-
-
-class FlowPerturbations:
-    """``(M, K)`` Gaussian streamfunction blobs; ``velocity(member_lat, member_lon, hours)`` -> ``(M,)`` (u, v)."""
-
-    def __init__(self, lat0: float, lon0: float, env, climate=None, members: int = MEMBERS, blobs: int = BLOBS,
-                 amplitude: float = AMPLITUDE, seed: int = 0) -> None:
-        rng = np.random.default_rng(seed)
-        distance = 2500.0 * np.sqrt(rng.uniform(0.0, 1.0, (members, blobs)))
-        bearing = rng.uniform(0.0, 360.0, (members, blobs))
-        self.lat, self.lon = destination(lat0, lon0, bearing, distance)
-        self.scale_km = rng.uniform(600.0, 1100.0, (members, blobs))
-        sigma = np.full((members, blobs), 3.0)
-        if climate is not None and "ustd500" in climate.fields:
-            std = np.hypot(climate.sample(climate.fields["ustd500"], self.lat, self.lon),
-                           climate.sample(climate.fields["vstd500"], self.lat, self.lon)) / np.sqrt(2.0)
-            sigma = np.where(np.isfinite(std), std, 3.0)
-        land = env.sample(env.fields["lsm"], self.lat, self.lon) if "lsm" in env.fields else np.zeros_like(sigma)
-        sigma = sigma * np.where(land < 0.2, OCEAN_INFLATION, 1.0)
-        # Peak wind of a Gaussian streamfunction blob is psi0 / (L sqrt(e)); choose psi0 for a peak of amplitude*sigma.
-        wind = amplitude * sigma * rng.choice([-1.0, 1.0], (members, blobs))
-        self.psi0 = wind * self.scale_km * 1000.0 * np.sqrt(np.e)
-
-    def velocity(self, lat, lon, hours):
-        lat = np.atleast_1d(lat)
-        lon = np.atleast_1d(lon)
-        x, y = to_local(self.lat, self.lon, lat[:, None], lon[:, None])          # member position relative to blobs
-        x, y = x * 1000.0, y * 1000.0
-        l2 = (self.scale_km * 1000.0) ** 2
-        g = self.psi0 * np.exp(-0.5 * (x * x + y * y) / l2)
-        u = (g * y / l2).sum(1)                                                   # u = -dpsi/dy
-        v = (-g * x / l2).sum(1)                                                  # v =  dpsi/dx
-        growth = 2.0 ** (np.asarray(hours, np.float64) / DOUBLING_H)
-        return u * growth, v * growth
-
-
-def ensemble_mean(tracks: np.ndarray) -> np.ndarray:
-    """``(M, L, 2)`` -> ``(L, 2)``: the mean position of the members alive at each lead (local-frame average)."""
-    from .geometry import from_local
-
-    out = np.full(tracks.shape[1:], np.nan)
-    for k in range(tracks.shape[1]):
-        ok = np.isfinite(tracks[:, k, 0])
-        if not ok.any():
-            continue
-        ref = tracks[ok, k][0]
-        x, y = to_local(ref[0], ref[1], tracks[ok, k, 0], tracks[ok, k, 1])
-        out[k] = np.stack(from_local(ref[0], ref[1], x.mean(), y.mean()), -1)
-    return out
-
-
-def ensemble_spread_km(tracks: np.ndarray, mean: np.ndarray) -> np.ndarray:
-    """``(L,)`` mean distance of the members from the ensemble mean."""
-    return np.nanmean(great_circle_km(tracks[..., 0], tracks[..., 1], mean[None, :, 0], mean[None, :, 1]), axis=0)
-
-
-def physics_ensemble(case, env_clean, flows: dict, beta, motion_ms, leads, climate=None, climate_flows=None,
-                     members: int = MEMBERS, seed: int = 0, tau_range=(12.0, 48.0), beta_range=(0.6, 1.4),
-                     anomaly_tau_h: float = 72.0) -> dict:
-    """
-    Run the ensemble. ``flows``: ``{layer name: SteeringFlow}`` of the vortex-removed analysis (members pick one
-    each); ``climate_flows`` the matching climatological flows (then each member's steering anomaly decays with
-    ``anomaly_tau_h``). Returns ``{"members": (M, L, 2), "mean": (L, 2), "spread_km": (L,)}``.
-    """
-    from .trajectory import integrate
-
-    rng = np.random.default_rng(seed + 7919)
-    names = list(flows)
-    choice = rng.integers(0, len(names), members)
-    tau = rng.uniform(*tau_range, members)
-    beta_scale = rng.uniform(*beta_range, members)
-    perturb = FlowPerturbations(case.lat, case.lon, env_clean, climate, members, seed=seed)
-    start = {n: tuple(float(a[0]) for a in flows[n].velocity(case.lat, case.lon)) for n in names}
-    b0 = tuple(float(a[0]) for a in beta.velocity(case.lat, case.lon))
-    residual = np.array([[motion_ms[0] - start[names[c]][0] - beta_scale[m] * b0[0],
-                          motion_ms[1] - start[names[c]][1] - beta_scale[m] * b0[1]] for m, c in enumerate(choice)])
-
-    def velocity(lat, lon, hours):
-        u = np.zeros(members)
-        v = np.zeros(members)
-        for k, name in enumerate(names):
-            sel = choice == k
-            if sel.any():
-                us, vs = flows[name].velocity(lat[sel], lon[sel])
-                if climate_flows is not None and name in climate_flows:
-                    uc, vc = climate_flows[name].velocity(lat[sel], lon[sel])
-                    memory = np.exp(-hours / anomaly_tau_h)
-                    us, vs = uc + memory * (us - uc), vc + memory * (vs - vc)
-                u[sel], v[sel] = us, vs
-        bu, bv = beta.velocity(lat, lon)
-        pu, pv = perturb.velocity(lat, lon, hours)
-        decay = np.exp(-hours / tau)
-        return (u + beta_scale * bu + pu + residual[:, 0] * decay, v + beta_scale * bv + pv + residual[:, 1] * decay)
-
-    tracks = integrate(np.full(members, case.lat), np.full(members, case.lon), velocity, leads)
-    mean = ensemble_mean(tracks)
-    return {"members": tracks, "mean": mean, "spread_km": ensemble_spread_km(tracks, mean)}
-
-
-__all__ = ["AMPLITUDE", "FlowPerturbations", "MEMBERS", "ensemble_mean", "ensemble_spread_km", "physics_ensemble"]

naturev1/cyclone/field_tracker.py

@@ -1,127 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Following a storm through a gridded forecast: a GFDL-style tracker for any model's output.
-
-The idea: comparing NatureV1's physics with GraphCast, Pangu, HRES, Aurora or FGN on hurricanes needs their
-tracks, and none of them outputs a track -- they output fields. The tracker used by operational centres
-(Marchok's GFDL vortex tracker) finds the storm in each forecast step from several fields and averages the
-fixes; this one does the same with what every model in WeatherBench 2 provides:
-
-* **sea-level pressure minimum** (every model has it), refined below the grid spacing by fitting a quadratic
-  surface to the 3x3 neighbourhood of the lowest grid value -- at 1.5 degrees the refinement matters (a grid
-  point can be 80 km from the true minimum);
-* **850 hPa relative vorticity maximum** (cyclonic sign per hemisphere) and **850/700 hPa geopotential
-  minima** when the model provides those fields;
-* each step searches only within a radius of the position the previous motion predicts (first guess
-  = previous position + previous displacement), so a nearby low is not grabbed;
-* the fix is the mean of the parameter fixes that agree (within 250 km of their median);
-* the track stops when the storm is lost: no closed low (the minimum is not at least ``depth_hpa`` below the
-  mean pressure on a ring 300-500 km out) or the fixes disagree.
-
-Works on any ``(time, lat, lon)`` field arrays on a regular grid (latitude ascending, longitude 0..360).
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .geometry import great_circle_km, move, local_displacement_km
-
-
-def _refine(field: np.ndarray, i: int, j: int) -> tuple[float, float]:
-    """Sub-grid offset (di, dj) of an extremum from a quadratic fit to its 3x3 neighbourhood (wrapped in j)."""
-    h, w = field.shape
-    if i <= 0 or i >= h - 1:
-        return 0.0, 0.0
-    c = field[i, j]
-    n, s = field[i + 1, j], field[i - 1, j]
-    e, wv = field[i, (j + 1) % w], field[i, (j - 1) % w]
-    di = 0.5 * (s - n) / (s - 2 * c + n) if (s - 2 * c + n) != 0 else 0.0
-    dj = 0.5 * (wv - e) / (wv - 2 * c + e) if (wv - 2 * c + e) != 0 else 0.0
-    return float(np.clip(di, -0.5, 0.5)), float(np.clip(dj, -0.5, 0.5))
-
-
-def find_extremum(field: np.ndarray, lat_axis: np.ndarray, lon_axis: np.ndarray, guess: tuple[float, float],
-                  radius_km: float, minimum: bool = True) -> tuple[float, float, float] | None:
-    """``(lat, lon, value)`` of the field's extremum within ``radius_km`` of ``guess``, sub-grid refined."""
-    lat_g, lon_g = np.meshgrid(lat_axis, lon_axis, indexing="ij")
-    d = great_circle_km(guess[0], guess[1], lat_g, lon_g)
-    inside = d < radius_km
-    if not inside.any():
-        return None
-    data = field if minimum else -field
-    masked = np.where(inside, data, np.inf)
-    i, j = np.unravel_index(int(np.argmin(masked)), masked.shape)
-    di, dj = _refine(data, i, j)
-    step_lat = lat_axis[1] - lat_axis[0]
-    step_lon = lon_axis[1] - lon_axis[0]
-    lat = float(lat_axis[i] + di * step_lat)
-    lon = float(((lon_axis[j] + dj * step_lon + 180.0) % 360.0) - 180.0)
-    return lat, lon, float(field[i, j])
-
-
-def closed_low_depth(msl: np.ndarray, lat_axis, lon_axis, lat: float, lon: float, centre_value: float,
-                     ring=(300.0, 500.0)) -> float:
-    """Ring-mean pressure minus the centre value (Pa) -- how closed the low is."""
-    lat_g, lon_g = np.meshgrid(lat_axis, lon_axis, indexing="ij")
-    d = great_circle_km(lat, lon, lat_g, lon_g)
-    band = (d >= ring[0]) & (d <= ring[1])
-    return float(msl[band].mean() - centre_value) if band.any() else 0.0
-
-
-def track_in_fields(start: tuple[float, float], hours, msl: np.ndarray, lat_axis, lon_axis,
-                    vorticity850: np.ndarray | None = None, z850: np.ndarray | None = None,
-                    z700: np.ndarray | None = None, first_motion_kmh: tuple[float, float] | None = None,
-                    search_km: float = 350.0, depth_pa: float = 100.0, agree_km: float = 250.0) -> np.ndarray:
-    """
-    Track a storm from ``start`` through forecast fields at ``hours`` (``msl`` is ``(T, H, W)`` Pa).
-
-    Returns ``(T, 2)`` lat/lon, NaN after the storm is lost. ``first_motion_kmh`` (east, north) seeds the first
-    guess; later guesses extrapolate the tracked motion.
-    """
-    hours = np.asarray(hours, np.float64)
-    out = np.full((len(hours), 2), np.nan)
-    position = (float(start[0]), float(start[1]))
-    motion = first_motion_kmh or (0.0, 0.0)
-    last_hours = 0.0
-    hemisphere = 1.0 if start[0] >= 0 else -1.0
-    for k, h in enumerate(hours):
-        if not np.isfinite(msl[k]).any():
-            continue                                         # a lead this model does not provide (12-hourly output)
-        dt = h - last_hours
-        guess = move(position[0], position[1], motion[0] * dt, motion[1] * dt) if dt > 0 else position
-        guess = (float(guess[0]), float(guess[1]))
-        fixes = []
-        found = find_extremum(msl[k], lat_axis, lon_axis, guess, search_km, minimum=True)
-        if found is None:
-            break
-        depth = closed_low_depth(msl[k], lat_axis, lon_axis, found[0], found[1], found[2])
-        if depth < depth_pa:
-            break
-        fixes.append(found[:2])
-        if vorticity850 is not None:
-            f = find_extremum(hemisphere * vorticity850[k], lat_axis, lon_axis, guess, search_km, minimum=False)
-            if f is not None:
-                fixes.append(f[:2])
-        for z in (z850, z700):
-            if z is not None:
-                f = find_extremum(z[k], lat_axis, lon_axis, guess, search_km, minimum=True)
-                if f is not None:
-                    fixes.append(f[:2])
-        fixes = np.asarray(fixes)
-        median = np.median(fixes, axis=0)
-        near = great_circle_km(median[0], median[1], fixes[:, 0], fixes[:, 1]) < agree_km
-        use = fixes[near] if near.any() else fixes[:1]
-        # Average positions in the local frame of the pressure fix (safe across the dateline).
-        east, north = local_displacement_km(fixes[0, 0], fixes[0, 1], use[:, 0], use[:, 1])
-        lat, lon = move(fixes[0, 0], fixes[0, 1], east.mean(), north.mean())
-        new = (float(lat), float(lon))
-        if dt > 0:
-            e, n = local_displacement_km(position[0], position[1], new[0], new[1])
-            motion = (float(e) / dt, float(n) / dt)
-        position, last_hours = new, h
-        out[k] = new
-    return out
-
-
-__all__ = ["closed_low_depth", "find_extremum", "track_in_fields"]

naturev1/cyclone/fields.py

@@ -1,231 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The atmosphere around one storm: a latitude-longitude box of analysis fields with spherical calculus.
-
-The idea: every physical diagnostic a track model needs -- layer-mean winds, vorticity and its gradient,
-divergence, the Laplacian for inverting vorticity -- is computed with the sphere's metric terms (the
-``1 / (a cos(lat))`` on every east-west derivative, the ``cos(lat)`` inside the curl and the divergence),
-not as finite differences in degrees. The box is stored with continuous (unwrapped) longitudes, so a storm
-box straddling the dateline is just a box. Sampling between grid points is bilinear in the box's own
-coordinates, with any longitude mapped into the box first; points outside the box clamp to its edge rather
-than wrapping onto the far side of the planet.
-
-Layer means are pressure-weighted (trapezoid in pressure), the vertical average a steering-layer argument
-actually calls for; levels between the stored ones interpolate in log-pressure.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-import numpy as np
-
-from .geometry import EARTH_RADIUS_KM, coriolis, to_local
-
-A_M = EARTH_RADIUS_KM * 1000.0
-
-#: Variables stored on pressure levels, and single-level ones.
-LEVEL_FIELDS = ("u", "v", "z", "t", "q")
-SURFACE_FIELDS = ("msl", "sst", "tcwv", "lsm", "zs")
-
-
-@dataclass
-class Environment:
-    """
-    Analysis fields in a box around a storm.
-
-    Attributes:
-        lat: ``(H,)`` ascending latitudes, degrees.
-        lon: ``(W,)`` ascending, continuous longitudes (may run past 180), degrees.
-        levels: pressure levels, hPa, in the order the level fields are stored.
-        fields: ``name -> (L, H, W)`` for level fields, ``(H, W)`` for single-level ones. SI units (m/s,
-            m^2/s^2 geopotential, K, kg/kg, Pa, 0-1 land fraction).
-        previous: the same kind of mapping 12 hours earlier, for the fields that were stored (u, v, z).
-        time: the analysis time.
-    """
-
-    lat: np.ndarray
-    lon: np.ndarray
-    levels: tuple[int, ...]
-    fields: dict[str, np.ndarray]
-    previous: dict[str, np.ndarray] = field(default_factory=dict)
-    time: np.datetime64 | None = None
-
-    # ------------------------------------------------------------------------------- access --
-
-    @property
-    def shape(self) -> tuple[int, int]:
-        return self.lat.size, self.lon.size
-
-    @property
-    def spacing_deg(self) -> float:
-        return float(self.lat[1] - self.lat[0])
-
-    def has(self, name: str) -> bool:
-        return name in self.fields
-
-    def level(self, name: str, pressure: float, previous: bool = False) -> np.ndarray:
-        """A level field at ``pressure`` hPa, interpolated in log-pressure between stored levels."""
-        source = self.previous if previous else self.fields
-        data = source[name]
-        levels = np.asarray(self.levels if data.shape[0] == len(self.levels) else self.previous_levels, np.float64)
-        if pressure in levels:
-            return data[int(np.nonzero(levels == pressure)[0][0])]
-        order = np.argsort(levels)
-        lv = levels[order]
-        p = float(np.clip(pressure, lv[0], lv[-1]))
-        j = int(np.clip(np.searchsorted(lv, p) - 1, 0, len(lv) - 2))
-        w = (np.log(p) - np.log(lv[j])) / (np.log(lv[j + 1]) - np.log(lv[j]))
-        return (1.0 - w) * data[order[j]] + w * data[order[j + 1]]
-
-    #: Levels of the stored previous-time level fields (set by the loader when they differ).
-    previous_levels: tuple[int, ...] = ()
-
-    def layer_mean(self, name: str, top: float, bottom: float, previous: bool = False,
-                   weights: dict[float, float] | None = None) -> np.ndarray:
-        """
-        Pressure-weighted mean of a level field between ``top`` and ``bottom`` hPa (trapezoid in pressure),
-        or a weighted mean over explicit ``weights`` ``{level: weight}`` when given.
-        """
-        if weights is not None:
-            total = sum(weights.values())
-            return sum(w * self.level(name, p, previous) for p, w in weights.items()) / total
-        source = self.previous if previous else self.fields
-        levels = np.asarray(self.levels if source[name].shape[0] == len(self.levels) else self.previous_levels,
-                            np.float64)
-        inside = sorted({float(p) for p in levels if top <= p <= bottom} | {float(top), float(bottom)})
-        values = [self.level(name, p, previous) for p in inside]
-        total = np.zeros_like(values[0], dtype=np.float64)
-        span = 0.0
-        for k in range(len(inside) - 1):
-            dp = inside[k + 1] - inside[k]
-            total = total + 0.5 * dp * (values[k] + values[k + 1])
-            span += dp
-        return total / max(span, 1e-9)
-
-    # ----------------------------------------------------------------------------- sampling --
-
-    def _fractional_index(self, lat, lon):
-        lat = np.asarray(lat, np.float64)
-        lon = np.asarray(lon, np.float64)
-        step = self.lat[1] - self.lat[0]
-        fi = (lat - self.lat[0]) / step
-        offset = (lon - self.lon[0]) % 360.0
-        fj = offset / (self.lon[1] - self.lon[0])
-        fi = np.clip(fi, 0.0, self.lat.size - 1.000001)
-        fj = np.clip(fj, 0.0, self.lon.size - 1.000001)
-        return fi, fj
-
-    def sample(self, grid: np.ndarray, lat, lon) -> np.ndarray:
-        """Bilinear value of a ``(H, W)`` field at points (degrees); outside the box clamps to its edge."""
-        fi, fj = self._fractional_index(lat, lon)
-        i0, j0 = np.floor(fi).astype(int), np.floor(fj).astype(int)
-        di, dj = fi - i0, fj - j0
-        return ((1 - di) * (1 - dj) * grid[i0, j0] + (1 - di) * dj * grid[i0, j0 + 1]
-                + di * (1 - dj) * grid[i0 + 1, j0] + di * dj * grid[i0 + 1, j0 + 1])
-
-    def inside(self, lat, lon, margin_deg: float = 0.0):
-        """Whether points lie inside the box (with a margin)."""
-        lat = np.asarray(lat, np.float64)
-        offset = (np.asarray(lon, np.float64) - self.lon[0]) % 360.0
-        return ((lat >= self.lat[0] + margin_deg) & (lat <= self.lat[-1] - margin_deg)
-                & (offset >= margin_deg) & (offset <= self.lon[-1] - self.lon[0] - margin_deg))
-
-    # ---------------------------------------------------------------------------- calculus --
-
-    @property
-    def coslat(self) -> np.ndarray:
-        return np.cos(np.radians(self.lat))[:, None]
-
-    def ddx(self, f: np.ndarray) -> np.ndarray:
-        """East derivative, per metre: (1 / (a cos(lat))) d/dlambda."""
-        dl = np.radians(self.lon[1] - self.lon[0])
-        g = np.gradient(f, dl, axis=-1)
-        return g / (A_M * np.maximum(self.coslat, 1e-3))
-
-    def ddy(self, f: np.ndarray) -> np.ndarray:
-        """North derivative, per metre: (1 / a) d/dphi."""
-        dp = np.radians(self.lat[1] - self.lat[0])
-        return np.gradient(f, dp, axis=-2) / A_M
-
-    def vorticity(self, u: np.ndarray, v: np.ndarray) -> np.ndarray:
-        """Relative vorticity on the sphere: (1 / (a cos)) [dv/dlambda - d(u cos)/dphi]."""
-        dl = np.radians(self.lon[1] - self.lon[0])
-        dp = np.radians(self.lat[1] - self.lat[0])
-        c = np.maximum(self.coslat, 1e-3)
-        return (np.gradient(v, dl, axis=-1) - np.gradient(u * c, dp, axis=-2)) / (A_M * c)
-
-    def divergence(self, u: np.ndarray, v: np.ndarray) -> np.ndarray:
-        """Horizontal divergence on the sphere: (1 / (a cos)) [du/dlambda + d(v cos)/dphi]."""
-        dl = np.radians(self.lon[1] - self.lon[0])
-        dp = np.radians(self.lat[1] - self.lat[0])
-        c = np.maximum(self.coslat, 1e-3)
-        return (np.gradient(u, dl, axis=-1) + np.gradient(v * c, dp, axis=-2)) / (A_M * c)
-
-    def laplacian(self, f: np.ndarray) -> np.ndarray:
-        """Spherical Laplacian: div(grad f)."""
-        return self.divergence(self.ddx(f), self.ddy(f))
-
-    def coriolis(self) -> np.ndarray:
-        """f on the box, ``(H, 1)``."""
-        return coriolis(self.lat)[:, None]
-
-    def absolute_vorticity(self, u: np.ndarray, v: np.ndarray) -> np.ndarray:
-        return self.vorticity(u, v) + self.coriolis()
-
-    def advect(self, u: np.ndarray, v: np.ndarray, f: np.ndarray) -> np.ndarray:
-        """-(u . grad) f."""
-        return -(u * self.ddx(f) + v * self.ddy(f))
-
-    # ------------------------------------------------------------------------------ frames --
-
-    def local_coordinates(self, lat0: float, lon0: float) -> tuple[np.ndarray, np.ndarray]:
-        """``(x, y)`` km of every grid point in the azimuthal-equidistant frame centred on (lat0, lon0)."""
-        lat_g, lon_g = np.meshgrid(self.lat, self.lon, indexing="ij")
-        return to_local(lat0, lon0, lat_g, lon_g)
-
-    def distance_km(self, lat0: float, lon0: float) -> np.ndarray:
-        x, y = self.local_coordinates(lat0, lon0)
-        return np.hypot(x, y)
-
-    def cell_area_m2(self) -> np.ndarray:
-        """Area of each grid cell, ``(H, W)``."""
-        dl = np.radians(self.lon[1] - self.lon[0])
-        dp = np.radians(self.lat[1] - self.lat[0])
-        return np.broadcast_to(A_M ** 2 * dl * dp * self.coslat, self.shape).copy()
-
-
-def synthetic_environment(lat0: float = 20.0, lon0: float = -60.0, half_lat: float = 30.0, half_lon: float = 45.0,
-                          step: float = 1.5, levels=(1000, 925, 850, 700, 600, 500, 400, 300, 250, 200, 150, 100, 50),
-                          u=None, v=None) -> Environment:
-    """
-    A constructed environment for tests and scenarios: uniform or functional winds ``u(lat, lon, p)`` and
-    ``v(lat, lon, p)`` (callables or constants), a standard-atmosphere column and a warm ocean.
-    """
-    lat = np.arange(lat0 - half_lat, lat0 + half_lat + 1e-9, step)
-    lon = np.arange(lon0 - half_lon, lon0 + half_lon + 1e-9, step)
-    lat_g, lon_g = np.meshgrid(lat, lon, indexing="ij")
-    levels = tuple(int(p) for p in levels)
-    shape = (len(levels), lat.size, lon.size)
-
-    def build(spec):
-        if spec is None:
-            return np.zeros(shape)
-        if callable(spec):
-            return np.stack([np.broadcast_to(spec(lat_g, lon_g, p), lat_g.shape) for p in levels]).astype(np.float64)
-        return np.full(shape, float(spec))
-
-    p = np.asarray(levels, np.float64)
-    t_col = np.clip(288.15 * (p / 1013.25) ** 0.190263, 210.0, None)
-    z_col = 9.80665 * 44330.8 * (1 - (p / 1013.25) ** 0.190263)
-    q_col = 0.018 * (p / 1000.0) ** 3
-    fields = {"u": build(u), "v": build(v),
-              "z": np.broadcast_to(z_col[:, None, None], shape).copy(),
-              "t": np.broadcast_to(t_col[:, None, None], shape).copy(),
-              "q": np.broadcast_to(q_col[:, None, None], shape).copy(),
-              "msl": np.full(lat_g.shape, 101300.0), "sst": np.full(lat_g.shape, 302.0),
-              "tcwv": np.full(lat_g.shape, 50.0), "lsm": np.zeros(lat_g.shape), "zs": np.zeros(lat_g.shape)}
-    return Environment(lat=lat, lon=lon, levels=levels, fields=fields)
-
-
-__all__ = ["Environment", "LEVEL_FIELDS", "SURFACE_FIELDS", "synthetic_environment"]

naturev1/cyclone/fit.py

@@ -1,85 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Fitting the hard-coded constants once, and writing them into the package as code.
-
-The idea: "no training" should mean the forecast system needs nothing but an analysis and a best track when it
-runs -- not that it was never calibrated. Every number the system relies on is fitted here, once, on data
-strictly older than (or disjoint from) the seasons it is judged on, and then *written into*
-:mod:`naturev1.cyclone.coefficients` as Python literals with their provenance:
-
-* CLIPER and SHIFOR on 1980-2014 best tracks (35 years, ~80,000 fixes, all basins);
-* the consensus weights, SHIPS-style regression and LGEM growth rates on the 2016/2017/2019 hindcast seasons;
-* the genesis logistic model on the same three seasons;
-* none of it on 2018/2020/2021/2022, the seasons every reported result comes from.
-
-The written module is plain data: reading it needs no fitting code, no data and no randomness.
-"""
-
-from __future__ import annotations
-
-import datetime as dt
-import json
-import pprint
-from pathlib import Path
-
-import numpy as np
-
-HEADER = '''# Copyright 2026 Nathan. Apache-2.0.
-"""
-Hard-coded constants of the tropical-cyclone physics, generated by :mod:`naturev1.cyclone.fit`.
-
-Do not edit by hand: regenerate with ``naturev1.cyclone.fit.write_coefficients``. Provenance of every table is in
-:data:`PROVENANCE`; nothing here was fitted on the 2018, 2020, 2021 or 2022 seasons the benchmark reports.
-"""
-
-'''
-
-
-def _plain(value):
-    """Literal-safe, rounded copy (numpy to lists; NaN stays NaN, written as ``nan``)."""
-    if isinstance(value, dict):
-        return {str(k): _plain(v) for k, v in value.items()}
-    if isinstance(value, (list, tuple, np.ndarray)):
-        return [_plain(v) for v in (value.tolist() if isinstance(value, np.ndarray) else value)]
-    if isinstance(value, (float, np.floating)):
-        return float("nan") if not np.isfinite(value) else round(float(value), 5)
-    if isinstance(value, (np.integer,)):
-        return int(value)
-    return value
-
-
-def write_coefficients(tables: dict, path: str | Path, provenance: dict) -> Path:
-    """Write ``{NAME: table}`` as module-level constants (plus ``PROVENANCE``) into ``path``."""
-    path = Path(path)
-    lines = [HEADER, "nan = float(\"nan\")\n\n"]
-    for name, table in tables.items():
-        literal = pprint.pformat(_plain(table), width=118, compact=True, sort_dicts=False)
-        lines.append(f"{name} = {literal}\n\n")
-    stamp = {"generated": dt.datetime.now(dt.timezone.utc).strftime("%Y-%m-%d %H:%M UTC"), **provenance}
-    lines.append(f"PROVENANCE = {pprint.pformat(_plain(stamp), width=118, sort_dicts=False)}\n")
-    path.write_text("".join(lines))
-    return path
-
-
-def fit_climatology_tables(history_cases, leads) -> dict:
-    """CLIPER and SHIFOR from historical cases (best tracks only)."""
-    from .cliper import fit_cliper
-    from .intensity import fit_shifor
-
-    return {"CLIPER": fit_cliper(history_cases, leads), "SHIFOR": fit_shifor(history_cases, leads)}
-
-
-def fit_consensus_table(cases, forecasts: dict, members, reference: str = "cliper") -> dict:
-    """Along/cross-track consensus weights over ``members`` (``forecasts[name]``: ``(N, L, 2)``)."""
-    from .consensus import fit_consensus
-
-    stack = np.stack([forecasts[m] for m in members], 2)
-    w = fit_consensus(cases, stack, reference=list(members).index(reference))
-    return {"members": list(members), "reference": w["reference"], "along": w["along"], "cross": w["cross"]}
-
-
-def load_json(path: str | Path) -> dict:
-    return json.loads(Path(path).read_text())
-
-
-__all__ = ["fit_climatology_tables", "fit_consensus_table", "load_json", "write_coefficients"]

naturev1/cyclone/forecast.py

@@ -1,284 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-One call, the whole physics forecast: track consensus, its members and cone, the regime, the Dorian-type stall
-warning, intensity and the environment that drives it -- from an analysis and the best track so far, with no
-neural network and nothing fitted at run time.
-
-:func:`physics_forecast` is what the rest of NatureV1 uses: the consensus track is a far stronger prior for the
-learned track head than a frozen steering flow, and every diagnostic here is something a forecaster would want
-next to the model's own answer.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .data import LEADS
-
-
-def physics_forecast(case, env, climatology=None, analogs=None, leads=LEADS, intensity: bool = True,
-                     swarm: int = 0, swarm_fixes: list | None = None, swarm_device="cpu", forecast_flow=None,
-                     model_track=None, model_extras=None, previous=None, aids=None) -> dict:
-    """
-    Args:
-        case: a :class:`naturev1.cyclone.data.Case` (position, intensity and the last 48 hours of best track; no
-            ``truth`` needed).
-        env: the analysis around the storm (:class:`naturev1.cyclone.fields.Environment`, with the 12-hour-earlier
-            winds in ``previous`` if available).
-        climatology: a :class:`naturev1.cyclone.climatology.Climatology` (members that need it are skipped
-            without it, and the consensus renormalises over the rest).
-        analogs: an :class:`naturev1.cyclone.analogs.AnalogDatabase`.
-        previous: the previous cycle's result, ``{"time": its analysis time, "track": its (L, 2) track}``: its error
-            for the time now analysed feeds back into the new track (:func:`naturev1.cyclone.consensus.apply_track_feedback`).
-        aids: the NHC's operational aids for the cycle, ``{"track": {tech: (L, 2)}, "intensity": {tech: (L,)}}``
-            (:func:`naturev1.swarm.adeck.aids_at`): blended into the track and the intensity with the tables fitted on
-            the tuning seasons (:mod:`naturev1.cyclone.aids`); our own stay in ``track_ours`` / ``intensity_ours``,
-            what was used in ``aids_track`` / ``aids_intensity``. The peak products keep our own consensus as their
-            input (they were fitted on it); the swarm, the categories and the headline follow the blend. With
-            ``aids["previous_errors"]`` (:func:`naturev1.cyclone.aids.previous_errors`, the previous cycle's verified
-            errors of ours and of HCCA) the split between the two is earned rather than fixed.
-        swarm: if positive, also run the particle-filter sandbox (:mod:`naturev1.swarm`) with this many
-            worlds, re-centred on the consensus track: scenario probabilities, a strike-probability map and a
-            flow-dependent cone under ``result["swarm"]``.
-        swarm_fixes: centre fixes (:mod:`naturev1.swarm.fixes`) to filter the swarm with instead of the 6-hourly
-            history -- the satellite path, minute by minute.
-        forecast_flow, model_track: dynamical models' forecast steering
-            (:class:`naturev1.cyclone.forecastflow.ForecastFlow`, one or ``{name: flow}``) and their own tracks of the
-            storm at ``leads`` (one ``(L, 2)`` or ``{name: track}``): they add the ``fflow`` and ``model`` members
-            (equal-weight means over the models; the consensus fitted with them is blended with the models' mean
-            track) and steer the swarm's worlds, each world following one model.
-        model_extras: the models' ``extras`` from :func:`naturev1.swarm.models.fetch_models` (``{name: extras}``):
-            their central-pressure deepening feeds the rapid-intensification probability and the model-trend
-            intensity member.
-
-    Returns:
-        ``{"leads", "track" (L, 2), "members": {name: (L, 2)}, "cone_km" (L,), "regime", "stall", "ridge",
-        "shear", "intensity_kt": {member: (L,)}, "intensity" (L,), "ri_probability" (P(+30 kt in 24 h)),
-        "intensity_regime" ("rapid" when the rapid-intensification weights were used), "intensity_if_ri" (the path if
-        the storm intensifies rapidly, to read with "ri_probability"), "peak_probability" (P(peak within the window >=
-        64/96/113/137 kt)), "peak_quantiles" (the 50/75/90/95% quantiles of the peak), "peak_if_ri_kt" (E[peak | RI]),
-        "category_probability"
-        (P(>= 64 / 96 / 113 / 137 kt) per lead), "cone_fixed_km", "model_spread_km" and "model_deepening_hpa" (with
-        models: the climatological cone behind the flow-dependent one, the models' disagreement, their deepening)}``.
-    """
-    from .consensus import apply_consensus
-    from .members import run_members
-    from .regimes import classify
-    from .ridge import ridge_diagnostics
-    from .shear import shear_diagnostics
-    from .stall import stall_diagnostics
-
-    out = run_members(case, env, climatology, analogs, leads=leads, forecast_flow=forecast_flow,
-                      model_track=model_track)
-    ctx = out.pop("_context", None)
-    ensemble = out.pop("_ensemble", None)
-    table = consensus_table(out)
-    nan = np.full((len(leads), 2), np.nan)
-    stack = np.stack([out.get(m, nan) for m in table["members"]], 1)[None]
-    physics_track = apply_consensus([case], stack, table)[0]
-    track = physics_track
-    result_models = 0
-    if table.get("model_blend") is not None and out.get("model") is not None:
-        from .consensus import blend_with_model
-
-        n_models = (sum(1 for t in model_track.values() if t is not None and np.isfinite(np.asarray(t)[:, 0]).any())
-                    if isinstance(model_track, dict) else 1)
-        track = blend_with_model(case, physics_track, np.asarray(out["model"], np.float64), table["model_blend"], leads, n_models)
-        result_models = n_models
-    if previous is not None and isinstance(previous, dict) and previous.get("track") is not None:
-        from .consensus import apply_track_feedback
-
-        track = apply_track_feedback(case, track, previous["track"], previous.get("time"), leads,
-                                     previous_position=(previous["lat"], previous["lon"]) if "lat" in previous and "lon" in previous else None)
-    result = {"leads": list(leads), "track": track, "members": out, "consensus_table": table["name"],
-              "n_models": result_models}
-    from . import coefficients
-
-    # each consensus table has its own cone: the forecast-flow consensus errs less, so its cone is narrower
-    cone_name = {"CONSENSUS_FF": "CONE_KM_FF", "CONSENSUS_BASIC_FF": "CONE_KM_BASIC_FF"}.get(table["name"], "CONE_KM")
-    cone = getattr(coefficients, cone_name, None) or getattr(coefficients, "CONE_KM", None)
-    if cone is not None:
-        # The 67th percentile of the consensus's out-of-sample errors on past seasons -- NHC's cone construction --
-        # widened where the physics ensemble disagrees more than usual for that lead.
-        climatological = np.interp(np.asarray(leads, np.float64), cone["leads"], cone["radius_km"])
-        radius = climatological
-        if ensemble is not None:
-            radius = np.maximum(radius, 1.2 * np.nan_to_num(ensemble["spread_km"], nan=0.0))
-        result["cone_km"] = radius
-        flow_table = getattr(coefficients, "CONE_FLOW", None)
-        if flow_table is not None and out.get("model") is not None:
-            # the cone sized for this forecast: member spread, model disagreement, speed, latitude, intensity
-            # (fitted and checked without the ensemble-spread floor, so it stands on its own)
-            from .multimodel import cone_predictors, flow_dependent_cone
-
-            result["cone_fixed_km"] = climatological
-            result["cone_predictors"] = cone_predictors(case, physics_track, out, table["members"], out.get("model"),
-                                                        out.get("fflow"), leads)
-            result["cone_km"] = flow_dependent_cone(result["cone_predictors"], flow_table, leads)
-    if isinstance(model_track, dict):
-        from .multimodel import model_spread_km
-
-        result["model_spread_km"] = model_spread_km(case, model_track)
-    if aids and aids.get("track") and getattr(coefficients, "ADECK_TRACK", None):
-        # the NHC guidance blended in after the cone is known: the split between ours and HCCA is earned from the
-        # previous cycle and moved away from the member that stands alone beyond the cone (cyclone.aids)
-        from .aids import blend_track
-
-        blended_track, used_aids = blend_track(case, track, aids["track"], leads, coefficients.ADECK_TRACK,
-                                               previous_errors=aids.get("previous_errors"), cone_km=result.get("cone_km"))
-        if used_aids:
-            result["track_ours"], result["aids_track"] = track, used_aids
-            track = blended_track
-            result["track"] = track
-    if ctx is not None:
-        stall = stall_diagnostics(ctx.flows["med"], np.where(np.isfinite(track), track, case.lat), leads, case.lat, case.lon)
-        ridge = ridge_diagnostics(ctx.clean, case.lat, case.lon)
-        result.update({"stall": {k: v for k, v in stall.items() if k != "cols"}, "cols": stall["cols"], "ridge": ridge,
-                       "regime": classify(case, stall, ridge), "shear": shear_diagnostics(ctx.clean, case.lat, case.lon, ctx.motion),
-                       "outer_strength_ms": ctx.outer_ms})
-    if intensity:
-        result.update(_intensity(case, env, ctx, track, leads, model_extras, aids=aids))
-    if swarm and ctx is not None:
-        from ..swarm.core import swarm_products
-
-        # the swarm sized to this forecast's own cone where the flow-dependent cone could be made
-        result["swarm"] = swarm_products(case, ctx, track, leads, particles=int(swarm), fixes=swarm_fixes,
-                                         intensity_kt=result.get("intensity"), device=swarm_device,
-                                         forecast_flow=forecast_flow,
-                                         target_cone_km=result.get("cone_km") if "cone_predictors" in result else None)
-    return result
-
-
-def consensus_table(members: dict) -> dict:
-    """
-    The shipped consensus whose members are all present: the full table when a climatology and an analog
-    database were given, else the basic one fitted for exactly the members that need neither -- renormalising
-    the full table over half its members would lean on combinations it was never fitted to trust. With a dynamical
-    model's forecast flow and track (the ``fflow`` and ``model`` members), the tables fitted with them come first.
-    """
-    from . import coefficients
-
-    best, best_share = None, -1.0
-    for name in ("CONSENSUS_FF", "CONSENSUS_BASIC_FF", "CONSENSUS", "CONSENSUS_BASIC"):
-        table = getattr(coefficients, name, None)
-        if table is None:
-            continue
-        have = [np.isfinite(np.asarray(members.get(m, [[np.nan]]))[0]).all() for m in table["members"]]
-        if all(have):
-            return {**table, "name": name}
-        # none complete (say, no analysis 12 hours earlier): the table missing the smallest share of its members,
-        # renormalised over the rest, in the same order of preference
-        if np.mean(have) > best_share:
-            best, best_share = name, float(np.mean(have))
-    name = best or "CONSENSUS_BASIC"
-    return {**getattr(coefficients, name), "name": name}
-
-
-def _with_aids(out: dict, aids, leads) -> dict:
-    """The aid blend on a fallback intensity (SHIFOR only), when the table and the aids are there."""
-    from . import coefficients
-
-    if aids and aids.get("intensity") and getattr(coefficients, "ADECK_INTENSITY", None):
-        from .aids import blend_intensity
-
-        blended, used = blend_intensity(out["intensity"], aids["intensity"], leads, coefficients.ADECK_INTENSITY)
-        if used:
-            out.update({"intensity_ours": out["intensity"], "intensity": blended, "aids_intensity": used})
-    return out
-
-
-def _intensity(case, env, ctx, track, leads, model_extras=None, aids=None) -> dict:
-    from . import coefficients
-    from .intensity import (category_probabilities, decay_along, environment_along_track, lgem_intensity,
-                            model_deficit_change, model_trend_intensity, peak_if_ri, peak_probability, peak_quantiles, ri_probability,
-                            ri_scenario_intensity,
-                            shifor_intensity, trend_intensity)
-
-    members = {"persistence": np.full(len(leads), case.wind_kt)}
-    shifor = shifor_intensity(case, leads)
-    members["shifor"] = shifor
-    if ctx is None or not np.isfinite(track[0, 0]):
-        return _with_aids({"intensity_kt": members, "intensity": shifor}, aids, leads)
-    filled = track.copy()
-    good = np.isfinite(filled[:, 0])
-    filled[~good] = filled[np.nonzero(good)[0][-1]]
-    ocean = None
-    if getattr(coefficients, "OCEAN", None):                 # the tables were fitted with the ocean climatology
-        from .ocean import OceanClimatology
-
-        ocean = OceanClimatology.default()
-    try:
-        along = environment_along_track(env, ctx.clean, case, filled, leads, np.nan_to_num(shifor, nan=case.wind_kt), ocean=ocean)
-    except Exception as error:                              # missing fields in a live analysis: degrade, don't fail
-        return _with_aids({"intensity_kt": members, "intensity": shifor, "intensity_note": f"environment along the track unavailable ({type(error).__name__}: {error}); SHIFOR only"}, aids, leads)
-    members["decay_shifor"] = decay_along(case, along, leads, np.nan_to_num(shifor, nan=case.wind_kt))
-    members["lgem"] = lgem_intensity(case, along, leads)
-    members["trend"] = trend_intensity(case, along, leads)
-    model_dp = model_deficit_change(model_extras, leads)
-    extra = {}
-    if model_dp is not None and np.isfinite(model_dp).any():
-        # the dynamical models' own deepening, as an intensity member and (below) as a rapid-intensification predictor
-        members["mdl"] = model_trend_intensity(case, along, leads, model_dp)
-        extra["model_deepening_hpa"] = model_dp
-    try:
-        from .coefficients import INTENSITY_CONSENSUS
-        from .intensity import ships_intensity
-
-        members["ships"] = decay_along(case, along, leads, ships_intensity(case, along, leads))
-        table = INTENSITY_CONSENSUS
-        regime = table.get("ri_regime")
-        if regime is not None:
-            # A storm primed for rapid intensification gets the weights fitted on such storms: they lean on LGEM and
-            # the trend, and correct the consensus's habit of pulling an intensifying storm back toward the mean.
-            p = ri_probability(case, along, model_dp=model_dp, leads=leads)
-            extra.update({"ri_probability": p, "intensity_regime": "rapid" if p >= regime["cut"] else "normal"})
-            if p >= regime["cut"]:
-                table = {**table, "weights": regime["weights"], "bias": regime["bias"]}
-        weights = np.asarray(table["weights"], np.float64)                      # (L, members)
-        nan = np.full(len(leads), np.nan)
-        stack = np.stack([members.get(n, nan) for n in table["members"]], -1)   # a member without its model: dropped
-        blended = (np.nan_to_num(stack) * weights).sum(-1) / np.maximum((np.isfinite(stack) * weights).sum(-1), 1e-9)
-        blended = blended + np.asarray(table.get("bias", np.zeros(len(leads))), np.float64)
-        # a basin's own residual bias (wind conventions and storm sizes differ between basins), when the table has it
-        blended = blended + np.asarray(INTENSITY_CONSENSUS.get("basin_bias", {}).get(case.basin, np.zeros(len(leads))), np.float64)
-    except ImportError:
-        blended = np.nanmean(np.stack([members["decay_shifor"], members["lgem"]]), 0)
-    intensity = np.clip(blended, 15.0, 200.0)
-    own = intensity
-    if aids and aids.get("intensity") and getattr(coefficients, "ADECK_INTENSITY", None):
-        # the operational aids beside our consensus, with the weights fitted on the tuning seasons; the peak products
-        # below keep our own consensus as their input, which is what they were fitted on
-        from .aids import blend_intensity
-
-        intensity, used = blend_intensity(intensity, aids["intensity"], leads, coefficients.ADECK_INTENSITY)
-        if used:
-            extra["aids_intensity"] = used
-            extra["intensity_ours"] = own
-    # the branch beside the expected value: the storm's path if it intensifies rapidly, with its probability
-    if_ri = ri_scenario_intensity(case, along, leads)
-    if np.isfinite(if_ri).any():
-        extra["intensity_if_ri"] = np.clip(if_ri, 15.0, 200.0)
-    categories = category_probabilities(intensity, extra.get("intensity_regime", "normal"), ri_probability=extra.get("ri_probability"),
-                                        ri_intensity=extra.get("intensity_if_ri"))
-    try:
-        peak = peak_probability(case, along, own, extra.get("ri_probability"), model_dp, leads=leads)
-    except Exception as error:
-        peak = {}
-        extra["intensity_note"] = f"peak probability unavailable ({type(error).__name__}: {error})"
-    if peak:
-        extra["peak_probability"] = peak
-    try:
-        pq = peak_quantiles(case, along, own, extra.get("ri_probability"), model_dp, extra.get("intensity_if_ri"), leads=leads)
-        if pq:
-            extra["peak_quantiles"] = pq
-        e_ri = peak_if_ri(case, along, own, extra.get("ri_probability"), model_dp, extra.get("intensity_if_ri"), leads=leads)
-        if np.isfinite(e_ri):
-            extra["peak_if_ri_kt"] = e_ri
-    except Exception as error:
-        extra["intensity_note"] = f"peak quantiles unavailable ({type(error).__name__}: {error})"
-    if categories:
-        extra["category_probability"] = categories
-    return {"intensity_kt": members, "intensity": intensity, "environment": along, **extra}
-
-
-__all__ = ["consensus_table", "physics_forecast"]

naturev1/cyclone/forecastflow.py

@@ -1,88 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Steering that evolves the way a dynamical model forecasts it -- for the turns.
-
-A storm turns when its steering changes: a trough digs in, a ridge erodes, a weakness opens. The analysis plus its
-12-hour tendency (:class:`naturev1.cyclone.trajectory.EvolvingFlow`) cannot know about a trough that is still
-2,000 km away and two days off. A dynamical model's forecast can. This is the idea of NHC's Beta and Advection Model:
-carry the storm through the model's *forecast* layer-mean winds, plus beta drift.
-
-:class:`ForecastFlow` holds those winds at forecast hours (every 12 h to 120 h) for three layers -- 850-700,
-850-400 and 850-200 hPa -- with the model's own storm removed at each hour (Biot-Savart removal around where the
-model has it, :func:`naturev1.cyclone.vortex.remove_vortex`), so a trajectory is steered by the environment, not by
-the model's copy of the hurricane. Between forecast hours it interpolates linearly.
-
-:func:`fflow_member` is the trajectory member; :mod:`naturev1.swarm` steers its worlds with the same flow. In
-hindcasts the flow comes from the HRES forecasts of WeatherBench 2; live, from GFS
-(:meth:`naturev1.swarm.analysis.GFSAnalysis.forecast_flow`). No neural network is involved: the model is the ECMWF or
-NOAA physics model.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-#: Layers stored, in channel order (u, v each): shallow, medium, deep.
-LAYERS = (("shal", 700, 850), ("med", 400, 850), ("dlm", 200, 850))
-
-
-class ForecastFlow:
-    """Layer-mean steering at forecast hours: ``data`` ``(T, 6, H, W)`` (shal u, v, med u, v, dlm u, v) on the
-    ``lat`` x ``lon`` box, at ``hours`` ``(T,)``."""
-
-    def __init__(self, lat: np.ndarray, lon: np.ndarray, hours, data: np.ndarray, source: str = "") -> None:
-        self.lat = np.asarray(lat, np.float64)
-        self.lon = np.asarray(lon, np.float64)
-        self.hours = np.asarray(hours, np.float64)
-        self.data = np.asarray(data, np.float32)
-        self.source = source
-
-    def _bracket(self, hours: float):
-        h = float(np.clip(hours, self.hours[0], self.hours[-1]))
-        k = int(np.clip(np.searchsorted(self.hours, h, side="right") - 1, 0, self.hours.size - 2))
-        a = (h - self.hours[k]) / max(self.hours[k + 1] - self.hours[k], 1e-9)
-        return k, a
-
-    def field(self, hours: float, layer: str = "med") -> tuple[np.ndarray, np.ndarray]:
-        """``(u, v)`` grids of ``layer`` at ``hours``."""
-        j = [name for name, _, _ in LAYERS].index(layer)
-        k, a = self._bracket(hours)
-        u = (1 - a) * self.data[k, 2 * j] + a * self.data[k + 1, 2 * j]
-        v = (1 - a) * self.data[k, 2 * j + 1] + a * self.data[k + 1, 2 * j + 1]
-        return u.astype(np.float64), v.astype(np.float64)
-
-    def velocity(self, env, lat, lon, hours: float, depth: float = 0.5):
-        """Steering at points for a steering depth (0 shallow .. 0.5 medium .. 1 deep), interpolated in time."""
-        w_sh, w_dp = max(1.0 - 2.0 * depth, 0.0), max(2.0 * depth - 1.0, 0.0)
-        w_md = 1.0 - w_sh - w_dp
-        u = np.zeros(np.shape(lat))
-        v = np.zeros(np.shape(lat))
-        for name, w in (("shal", w_sh), ("med", w_md), ("dlm", w_dp)):
-            if w <= 0:
-                continue
-            gu, gv = self.field(hours, name)
-            u = u + w * env.sample(gu, lat, lon)
-            v = v + w * env.sample(gv, lat, lon)
-        return u, v
-
-
-def fflow_member(ctx, flow: ForecastFlow, leads, tau_h: float = 24.0, depth: float | None = 0.5) -> np.ndarray:
-    """
-    The storm carried through the forecast flow, plus beta drift, plus the part of its present motion the flow does
-    not explain, fading with ``tau_h`` (``(L, 2)`` lat, lon). ``depth`` 0.5 is the 850-400 hPa layer, which beat the
-    intensity-dependent depth (``None``) and the shallow and deep layers on the tuning seasons.
-    """
-    from ..swarm.core import depth_for_wind
-    from .trajectory import DecayingResidual, combined, integrate
-
-    case = ctx.case
-    depth = depth_for_wind(case.wind_kt) if depth is None else float(depth)
-    env = ctx.clean
-    steer = lambda lat, lon, hours: flow.velocity(env, lat, lon, hours, depth)
-    u0, v0 = steer(np.array([case.lat]), np.array([case.lon]), 0.0)
-    b0 = ctx.beta0()
-    residual = DecayingResidual(ctx.motion[0] - float(u0[0]) - b0[0], ctx.motion[1] - float(v0[0]) - b0[1], tau_h)
-    return integrate(case.lat, case.lon, combined(steer, ctx.beta_velocity(), residual), leads)
-
-
-__all__ = ["ForecastFlow", "LAYERS", "fflow_member"]

naturev1/cyclone/genesis.py

@@ -1,347 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Seeing storms before they are storms: genesis detection from the analysis, verified against what formed.
-
-The idea: a tropical cyclone forms from a disturbance that has been visible for days -- a tropical wave, a
-monsoon-trough vortex -- and the question a forecaster answers (NHC's two- and seven-day outlooks) is which
-disturbances will become cyclones and when. The ingredients are known physics (Gray 1968; Emanuel and Nolan
-2004; Dunkerton et al. 2009): low-level spin that is rotation-dominated rather than shear (Okubo-Weiss),
-a moist mid-troposphere, weak vertical shear, warm water, a closed circulation in the frame moving with the
-wave (:mod:`naturev1.cyclone.pouch`), a mid-level vortex stacking above it, and a falling surface pressure. So:
-
-1. **Candidates**: local maxima of smoothed 850 hPa cyclonic vorticity above a threshold over warm ocean in the
-   tropics, at every analysis time, away from cyclones that already exist.
-2. **Candidate tracks**: candidates linked in time (nearest within 600 km of where the 700 hPa flow carries
-   them), so each disturbance has an age and a history -- intensifying spin matters more than strong spin.
-3. **Features** per candidate and time: vorticity (850, 600), its 24-hour change, Okubo-Weiss, 600 hPa
-   humidity, 850-200 shear, SST, a closed-low depth, the 300 hPa warm-core anomaly, the genesis potential
-   index, and the wave-relative pouch's closedness.
-4. **Probability** of genesis within 48 hours: a logistic model on those features, fitted on the 2016/2017/2019
-   seasons against IBTrACS (genesis = the first tropical or subtropical fix within 300 km of the candidate in the
-   next 48 hours) and verified on 2018/2020-2022 with the Brier score, its skill against climatology, detection
-   rate and false alarms, and how many hours of warning the detector gives.
-
-The basin store (:func:`build_genesis_store`) keeps the northern-hemisphere tropics (0-45 N, all longitudes)
-at 00 and 12 UTC through each season: the 850, 600 and 200 hPa winds, 600 hPa temperature and humidity, the
-300 and 850 hPa temperatures, sea-level pressure and SST.
-"""
-
-from __future__ import annotations
-
-import json
-from dataclasses import dataclass, field
-from pathlib import Path
-
-import numpy as np
-
-from .fields import Environment
-from .geometry import great_circle_km, hemisphere
-from .pouch import phase_from_history, pouch_closedness
-
-CHANNELS = ("u850", "v850", "u600", "v600", "u200", "v200", "t600", "q600", "t300", "t850", "msl", "sst")
-LAT_RANGE = (0.0, 45.0)
-SEASON = ("06-01", "11-30")
-VORTICITY_MIN = 2.0e-5
-WINDOW_H = 48
-FEATURES = ("one", "vort850", "vort600", "dvort24", "okubo_weiss", "rh600", "shear", "sst", "depth", "warm_core",
-            "gpi", "age", "lat", "pouch")
-
-
-def build_genesis_store(years, root: str | Path, reader=None, log=print) -> dict[int, Path]:
-    """One memmap per season: ``(T, C, H, 240)`` float16 (standardised per channel) plus ``times.npy``."""
-    from .data import WB2Reader
-
-    out = {}
-    for year in years:
-        directory = Path(root) / f"genesis_{year}"
-        out[year] = directory
-        if (directory / "done").exists():
-            continue
-        directory.mkdir(parents=True, exist_ok=True)
-        reader = reader or WB2Reader()
-        rows = np.nonzero((reader.lat >= LAT_RANGE[0]) & (reader.lat <= LAT_RANGE[1]))[0]
-        start, stop = np.datetime64(f"{year}-{SEASON[0]}T00", "s"), np.datetime64(f"{year}-{SEASON[1]}T12", "s")
-        times = np.arange(start, stop + np.timedelta64(1, "s"), np.timedelta64(12, "h"))
-        store = np.lib.format.open_memmap(directory / "fields.npy", mode="w+", dtype=np.float32,
-                                          shape=(len(times), len(CHANNELS), rows.size, reader.lon.size))
-        levels = list(reader.levels)
-        for i, when in enumerate(times):
-            f = reader.fields(when)
-            planes = [f["u"][levels.index(850)], f["v"][levels.index(850)], f["u"][levels.index(600)],
-                      f["v"][levels.index(600)], f["u"][levels.index(200)], f["v"][levels.index(200)],
-                      f["t"][levels.index(600)], f["q"][levels.index(600)], f["t"][levels.index(300)],
-                      f["t"][levels.index(850)], f["msl"], f["sst"]]
-            store[i] = np.stack([p[rows] for p in planes])
-            if log and i % 60 == 0:
-                log(f"[genesis-data] {year}: {i + 1}/{len(times)}")
-        store.flush()
-        np.save(directory / "times.npy", times.astype(np.int64))
-        np.save(directory / "lat.npy", reader.lat[rows])
-        np.save(directory / "lon.npy", reader.lon)
-        (directory / "done").write_text("ok")
-    return out
-
-
-class GenesisSeason:
-    def __init__(self, directory: str | Path) -> None:
-        directory = Path(directory)
-        self.fields = np.load(directory / "fields.npy", mmap_mode="r")
-        self.times = np.load(directory / "times.npy").astype("datetime64[s]")
-        self.lat = np.load(directory / "lat.npy").astype(np.float64)
-        self.lon = np.load(directory / "lon.npy").astype(np.float64)
-        self.slot = {c: k for k, c in enumerate(CHANNELS)}
-
-    def environment(self, i: int) -> Environment:
-        block = np.asarray(self.fields[i], np.float64)
-        f = {c: block[self.slot[c]] for c in CHANNELS}
-        # Wrap one column so derivatives are periodic-ish at the seam; the Environment is the whole band.
-        return Environment(lat=self.lat, lon=self.lon, levels=(850,), fields=f, time=self.times[i])
-
-
-@dataclass
-class Candidate:
-    time: np.datetime64
-    lat: float
-    lon: float
-    features: dict
-    track_id: int = -1
-    label: float = float("nan")
-    history: list = field(default_factory=list)
-
-
-def _smooth(field: np.ndarray, passes: int = 2) -> np.ndarray:
-    out = field.copy()
-    for _ in range(passes):
-        padded = np.pad(out, ((1, 1), (0, 0)), mode="edge")
-        padded = np.concatenate([padded[:, -1:], padded, padded[:, :1]], 1)
-        out = (4 * padded[1:-1, 1:-1] + padded[:-2, 1:-1] + padded[2:, 1:-1] + padded[1:-1, :-2] + padded[1:-1, 2:]) / 8.0
-    return out
-
-
-def _relative_humidity(t, q, p):
-    es = 6.112 * np.exp(17.67 * (t - 273.15) / (t - 29.65))
-    return np.clip(q * p / (0.622 + 0.378 * q) / es, 0.0, 1.2)
-
-
-def diagnostics(env: Environment) -> dict:
-    """Gridded genesis ingredients for one analysis of the band."""
-    f = env.fields
-    zeta850 = env.vorticity(f["u850"], f["v850"])
-    zeta600 = env.vorticity(f["u600"], f["v600"])
-    sign = hemisphere(env.lat)[:, None]
-    dudx, dudy = env.ddx(f["u850"]), env.ddy(f["u850"])
-    dvdx, dvdy = env.ddx(f["v850"]), env.ddy(f["v850"])
-    strain2 = (dudx - dvdy) ** 2 + (dvdx + dudy) ** 2
-    ow = zeta850 ** 2 - strain2
-    rh = _relative_humidity(f["t600"], f["q600"], 600.0)
-    shear = np.hypot(f["u200"] - f["u850"], f["v200"] - f["v850"])
-    sst = np.asarray(f["sst"], np.float64)                            # NaN over land
-    eta = np.abs(zeta850 + env.coriolis())
-    potential = np.clip(np.nan_to_num(sst, nan=273.15) - 273.15 - 26.0, 0.0, None) * 10.0   # stand-in for PI, m/s
-    gpi = np.abs(1e5 * eta) ** 1.5 * (100 * rh / 50.0) ** 3 * (potential / 70.0) ** 3 * (1 + 0.1 * shear) ** -2
-    t300_anom = f["t300"] - _smooth(f["t300"], 20)
-    return {"vort850": sign * _smooth(zeta850), "vort600": sign * _smooth(zeta600), "ow": _smooth(ow), "rh600": rh,
-            "shear": shear, "sst": sst, "gpi": gpi, "warm": t300_anom, "msl": f["msl"]}
-
-
-def find_candidates(env: Environment, diag: dict, existing: list[tuple[float, float]], exclude_km: float = 600.0) -> list[dict]:
-    vort = diag["vort850"]
-    out = []
-    h, w = vort.shape
-    for i in range(2, h - 2):
-        if abs(env.lat[i]) < 3.0 or abs(env.lat[i]) > 35.0:
-            continue
-        for j in range(w):
-            v = vort[i, j]
-            if v < VORTICITY_MIN or not (diag["sst"][i, j] >= 299.15):
-                continue
-            block = vort[i - 1:i + 2, [(j - 1) % w, j, (j + 1) % w]]
-            if v < block.max():
-                continue
-            lat, lon = float(env.lat[i]), float(((env.lon[j] + 180.0) % 360.0) - 180.0)
-            if any(great_circle_km(lat, lon, a, b) < exclude_km for a, b in existing):
-                continue
-            out.append({"lat": lat, "lon": lon, "i": i, "j": j})
-    return out
-
-
-def candidate_features(env: Environment, diag: dict, cand: dict) -> dict:
-    i, j = cand["i"], cand["j"]
-    lat, lon = cand["lat"], cand["lon"]
-    d = great_circle_km(lat, lon, *np.meshgrid(env.lat, env.lon, indexing="ij"))
-    disc = d < 500.0
-    ring = (d >= 500.0) & (d < 900.0)
-    msl = diag["msl"]
-    depth = float(msl[ring].mean() - msl[disc].min()) / 100.0 if ring.any() and disc.any() else 0.0
-    return {"vort850": float(diag["vort850"][i, j]) * 1e5, "vort600": float(diag["vort600"][disc].max()) * 1e5,
-            "okubo_weiss": float(np.clip(diag["ow"][disc].max() * 1e10, -50, 50)), "rh600": float(diag["rh600"][disc].mean()),
-            "shear": float(diag["shear"][disc].mean()) / 10.0,
-            "sst": (float(np.nanmean(diag["sst"][disc])) - 301.15) / 2.0 if np.isfinite(diag["sst"][disc]).any() else -1.0,
-            "depth": depth, "warm_core": float(diag["warm"][disc].max()), "gpi": float(np.log1p(diag["gpi"][disc].mean())),
-            "lat": abs(lat) / 20.0}
-
-
-def genesis_events(tracks, years) -> list[tuple[np.datetime64, float, float]]:
-    """IBTrACS genesis: each storm's first tropical/subtropical fix (time, lat, lon)."""
-    out = []
-    for t in tracks:
-        tropical = np.isin(t.status, ("TD", "TS", "HU", "SS"))
-        if not tropical.any():
-            continue
-        k = int(np.argmax(tropical))
-        if int(str(t.time[k])[:4]) in set(years) and t.latitude[k] >= 0:
-            out.append((t.time[k].astype("datetime64[s]"), float(t.latitude[k]), float(t.longitude[k])))
-    return out
-
-
-def active_storms(tracks, when: np.datetime64) -> list[tuple[float, float]]:
-    out = []
-    for t in tracks:
-        hit = np.nonzero(t.time.astype("datetime64[s]") == when)[0]
-        if hit.size and t.status[hit[0]] in ("TD", "TS", "HU", "SS"):
-            out.append((float(t.latitude[hit[0]]), float(t.longitude[hit[0]])))
-    return out
-
-
-def detect_season(season: GenesisSeason, tracks, link_km: float = 600.0, log=None) -> list[Candidate]:
-    """Candidates at every time, linked into disturbance tracks, with 24-hour trends and ages."""
-    candidates: list[Candidate] = []
-    previous: list[Candidate] = []
-    next_id = 0
-    for i in range(len(season.times)):
-        env = season.environment(i)
-        diag = diagnostics(env)
-        when = season.times[i]
-        found = find_candidates(env, diag, active_storms(tracks, when))
-        current = []
-        for cand in found:
-            feats = candidate_features(env, diag, cand)
-            c = Candidate(when, cand["lat"], cand["lon"], feats)
-            best = None
-            for p in previous:
-                d = great_circle_km(p.lat, p.lon, c.lat, c.lon)
-                if d < link_km and (best is None or d < best[0]):
-                    best = (d, p)
-            if best is not None:
-                c.track_id = best[1].track_id
-                c.history = best[1].history + [best[1]]
-            else:
-                c.track_id, next_id = next_id, next_id + 1
-            c.features["pouch"] = pouch_closedness(env, c.lat, c.lon, phase_from_history(c))["closedness"]
-            current.append(c)
-        for c in current:
-            back = [h for h in c.history if (c.time - h.time) == np.timedelta64(24, "h")]
-            c.features["dvort24"] = c.features["vort850"] - back[0].features["vort850"] if back else 0.0
-            c.features["age"] = min(len(c.history), 10) / 10.0
-        candidates.extend(current)
-        previous = current
-        if log and i % 60 == 0:
-            log(f"[genesis] {str(when)[:10]}: {len(current)} candidates")
-    return candidates
-
-
-def label_candidates(candidates: list[Candidate], events, window_h: int = WINDOW_H, radius_km: float = 300.0) -> None:
-    """1 if a genesis event happens within ``window_h`` hours (and 300 km of the candidate's track) after it."""
-    for c in candidates:
-        c.label = 0.0
-        for when, lat, lon in events:
-            dt = (when - c.time) / np.timedelta64(1, "h")
-            if 0 <= dt <= window_h and great_circle_km(c.lat, c.lon, lat, lon) < radius_km + 15.0 * dt:
-                c.label = 1.0
-                break
-
-
-def feature_matrix(candidates: list[Candidate]) -> np.ndarray:
-    return np.array([[1.0] + [c.features.get(k, 0.0) for k in FEATURES[1:]] for c in candidates], np.float64)
-
-
-def _pairs() -> list[tuple[str, str]]:
-    import itertools
-
-    base = list(FEATURES[1:])
-    return list(itertools.combinations(base, 2)) + [(f, f) for f in base]
-
-
-#: Second-order terms of the shipped model: every pairwise product and square of the ingredients -- humidity
-#: matters more when the shear is weak, spin matters more inside a closed pouch. Chosen over the linear model by
-#: leave-one-season-out cross-validation on the 2016/2017/2019 seasons (Brier skill 0.193 against 0.184).
-PAIRS = _pairs()
-
-
-def design_matrix(candidates: list[Candidate]) -> np.ndarray:
-    """``[1, features, pairwise products and squares]`` per candidate -- the shipped model's inputs."""
-    rows = []
-    for c in candidates:
-        f = c.features
-        rows.append([1.0] + [f.get(k, 0.0) for k in FEATURES[1:]] + [f.get(a, 0.0) * f.get(b, 0.0) for a, b in PAIRS])
-    return np.asarray(rows, np.float64)
-
-
-def candidate_probability(candidates: list[Candidate], weights=None) -> np.ndarray:
-    """Genesis-within-48-hours probability from the shipped coefficients (:data:`naturev1.cyclone.coefficients.GENESIS`)."""
-    if weights is None:
-        from .coefficients import GENESIS
-
-        weights = GENESIS["weights"]
-    return genesis_probability(design_matrix(candidates), weights)
-
-
-def fit_logistic(x: np.ndarray, y: np.ndarray, l2: float = 1e-2, steps: int = 400) -> np.ndarray:
-    """Newton-Raphson L2-regularised logistic regression (intercept unpenalised)."""
-    mean, std = x[:, 1:].mean(0), x[:, 1:].std(0) + 1e-9
-    z = np.concatenate([x[:, :1], (x[:, 1:] - mean) / std], 1)
-    w = np.zeros(z.shape[1])
-    penalty = np.diag([0.0] + [l2 * len(y)] * (z.shape[1] - 1))
-    for _ in range(steps):
-        p = 1.0 / (1.0 + np.exp(-z @ w))
-        grad = z.T @ (p - y) + penalty @ w
-        hess = (z * (p * (1 - p))[:, None]).T @ z + penalty
-        step = np.linalg.solve(hess, grad)
-        w -= step
-        if np.abs(step).max() < 1e-8:
-            break
-    # Fold the standardisation back so the weights apply to raw features.
-    raw = w.copy()
-    raw[1:] = w[1:] / std
-    raw[0] = w[0] - (w[1:] * mean / std).sum()
-    return raw
-
-
-def genesis_probability(x: np.ndarray, weights) -> np.ndarray:
-    return 1.0 / (1.0 + np.exp(-x @ np.asarray(weights, np.float64)))
-
-
-def verify_genesis(candidates: list[Candidate], probability: np.ndarray, events, threshold: float = 0.5) -> dict:
-    """Brier score and skill, reliability-in-thirds, detection rate, false alarms and warning time."""
-    y = np.array([c.label for c in candidates])
-    brier = float(np.mean((probability - y) ** 2))
-    climo = float(np.mean((y.mean() - y) ** 2))
-    hits, lead_hours = 0, []
-    for when, lat, lon in events:
-        warned = [c for c, p in zip(candidates, probability) if p >= threshold
-                  and 0 <= (when - c.time) / np.timedelta64(1, "h") <= WINDOW_H
-                  and great_circle_km(c.lat, c.lon, lat, lon) < 300.0 + 15.0 * (when - c.time) / np.timedelta64(1, "h")]
-        if warned:
-            hits += 1
-            lead_hours.append(max((when - c.time) / np.timedelta64(1, "h") for c in warned))
-    alarms = probability >= threshold
-    false_alarm = float(np.mean(y[alarms] == 0)) if alarms.any() else float("nan")
-    bins = np.quantile(probability, [0, 1 / 3, 2 / 3, 1])
-    reliability = []
-    for lo, hi in zip(bins[:-1], bins[1:]):
-        sel = (probability >= lo) & (probability <= hi)
-        reliability.append((float(probability[sel].mean()), float(y[sel].mean()), int(sel.sum())))
-    return {"brier": brier, "brier_skill": 1.0 - brier / max(climo, 1e-9), "events": len(events), "detected": hits,
-            "detection_rate": hits / max(len(events), 1), "false_alarm_ratio": false_alarm,
-            "median_warning_h": float(np.median(lead_hours)) if lead_hours else float("nan"), "reliability": reliability,
-            "candidates": len(candidates), "base_rate": float(y.mean())}
-
-
-def save_weights(weights, path: str | Path) -> None:
-    Path(path).write_text(json.dumps({"features": list(FEATURES), "weights": [float(w) for w in weights]}))
-
-
-__all__ = ["CHANNELS", "Candidate", "FEATURES", "GenesisSeason", "PAIRS", "build_genesis_store", "candidate_features",
-           "candidate_probability", "design_matrix", "detect_season", "diagnostics", "feature_matrix", "find_candidates",
-           "fit_logistic", "genesis_events",
-           "genesis_probability", "label_candidates", "save_weights", "verify_genesis"]

naturev1/cyclone/geometry.py

@@ -1,154 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Spherical geometry for storm tracks: every move, distance and frame on the sphere, never on a lat-lon sheet.
-
-The idea: a track model that steps a storm east by ``u * dt / (R cos(lat))`` degrees is right in the
-deep tropics and quietly wrong everywhere a storm actually recurves -- the error grows with latitude and
-blows up near the poles, and a longitude step taken in degrees across the dateline is a 360-degree jump.
-Here every displacement is a great-circle move from a bearing and a distance, every local calculation
-happens in an azimuthal-equidistant frame centred on the storm (distances from the centre are exact, and
-the frame turns with the storm), and verification splits errors into along- and cross-track parts the way
-the National Hurricane Center does.
-
-All functions take and return numpy arrays (broadcasting), degrees and kilometres.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-EARTH_RADIUS_KM = 6371.0088
-KM_PER_DEGREE = np.pi * EARTH_RADIUS_KM / 180.0
-OMEGA = 7.2921159e-5                      # Earth's rotation, s^-1
-
-
-def wrap_longitude(lon):
-    """Longitude back into [-180, 180)."""
-    return (np.asarray(lon, np.float64) + 180.0) % 360.0 - 180.0
-
-
-def great_circle_km(lat0, lon0, lat1, lon1):
-    """Haversine distance in kilometres."""
-    p0, p1 = np.radians(lat0), np.radians(lat1)
-    dp = p1 - p0
-    dl = np.radians(np.asarray(lon1, np.float64) - np.asarray(lon0, np.float64))
-    h = np.sin(dp / 2) ** 2 + np.cos(p0) * np.cos(p1) * np.sin(dl / 2) ** 2
-    return 2.0 * EARTH_RADIUS_KM * np.arcsin(np.sqrt(np.clip(h, 0.0, 1.0)))
-
-
-def bearing_deg(lat0, lon0, lat1, lon1):
-    """Initial great-circle bearing from point 0 to point 1, degrees clockwise from north, in [0, 360)."""
-    p0, p1 = np.radians(lat0), np.radians(lat1)
-    dl = np.radians(np.asarray(lon1, np.float64) - np.asarray(lon0, np.float64))
-    x = np.sin(dl) * np.cos(p1)
-    y = np.cos(p0) * np.sin(p1) - np.sin(p0) * np.cos(p1) * np.cos(dl)
-    return np.degrees(np.arctan2(x, y)) % 360.0
-
-
-def destination(lat, lon, bearing, distance_km):
-    """The point ``distance_km`` along the great circle leaving (lat, lon) on ``bearing``; (lat, lon)."""
-    p, l0 = np.radians(lat), np.radians(lon)
-    b = np.radians(bearing)
-    d = np.asarray(distance_km, np.float64) / EARTH_RADIUS_KM
-    p1 = np.arcsin(np.clip(np.sin(p) * np.cos(d) + np.cos(p) * np.sin(d) * np.cos(b), -1.0, 1.0))
-    l1 = l0 + np.arctan2(np.sin(b) * np.sin(d) * np.cos(p), np.cos(d) - np.sin(p) * np.sin(p1))
-    return np.degrees(p1), wrap_longitude(np.degrees(l1))
-
-
-def move(lat, lon, east_km, north_km):
-    """Move by a local (east, north) displacement in km, as one great-circle step."""
-    east_km, north_km = np.asarray(east_km, np.float64), np.asarray(north_km, np.float64)
-    distance = np.hypot(east_km, north_km)
-    bearing = np.degrees(np.arctan2(east_km, north_km))
-    return destination(lat, lon, bearing, distance)
-
-
-def local_displacement_km(lat0, lon0, lat1, lon1):
-    """(east, north) km from point 0 to point 1 in point 0's azimuthal-equidistant frame (exact distance)."""
-    distance = great_circle_km(lat0, lon0, lat1, lon1)
-    b = np.radians(bearing_deg(lat0, lon0, lat1, lon1))
-    return distance * np.sin(b), distance * np.cos(b)
-
-
-def to_local(lat0, lon0, lat, lon):
-    """Azimuthal-equidistant (x east, y north) km of points around a centre -- alias of the displacement."""
-    return local_displacement_km(lat0, lon0, lat, lon)
-
-
-def from_local(lat0, lon0, x_km, y_km):
-    """Inverse of :func:`to_local`."""
-    return move(lat0, lon0, x_km, y_km)
-
-
-def velocity_from_positions(lat0, lon0, lat1, lon1, hours):
-    """Mean (east, north) motion in m/s that takes a storm from point 0 to point 1 in ``hours``."""
-    east, north = local_displacement_km(lat0, lon0, lat1, lon1)
-    scale = 1000.0 / (np.asarray(hours, np.float64) * 3600.0)
-    return east * scale, north * scale
-
-
-def coriolis(lat):
-    """f = 2 Omega sin(lat), s^-1."""
-    return 2.0 * OMEGA * np.sin(np.radians(lat))
-
-
-def beta(lat):
-    """df/dy = 2 Omega cos(lat) / R, m^-1 s^-1."""
-    return 2.0 * OMEGA * np.cos(np.radians(lat)) / (EARTH_RADIUS_KM * 1000.0)
-
-
-def hemisphere(lat):
-    """+1 north (and on the equator), -1 south."""
-    return np.where(np.asarray(lat) < 0.0, -1.0, 1.0)
-
-
-def rotate(east, north, degrees):
-    """Rotate a vector counter-clockwise (mathematical sense) by ``degrees``."""
-    a = np.radians(degrees)
-    c, s = np.cos(a), np.sin(a)
-    return c * east - s * north, s * east + c * north
-
-
-def along_cross_track(lat_init, lon_init, lat_truth, lon_truth, lat_fcst, lon_fcst):
-    """
-    NHC-style decomposition of a forecast error, km: along-track (positive = forecast ahead of the storm)
-    and cross-track (positive = forecast to the right of the storm's actual motion).
-
-    The reference direction is the actual motion from the initial position to the verifying position; for
-    a storm that did not move (under 10 km) the decomposition is undefined and NaN is returned.
-    """
-    te, tn = local_displacement_km(lat_init, lon_init, lat_truth, lon_truth)
-    fe, fn = local_displacement_km(lat_init, lon_init, lat_fcst, lon_fcst)
-    length = np.hypot(te, tn)
-    with np.errstate(invalid="ignore", divide="ignore"):
-        ue, un = te / length, tn / length
-    de, dn = fe - te, fn - tn
-    along = de * ue + dn * un
-    cross = de * un - dn * ue                 # right of motion is positive
-    bad = length < 10.0
-    return np.where(bad, np.nan, along), np.where(bad, np.nan, cross)
-
-
-def interpolate_track(hours, lat, lon, at_hours):
-    """
-    Positions at ``at_hours`` along a track given at ``hours``, interpolating along great circles in each
-    segment (exact for a constant-bearing segment, unlike linear interpolation of latitude and longitude).
-    """
-    hours = np.asarray(hours, np.float64)
-    at = np.atleast_1d(np.asarray(at_hours, np.float64))
-    out_lat, out_lon = np.full(at.shape, np.nan), np.full(at.shape, np.nan)
-    for k, h in enumerate(at):
-        if h < hours[0] - 1e-9 or h > hours[-1] + 1e-9:
-            continue
-        j = int(np.clip(np.searchsorted(hours, h, side="right") - 1, 0, len(hours) - 2))
-        span = hours[j + 1] - hours[j]
-        frac = 0.0 if span <= 0 else (h - hours[j]) / span
-        distance = great_circle_km(lat[j], lon[j], lat[j + 1], lon[j + 1])
-        b = bearing_deg(lat[j], lon[j], lat[j + 1], lon[j + 1])
-        out_lat[k], out_lon[k] = destination(lat[j], lon[j], b, frac * distance)
-    return out_lat, out_lon
-
-
-__all__ = ["EARTH_RADIUS_KM", "KM_PER_DEGREE", "OMEGA", "along_cross_track", "bearing_deg", "beta", "coriolis",
-           "destination", "from_local", "great_circle_km", "hemisphere", "interpolate_track",
-           "local_displacement_km", "move", "rotate", "to_local", "velocity_from_positions", "wrap_longitude"]

naturev1/cyclone/intensity.py

@@ -1,746 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Intensity without a neural network: three statistical-dynamical models that read the atmosphere along the
-*forecast track*, not just where the storm is now.
-
-The idea: an intensity forecast is a forecast of the conditions the storm will meet -- warmer or cooler water,
-more or less shear, drier air, land -- and the track forecast says where it will meet them. So every
-environmental predictor is sampled along the physics consensus track, hour by hour, from the analysis
-(:func:`environment_along_track`), with two corrections no reanalysis carries: the **cold wake** under a slow
-storm (:mod:`naturev1.cyclone.ocean`) lowers the sea-surface temperature the core feels, and **land and
-terrain** (:mod:`naturev1.cyclone.land`) are applied as decay after the fact.
-
-* :func:`shifor_intensity` -- SHIFOR (Jarvinen and Neumann 1979) rebuilt like CLIPER: climatology and
-  persistence (current wind, its 12- and 24-hour trends, position, season, motion), per basin, 1980-2014.
-* :func:`ships_intensity` -- SHIPS-style (DeMaria and Kaplan 1994): the change at each lead regressed on
-  predictors averaged along the track up to that lead -- potential intensity minus the current wind (the
-  room to grow), shear in two layers, mid-level humidity, effective ocean temperature, land, persistence.
-* :func:`lgem_intensity` -- LGEM-style (DeMaria 2009): ``dV/dt = kappa V - beta (V / V_pi)^n V`` integrated
-  hourly along the track, the growth rate ``kappa`` a linear function of the environment, the potential
-  intensity a hard ceiling the storm approaches logistically.
-
-Coefficients: SHIFOR on 1980-2014 best tracks; SHIPS and LGEM on the 2016/2017/2019 hindcast seasons -- never
-on the 2018/2020-2022 seasons the benchmark reports.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .geometry import great_circle_km, wrap_longitude
-from .land import apply_land_decay, land_along_track
-from .ocean import effective_sst
-
-KT_PER_MS = 1.0 / 0.514444
-SHIFOR_PREDICTORS = ("one", "wind", "dwind12", "dwind24", "lat", "lon", "season_s", "season_c", "u6", "v6", "wind2",
-                     "wind_lat")
-
-
-def _season_phase(case) -> float:
-    day = (np.datetime64(case.time, "D") - np.datetime64(str(case.time)[:4] + "-01-01", "D")).astype(int)
-    shift = 182 if case.lat < 0 else 0
-    return 2 * np.pi * ((day + shift) % 365) / 365.0
-
-
-def shifor_predictors(case) -> np.ndarray | None:
-    from .cliper import GROUPS, _motion
-
-    if not np.isfinite(case.wind_kt):
-        return None
-    w = case.history["wind"]
-    w12, w24 = w[-3], w[-5]
-    d12 = (case.wind_kt - w12) / 10.0 if np.isfinite(w12) else 0.0
-    d24 = (case.wind_kt - w24) / 10.0 if np.isfinite(w24) else d12
-    sign = -1.0 if case.lat < 0 else 1.0
-    m = _motion(case, -6, 0) or _motion(case, -12, 0) or (0.0, 0.0)
-    _, reference = GROUPS.get(case.basin, ("NA", -60.0))
-    phase = _season_phase(case)
-    wind = case.wind_kt / 100.0
-    lat = abs(case.lat) / 30.0
-    return np.array([1.0, wind, d12, d24, lat, wrap_longitude(case.lon - reference) / 60.0, np.sin(phase), np.cos(phase),
-                     m[0] / 20.0, sign * m[1] / 20.0, wind * wind, wind * lat])
-
-
-def fit_shifor(cases, leads, ridge: float = 1e-2) -> dict:
-    from .cliper import group_of
-
-    rows: dict[str, list] = {}
-    for c in cases:
-        x = shifor_predictors(c)
-        if x is None:
-            continue
-        target = np.where(c.truth["valid"] & np.isfinite(c.truth["wind"]), c.truth["wind"] - c.wind_kt, np.nan)
-        rows.setdefault(group_of(c), []).append((x, target))
-    table = {"leads": [int(h) for h in leads]}
-    for group, items in rows.items():
-        x = np.stack([i[0] for i in items])
-        y = np.stack([i[1] for i in items])
-        weights = np.full((len(leads), x.shape[1]), np.nan)
-        for k in range(len(leads)):
-            ok = np.isfinite(y[:, k])
-            if ok.sum() < 5 * x.shape[1]:
-                continue
-            a = x[ok]
-            gram = a.T @ a + ridge * ok.sum() * np.diag([0.0] + [1.0] * (x.shape[1] - 1))
-            weights[k] = np.linalg.solve(gram, a.T @ y[ok, k])
-        table[group] = weights.round(5).tolist()
-    return table
-
-
-def shifor_intensity(case, leads, table: dict | None = None) -> np.ndarray:
-    from .cliper import group_of
-
-    if table is None:
-        from .coefficients import SHIFOR as table
-    x = shifor_predictors(case)
-    out = np.full(len(leads), np.nan)
-    group = table.get(group_of(case))
-    if x is None or group is None:
-        return out
-    stored = list(table["leads"])
-    w = np.asarray(group, np.float64)
-    for k, lead in enumerate(leads):
-        if lead in stored:
-            out[k] = max(case.wind_kt + float(w[stored.index(lead)] @ x), 15.0)
-    return out
-
-
-# ------------------------------------------------------------------------------- along the track --
-
-def _relative_humidity(t_k: np.ndarray, q: np.ndarray, p_hpa: float) -> np.ndarray:
-    es = 6.112 * np.exp(17.67 * (t_k - 273.15) / (t_k - 29.65))
-    e = q * p_hpa / (0.622 + 0.378 * q)
-    return np.clip(e / es, 0.0, 1.2)
-
-
-def potential_intensity_at(env, lat, lon, sst_k) -> np.ndarray:
-    """Bister-Emanuel potential intensity (m/s, surface) at points, from the analysis column there."""
-    import torch
-
-    from ..thermo import potential_intensity
-
-    levels = [p for p in env.levels if p >= 100]
-    idx = [list(env.levels).index(p) for p in levels]
-    t = np.stack([env.sample(env.fields["t"][k], lat, lon) for k in idx], -1)
-    q = np.stack([env.sample(env.fields["q"][k], lat, lon) for k in idx], -1)
-    msl = env.sample(env.fields["msl"], lat, lon) / 100.0
-    out = potential_intensity(torch.tensor(np.asarray(sst_k, np.float64)), torch.tensor(msl),
-                              torch.tensor(np.asarray(levels, np.float64)), torch.tensor(t), torch.tensor(q))
-    return np.nan_to_num(out["vmax_ms"].numpy(), nan=0.0)
-
-
-def environment_along_track(env, env_clean, case, track: np.ndarray, leads, wind_guess_kt: np.ndarray | None = None,
-                            ocean=None) -> dict:
-    """
-    Hourly environment along the forecast track: effective SST (cold wake), potential intensity, shear (850-200
-    and 850-500, annulus 200-800 km), 700-500 hPa humidity, land and terrain, translation speed -- and, with an
-    :class:`naturev1.cyclone.ocean.OceanClimatology` (``ocean``), the depth of the 26 C isotherm and the heat potential
-    along the track, with the cold wake sized by that depth.
-    """
-    from .shear import annulus_profile
-
-    land = land_along_track(env, case.lat, case.lon, track, leads)
-    hours, la, lo = land["hours"], land["lat"], land["lon"]
-    step = np.gradient(hours)
-    dist = np.concatenate([[0.0], great_circle_km(la[:-1], lo[:-1], la[1:], lo[1:])])
-    speed = np.convolve(dist, np.ones(6) / 6.0, mode="same") / np.maximum(step, 1e-6) / 3.6
-    sst = env.sample(np.nan_to_num(env.fields["sst"], nan=float(np.nanmean(env.fields["sst"]))), la, lo)
-    wind = np.interp(hours, np.concatenate([[0.0], np.asarray(leads, float)]),
-                     np.concatenate([[case.wind_kt], wind_guess_kt if wind_guess_kt is not None else np.full(len(leads), case.wind_kt)]))
-    d26 = tchp = np.full(hours.size, np.nan)
-    power = None
-    if ocean is not None:
-        from . import coefficients
-
-        from .ocean import anomaly_adjusted_depth
-
-        sampled = ocean.sample(la, lo, case.time)
-        d26, tchp = sampled["d26_m"], sampled["tchp_kj_cm2"]
-        table = getattr(coefficients, "OCEAN", None) or {}
-        power = table.get("d26_power")
-        sst_clim = sampled.get("sst_c", np.full(hours.size, np.nan))
-        d26_used = anomaly_adjusted_depth(d26, sst, sst_clim, table.get("sst_anomaly_per_c", 0.0))
-    sst_eff = effective_sst(sst, wind, speed, hours, d26_used if ocean is not None else None, power)
-    sample_hours = np.arange(0.0, hours[-1] + 1e-9, 6.0)
-    pick = np.searchsorted(hours, sample_hours).clip(0, len(hours) - 1)
-    pi = potential_intensity_at(env, la[pick], lo[pick], sst_eff[pick]) * KT_PER_MS
-    # the potential intensity over the uncooled sea as well, so a different wake can be priced without the profiles
-    pi_warm = potential_intensity_at(env, la[pick], lo[pick], sst[pick]) * KT_PER_MS if ocean is not None else pi
-    shear_l, shear_m, rh = [], [], []
-    for j in pick:
-        prof = annulus_profile(env_clean, la[j], lo[j])
-        shear_l.append(np.hypot(prof[200][0] - prof[850][0], prof[200][1] - prof[850][1]))
-        shear_m.append(np.hypot(prof[500][0] - prof[850][0], prof[500][1] - prof[850][1]))
-        rhs = []
-        for p in (700, 600, 500):
-            k = list(env.levels).index(p)
-            rhs.append(float(env.sample(_relative_humidity(env.fields["t"][k], env.fields["q"][k], p), la[j], lo[j])))
-        rh.append(np.mean(rhs))
-    return {"hours": hours, "lat": la, "lon": lo, "land": land["land"], "height_m": land["height_m"], "speed_ms": speed,
-            "sst_k": sst, "sst_eff_k": sst_eff, "six_hours": sample_hours, "pi_kt": pi, "shear_ms": np.asarray(shear_l),
-            "shear_mid_ms": np.asarray(shear_m), "rh_mid": np.asarray(rh), "landfall_hour": land["landfall_hour"],
-            "d26_m": d26, "tchp_kj_cm2": tchp, "pi_warm_kt": pi_warm,
-            "sst_clim_c": sampled.get("sst_c", np.full(hours.size, np.nan)) if ocean is not None else np.full(hours.size, np.nan)}
-
-
-SHIPS_PREDICTORS = ("one", "wind", "dwind12", "potential", "potential2", "shear", "shear_mid", "rh", "sst", "land",
-                    "wind_shear", "lat", "speed", "heat_potential", "size", "has_size")
-
-
-def _size_features(case) -> list:
-    """The storm's observed 34-kt radius (mean quadrant, in units of 150 km) and whether it was reported: small storms
-    intensify faster, and the radius is in the best track for 2004 on (``Case.r34_nmi``, from IBTrACS or the b-deck)."""
-    r = getattr(case, "r34_nmi", float("nan"))
-    return [float(r) * 1.852 / 150.0 if np.isfinite(r) and r > 0 else 0.0, 1.0 if np.isfinite(r) and r > 0 else 0.0]
-
-
-def _heat_potential(along: dict, mask) -> float:
-    """Mean tropical-cyclone heat potential along the track (kJ/cm2) scaled to ~1 at 50, NaN -> 0 (unknown)."""
-    tchp = np.asarray(along.get("tchp_kj_cm2", np.full(np.count_nonzero(mask), np.nan)), np.float64)
-    if tchp.size != np.size(mask):
-        return 0.0
-    v = tchp[mask]
-    return float(np.nanmean(v)) / 50.0 if np.isfinite(v).any() else 0.0
-
-
-def ships_predictors(case, along: dict, lead: float) -> np.ndarray:
-    """Predictors averaged along the track from now to ``lead`` (the heat potential last: a table fitted without the
-    ocean climatology simply ignores it)."""
-    six = along["six_hours"]
-    use = six <= lead + 1e-9
-    hourly = along["hours"] <= lead + 1e-9
-    wind = case.wind_kt
-    w12 = case.history["wind"][-3]
-    pi = float(np.mean(along["pi_kt"][use]))
-    room = (pi - wind) / 50.0
-    shear = float(np.mean(along["shear_ms"][use])) / 10.0
-    return np.array([1.0, wind / 100.0, ((wind - w12) / 10.0) if np.isfinite(w12) else 0.0, room, room * abs(room),
-                     shear, float(np.mean(along["shear_mid_ms"][use])) / 10.0, float(np.mean(along["rh_mid"][use])),
-                     (float(np.mean(along["sst_eff_k"][hourly])) - 300.15) / 2.0, float(np.mean(along["land"][hourly])),
-                     wind / 100.0 * shear, abs(case.lat) / 30.0, float(np.mean(along["speed_ms"][hourly])) / 5.0,
-                     _heat_potential(along, hourly), *_size_features(case)])
-
-
-def _fit_length(features: np.ndarray, weights: np.ndarray) -> np.ndarray:
-    """Features cut or zero-padded to a table's length: newer predictors are always appended last."""
-    if features.size == weights.size:
-        return features
-    if features.size > weights.size:
-        return features[:weights.size]
-    return np.concatenate([features, np.zeros(weights.size - features.size)])
-
-
-def fit_ships(cases, alongs: list, leads, ridge: float = 3e-2) -> dict:
-    """Ridge regression of the wind change at each lead on :func:`ships_predictors`; one model for all basins."""
-    table = {"leads": [int(h) for h in leads], "weights": []}
-    for k, lead in enumerate(leads):
-        xs, ys = [], []
-        for c, a in zip(cases, alongs):
-            if a is None or not c.truth["valid"][k] or not np.isfinite(c.truth["wind"][k]) or not np.isfinite(c.wind_kt):
-                continue
-            xs.append(ships_predictors(c, a, lead))
-            ys.append(c.truth["wind"][k] - c.wind_kt)
-        x, y = np.asarray(xs), np.asarray(ys)
-        if len(y) < 10 * x.shape[1]:
-            table["weights"].append([float("nan")] * len(SHIPS_PREDICTORS))
-            continue
-        gram = x.T @ x + ridge * len(y) * np.diag([0.0] + [1.0] * (x.shape[1] - 1))
-        table["weights"].append(np.linalg.solve(gram, x.T @ y).round(5).tolist())
-    return table
-
-
-def ships_intensity(case, along: dict, leads, table: dict | None = None) -> np.ndarray:
-    if table is None:
-        from .coefficients import SHIPS as table
-    stored = list(table["leads"])
-    out = np.full(len(leads), np.nan)
-    for k, lead in enumerate(leads):
-        if lead in stored and along is not None:
-            w = np.asarray(table["weights"][stored.index(lead)], np.float64)
-            out[k] = max(case.wind_kt + float(w @ _fit_length(ships_predictors(case, along, lead), w)), 15.0)
-    return out
-
-
-#: LGEM: the exponent of the logistic ceiling, the damping rate (per hour) and the growth-rate coefficients
-#: (per hour) on [1, shear/10, rh, (sst_eff - 28.5 C)/2, (pi - v)/50].
-LGEM_N = 2.5
-LGEM_BETA = 1.0 / 24.0
-LGEM_KAPPA = (0.010, -0.012, 0.035, 0.006, 0.015)
-
-
-def lgem_table() -> tuple[np.ndarray, float, float]:
-    """The shipped LGEM fit (``coefficients.LGEM``) if there is one, else the hand-set defaults above."""
-    from . import coefficients
-
-    table = getattr(coefficients, "LGEM", None)
-    if table is None:
-        return np.asarray(LGEM_KAPPA, np.float64), LGEM_N, LGEM_BETA
-    return np.asarray(table["kappa"], np.float64), float(table["n"]), float(table["beta_per_h"])
-
-
-def lgem_intensity(case, along: dict, leads, kappa=None, n: float | None = None, beta: float | None = None) -> np.ndarray:
-    """Logistic growth to potential intensity, integrated hourly along the track; land decay applied after."""
-    fitted, fitted_n, fitted_beta = lgem_table()
-    kappa = fitted if kappa is None else np.asarray(kappa, np.float64)
-    n = fitted_n if n is None else n
-    beta = fitted_beta if beta is None else beta
-    hours = along["hours"]
-    six = along["six_hours"]
-    pi = np.maximum(np.interp(hours, six, along["pi_kt"]), 20.0)
-    shear = np.interp(hours, six, along["shear_ms"]) / 10.0
-    rh = np.interp(hours, six, along["rh_mid"])
-    sst = (along["sst_eff_k"] - 301.65) / 2.0
-    v = np.empty_like(hours)
-    v[0] = max(case.wind_kt, 15.0)
-    for k in range(1, len(hours)):
-        dt = hours[k] - hours[k - 1]
-        rate = kappa @ np.array([1.0, shear[k], rh[k], sst[k], (pi[k] - v[k - 1]) / 50.0])
-        growth = rate * v[k - 1] - beta * (v[k - 1] / pi[k]) ** n * v[k - 1]
-        v[k] = float(np.clip(v[k - 1] + dt * growth, 15.0, 200.0))
-    v = apply_land_decay(hours, v, along["land"], along["height_m"])
-    return np.interp(np.asarray(leads, float), hours, v, right=np.nan)
-
-
-def lgem_batch(start_kt: np.ndarray, alongs: list, leads, kappa=None, n: float = LGEM_N, beta: float = LGEM_BETA,
-               land: bool = True) -> np.ndarray:
-    """
-    :func:`lgem_intensity` for many storms at once (``(N, L)``): the environment arrays are stacked over cases on
-    the common hourly axis, so fitting the growth-rate coefficients over thousands of hindcasts takes seconds.
-    """
-    kappa = np.asarray(LGEM_KAPPA if kappa is None else kappa, np.float64)
-    hours = alongs[0]["hours"]
-    t = len(hours)
-    six = alongs[0]["six_hours"]
-
-    def stack(key, six_hourly):
-        rows = []
-        for a in alongs:
-            x = np.asarray(a[key], np.float64)
-            x = np.interp(hours, six, x) if six_hourly else x
-            rows.append(x[:t] if x.size >= t else np.pad(x, (0, t - x.size), mode="edge"))
-        return np.stack(rows)
-
-    pi = np.maximum(stack("pi_kt", True), 20.0)
-    shear = stack("shear_ms", True) / 10.0
-    rh = stack("rh_mid", True)
-    sst = (stack("sst_eff_k", False) - 301.65) / 2.0
-    v = np.empty((len(alongs), t))
-    v[:, 0] = np.maximum(np.asarray(start_kt, np.float64), 15.0)
-    for k in range(1, t):
-        dt = hours[k] - hours[k - 1]
-        rate = kappa[0] + kappa[1] * shear[:, k] + kappa[2] * rh[:, k] + kappa[3] * sst[:, k] + kappa[4] * (pi[:, k] - v[:, k - 1]) / 50.0
-        growth = rate * v[:, k - 1] - beta * (v[:, k - 1] / pi[:, k]) ** n * v[:, k - 1]
-        v[:, k] = np.clip(v[:, k - 1] + dt * growth, 15.0, 200.0)
-    if land:
-        lands, heights = stack("land", False), stack("height_m", False)
-        v = np.stack([apply_land_decay(hours, v[i], lands[i], heights[i]) for i in range(len(alongs))])
-    idx = [int(np.argmin(np.abs(hours - h))) for h in leads]
-    return v[:, idx]
-
-
-def fit_lgem(cases, alongs: list, leads, start=None, iterations: int = 300) -> np.ndarray:
-    """Growth-rate coefficients minimising the mean absolute wind error over all leads (Nelder-Mead)."""
-    keep = [i for i, a in enumerate(alongs) if a is not None and np.isfinite(cases[i].wind_kt)]
-    al = [alongs[i] for i in keep]
-    start_kt = np.array([cases[i].wind_kt for i in keep])
-    truth = np.stack([cases[i].truth["wind"] for i in keep])
-    valid = np.stack([cases[i].truth["valid"] for i in keep]) & np.isfinite(truth)
-
-    def loss(k):
-        pred = lgem_batch(start_kt, al, leads, k, land=False)
-        return float(np.mean(np.abs(pred - truth)[valid]))
-
-    x0 = np.asarray(LGEM_KAPPA if start is None else start, np.float64)
-    simplex = [x0] + [x0 + np.eye(len(x0))[j] * (0.5 * abs(x0[j]) + 0.005) for j in range(len(x0))]
-    values = [loss(x) for x in simplex]
-    for _ in range(iterations):
-        order = np.argsort(values)
-        simplex = [simplex[i] for i in order]
-        values = [values[i] for i in order]
-        centroid = np.mean(simplex[:-1], axis=0)
-        reflected = centroid + (centroid - simplex[-1])
-        fr = loss(reflected)
-        if fr < values[0]:
-            expanded = centroid + 2.0 * (centroid - simplex[-1])
-            fe = loss(expanded)
-            simplex[-1], values[-1] = (expanded, fe) if fe < fr else (reflected, fr)
-        elif fr < values[-2]:
-            simplex[-1], values[-1] = reflected, fr
-        else:
-            contracted = centroid + 0.5 * (simplex[-1] - centroid)
-            fc = loss(contracted)
-            if fc < values[-1]:
-                simplex[-1], values[-1] = contracted, fc
-            else:
-                simplex = [simplex[0] + 0.5 * (x - simplex[0]) for x in simplex]
-                values = [loss(x) for x in simplex]
-    return simplex[int(np.argmin(values))]
-
-
-def decay_along(case, along: dict, leads, water_kt: np.ndarray) -> np.ndarray:
-    """Apply inland and terrain decay to an over-water forecast given at ``leads``."""
-    hours = along["hours"]
-    water = np.interp(hours, np.concatenate([[0.0], np.asarray(leads, float)]), np.concatenate([[case.wind_kt], water_kt]))
-    decayed = apply_land_decay(hours, water, along["land"], along["height_m"])
-    return np.interp(np.asarray(leads, float), hours, decayed, right=np.nan)
-
-
-#: The trend member's memory (hours): how long a storm keeps intensifying (or weakening) the way it has been.
-TREND_TAU_H = 24.0
-
-
-def recent_change(case, hours: int = 24) -> float:
-    """Intensity change (kt) over the last ``hours`` from the best-track history (NaN when unknown)."""
-    from .data import HISTORY_HOURS
-
-    if -hours not in HISTORY_HOURS:
-        return float("nan")
-    past = case.history["wind"][HISTORY_HOURS.index(-hours)]
-    return float(case.wind_kt - past) if np.isfinite(past) else float("nan")
-
-
-def trend_intensity(case, along: dict, leads, tau_h: float | None = None) -> np.ndarray:
-    """
-    The storm keeps doing what it has been doing: the last 24 hours' change continued with an e-folding memory of
-    ``tau_h`` (``V0 + r tau (1 - exp(-t / tau))``), never above the potential intensity along the track, then land and
-    terrain decay. This is the member that can follow a storm through rapid intensification, which the regressions
-    (built to minimise the average error) pull back toward the mean.
-    """
-    from . import coefficients
-
-    tau = tau_h if tau_h is not None else getattr(coefficients, "TREND", {}).get("tau_h", TREND_TAU_H)
-    change = recent_change(case, 24)
-    if not np.isfinite(change):
-        change = 2.0 * recent_change(case, 12) if np.isfinite(recent_change(case, 12)) else 0.0
-    rate = change / 24.0
-    hours = along["hours"]
-    path = case.wind_kt + rate * tau * (1.0 - np.exp(-hours / tau))
-    pi = np.interp(hours, along["six_hours"], along["pi_kt"])
-    path = np.where(rate > 0, np.minimum(path, np.maximum(pi, case.wind_kt)), path)
-    path = apply_land_decay(hours, np.maximum(path, 15.0), along["land"], along["height_m"])
-    return np.interp(np.asarray(leads, float), hours, path, right=np.nan)
-
-
-#: Rapid intensification (+30 kt in 24 h): predictor names, in order.
-RI_FEATURES = ("one", "dv12", "dv24", "wind", "headroom", "shear", "rh", "sst", "lat", "land24")
-
-
-#: With a dynamical model's forecast: its central-pressure deficit change by 24 and 48 h, and whether it was there.
-RI_MODEL_FEATURES = ("model_dp24", "model_dp48", "has_model")
-#: With the ocean climatology: the heat potential over the first 24 hours (kJ/cm2 / 50) and the 26 C depth (m / 50).
-RI_OCEAN_FEATURES = ("heat_potential", "warm_depth")
-#: The storm's observed 34-kt radius (units of 150 km) and whether it was reported.
-RI_SIZE_FEATURES = ("size", "has_size")
-
-
-def ri_features(case, along: dict, model_dp=None, leads=None) -> np.ndarray:
-    """
-    SHIPS-RII-style predictors over the first 24 hours along the forecast track; with ``model_dp`` (the models' mean
-    change in central-pressure deficit at the standard leads, hPa, negative = deepening, from
-    :func:`model_deficit_change`) three more: the deepening by 24 h, by 48 h, and that a model was there.
-    """
-    h = along["hours"]
-    six = along["six_hours"]
-    first = six <= 24.0 + 1e-9
-    pi = float(np.nanmean(np.asarray(along["pi_kt"])[first]))
-    dv12, dv24 = recent_change(case, 12), recent_change(case, 24)
-    base = np.array([1.0, np.nan_to_num(dv12) / 10.0, np.nan_to_num(dv24) / 10.0, case.wind_kt / 50.0,
-                     (pi - case.wind_kt) / 50.0, float(np.nanmean(np.asarray(along["shear_ms"])[first])) / 10.0,
-                     float(np.nanmean(np.asarray(along["rh_mid"])[first])),
-                     (float(np.nanmean(np.asarray(along["sst_eff_k"])[h <= 24.0])) - 301.65) / 2.0,
-                     abs(case.lat) / 20.0, float(np.mean(np.asarray(along["land"])[h <= 24.0]))])
-    from .data import LEADS
-
-    if model_dp is None:
-        model = np.zeros(3)
-    else:
-        dp = np.asarray(model_dp, np.float64)
-        L = np.asarray(leads if leads is not None else LEADS, np.float64)
-        k24, k48 = int(np.argmin(np.abs(L - 24.0))), int(np.argmin(np.abs(L - 48.0)))
-        have = np.isfinite(dp[k24])
-        model = np.array([np.nan_to_num(-dp[k24]) / 10.0 if have else 0.0, np.nan_to_num(-dp[k48]) / 20.0 if have else 0.0, float(have)])
-    first_day = h <= 24.0
-    tchp = np.asarray(along.get("tchp_kj_cm2", np.full(h.size, np.nan)), np.float64)
-    d26 = np.asarray(along.get("d26_m", np.full(h.size, np.nan)), np.float64)
-    ocean = np.array([float(np.nanmean(tchp[first_day])) / 50.0 if np.isfinite(tchp[first_day]).any() else 0.0,
-                      float(np.nanmean(d26[first_day])) / 50.0 if np.isfinite(d26[first_day]).any() else 0.0])
-    return np.concatenate([base, model, ocean, _size_features(case)])
-
-
-def model_deficit_change(extras: dict | list | None, leads) -> np.ndarray | None:
-    """
-    ``(L,)`` the models' mean change in central-pressure deficit (central minus environmental pressure, hPa) from
-    the analysis to each lead -- negative when the model deepens its storm -- from the ``extras`` of
-    :func:`naturev1.swarm.models.fetch_models` (each with ``hours``, ``msl_min_hpa``, ``msl_env_hpa``). None without any.
-    """
-    if not extras:
-        return None
-    rows = []
-    for e in (extras.values() if isinstance(extras, dict) else extras):
-        e = e.get("extras", e)
-        hours, pmin, penv = np.asarray(e["hours"], float), np.asarray(e["msl_min_hpa"], float), np.asarray(e["msl_env_hpa"], float)
-        deficit = pmin - penv
-        if hours.size == 0 or not np.isfinite(deficit[0]):
-            continue
-        at = np.array([deficit[np.argmin(np.abs(hours - h))] if np.any(np.abs(hours - h) < 1e-6) else np.nan for h in leads])
-        rows.append(at - deficit[0])
-    if not rows:
-        return None
-    return np.nanmean(np.stack(rows), axis=0) if len(rows) > 1 else rows[0]
-
-
-def model_trend_intensity(case, along: dict, leads, model_dp, table: dict | None = None) -> np.ndarray:
-    """
-    The dynamical models' own intensification, as an intensity member: ``V0 + k_lead * deepening`` (kt per hPa of
-    central-pressure-deficit change fitted per lead on the tuning seasons, ``coefficients.MODEL_INTENSITY``), capped
-    at the potential intensity, then land and terrain decay. A model that deepens its storm by 30 hPa is saying
-    something the statistical members cannot.
-    """
-    if table is None:
-        from . import coefficients
-
-        table = getattr(coefficients, "MODEL_INTENSITY", None) or {"leads": list(leads), "kt_per_hpa": [1.0] * len(leads)}
-    hours = along["hours"]
-    k = np.interp(np.asarray(leads, float), table["leads"], table["kt_per_hpa"])
-    dp = np.asarray(model_dp, np.float64)
-    water = case.wind_kt + k * (-np.nan_to_num(dp))
-    pi = np.interp(np.asarray(leads, float), along["six_hours"], along["pi_kt"])
-    water = np.where(np.isfinite(dp), np.minimum(water, np.maximum(pi, case.wind_kt)), np.nan)
-    knots = np.concatenate([[0.0], np.asarray(leads, float)])
-    path = np.interp(hours, knots, np.concatenate([[case.wind_kt], np.nan_to_num(water, nan=case.wind_kt)]))
-    path = apply_land_decay(hours, np.maximum(path, 15.0), along["land"], along["height_m"])
-    return np.where(np.isfinite(water), np.interp(np.asarray(leads, float), hours, path), np.nan)
-
-
-def fit_ri_path(cases, alongs: list, leads, threshold_kt: float = 30.0) -> dict:
-    """
-    The intensity path of the storms that *did* intensify rapidly: the mean and 75th percentile of their change from
-    the analysis at each lead (kt), over the tuning seasons' cases whose 24-hour change reached ``threshold_kt``.
-    """
-    from .data import LEADS
-
-    k24 = list(LEADS).index(24)
-    rows = []
-    for c, a in zip(cases, alongs):
-        if a is None or not c.truth["valid"][k24] or not np.isfinite(c.truth["wind"][k24]) or not np.isfinite(c.wind_kt):
-            continue
-        if c.truth["wind"][k24] - c.wind_kt >= threshold_kt:
-            rows.append(np.where(c.truth["valid"], c.truth["wind"], np.nan) - c.wind_kt)
-    rows = np.asarray(rows)
-    return {"leads": [int(h) for h in leads], "threshold_kt": threshold_kt, "cases": int(rows.shape[0]),
-            "mean_change_kt": [round(float(np.nanmean(rows[:, k])), 2) for k in range(len(leads))],
-            "p75_change_kt": [round(float(np.nanquantile(rows[:, k], 0.75)), 2) for k in range(len(leads))]}
-
-
-def ri_scenario_intensity(case, along: dict, leads, table: dict | None = None, which: str = "mean_change_kt") -> np.ndarray:
-    """
-    The intensity *if the storm intensifies rapidly*: the analysis plus the rapid intensifiers' mean change at each
-    lead (``coefficients.RI_PATH``), capped at the potential intensity along the track, then land and terrain decay.
-    Issued beside the consensus with its probability (``ri_probability``): the consensus is the expected value, this
-    is the branch a parish cannot afford to ignore when the probability is real.
-    """
-    if table is None:
-        from . import coefficients
-
-        table = getattr(coefficients, "RI_PATH", None)
-        if table is None:
-            return np.full(len(leads), np.nan)
-    hours = along["hours"]
-    change = np.interp(np.asarray(leads, float), table["leads"], table[which])
-    water = case.wind_kt + change
-    pi = np.interp(np.asarray(leads, float), along["six_hours"], along["pi_kt"])
-    water = np.minimum(water, np.maximum(pi, case.wind_kt))
-    knots = np.concatenate([[0.0], np.asarray(leads, float)])
-    path = np.interp(hours, knots, np.concatenate([[case.wind_kt], water]))
-    path = apply_land_decay(hours, np.maximum(path, 15.0), along["land"], along["height_m"])
-    return np.interp(np.asarray(leads, float), hours, path)
-
-
-def category_probabilities(intensity: np.ndarray, regime: str, table: dict | None = None, ri_probability: float | None = None,
-                           ri_intensity: np.ndarray | None = None) -> dict:
-    """
-    ``{"thresholds_kt": [...], "probability": (L, T)}`` -- P(intensity >= each threshold) at each lead, from the
-    forecast plus the empirical distribution of the consensus's out-of-sample errors on the tuning seasons
-    (``coefficients.INTENSITY_SPREAD``: 25 quantiles per lead, separately for the normal and the rapid regime).
-    """
-    if table is None:
-        from . import coefficients
-
-        table = getattr(coefficients, "INTENSITY_SPREAD", None)
-    if table is None:
-        return {}
-    q = np.asarray(table["quantiles"].get(regime, table["quantiles"]["normal"]), np.float64)        # (L, 25)
-    thresholds = np.asarray(table.get("thresholds_kt", (64, 96, 113, 137)), np.float64)
-    v = np.asarray(intensity, np.float64)
-    samples = v[:, None] + q                                                                        # (L, 25)
-    prob = np.stack([(samples >= t).mean(1) for t in thresholds], -1)
-    mixed = table.get("ri_mixture") and ri_probability is not None and ri_intensity is not None and np.isfinite(ri_intensity).any()
-    if mixed:
-        # the rapid-intensification branch: with probability P(RI) the storm follows the rapid intensifiers' path,
-        # spread by the rapid regime's own error quantiles (switched on by the table only where it scored better)
-        qr = np.asarray(table["quantiles"]["rapid"], np.float64)
-        branch = np.asarray(ri_intensity, np.float64)[:, None] + qr
-        prob_ri = np.stack([(branch >= t).mean(1) for t in thresholds], -1)
-        p = float(np.clip(ri_probability, 0.0, 1.0))
-        prob = (1.0 - p) * prob + p * np.where(np.isfinite(prob_ri), prob_ri, prob)
-    prob[~np.isfinite(v)] = np.nan
-    return {"thresholds_kt": thresholds.tolist(), "probability": prob, "ri_mixture": bool(mixed)}
-
-
-def fit_ri(cases, alongs: list, threshold_kt: float = 30.0, l2: float = 1e-2, iterations: int = 30,
-           model_dp: dict | None = None, n_features: int | None = None) -> dict:
-    """Logistic regression for P(intensity rises by >= ``threshold_kt`` in 24 h), by Newton's method, on
-    :func:`ri_features` (``model_dp``: ``{case.key: (L,) deficit change}`` when the models' deepening is a predictor;
-    ``n_features`` cuts the predictor list, e.g. 10 for the environment alone)."""
-    from .data import LEADS
-
-    k24 = list(LEADS).index(24)
-    x, y = [], []
-    for c, a in zip(cases, alongs):
-        if a is None or not c.truth["valid"][k24] or not np.isfinite(c.truth["wind"][k24]):
-            continue
-        f = ri_features(c, a, None if model_dp is None else model_dp.get(c.key))
-        if n_features is not None:
-            f = _fit_length(f, np.zeros(n_features))
-        if np.isfinite(f).all():
-            x.append(f)
-            y.append(float(c.truth["wind"][k24] - c.wind_kt >= threshold_kt))
-    x, y = np.asarray(x), np.asarray(y)
-    w = np.zeros(x.shape[1])
-    reg = l2 * len(y) * np.diag([0.0] + [1.0] * (x.shape[1] - 1))
-    for _ in range(iterations):
-        p = 1.0 / (1.0 + np.exp(-x @ w))
-        grad = x.T @ (p - y) + reg @ w
-        hess = (x * (p * (1 - p))[:, None]).T @ x + reg
-        w = w - np.linalg.solve(hess, grad)
-    names = list(RI_FEATURES) + list(RI_MODEL_FEATURES) + list(RI_OCEAN_FEATURES) + list(RI_SIZE_FEATURES)
-    return {"features": names[:x.shape[1]], "threshold_kt": threshold_kt, "weights": w.round(5).tolist(),
-            "base_rate": float(y.mean()), "cases": int(len(y))}
-
-
-def ri_probability(case, along: dict, table: dict | None = None, model_dp=None, leads=None) -> float:
-    """P(+30 kt in 24 h) for a storm on its forecast track (``coefficients.RI`` by default; a table fitted with the
-    model-deepening predictors uses them when ``model_dp`` is given, and counts the model as absent otherwise)."""
-    if table is None:
-        from .coefficients import RI as table
-    w = np.asarray(table["weights"], np.float64)
-    f = _fit_length(ri_features(case, along, model_dp, leads), w)    # a table fitted with fewer predictors ignores the rest
-    if not np.isfinite(f).all():
-        return float(table.get("base_rate", 0.05))
-    return float(1.0 / (1.0 + np.exp(-w @ f)))
-
-
-
-#: Predictors of the peak-intensity logistic (``coefficients.PEAK``), after the intercept: the analysis intensity, the
-#: consensus's rise and maximum, the warm-ocean potential-intensity headroom over 72 h, mean ocean heat content, shear
-#: and mid-level humidity over 48 h, P(RI) and its logit, the model's 24 h deepening and whether there is one, the
-#: share of the first 72 h over land, latitude.
-PEAK_FEATURES = ("one", "v0", "cons_rise", "cons_max", "headroom72", "tchp48", "shear48", "rh48", "p_ri", "logit_p", "dp24", "has_dp",
-                 "land72", "abslat")
-
-
-def _series_upto(along: dict, key: str, upto_h: float) -> np.ndarray:
-    v = np.asarray(along[key], np.float64)
-    t = np.asarray(along["six_hours"] if v.size == len(along["six_hours"]) else along["hours"], np.float64)
-    return v[t <= upto_h]
-
-
-def peak_features(case, along: dict, consensus_kt, ri_probability: float, model_dp=None, leads=None) -> np.ndarray:
-    """The :data:`PEAK_FEATURES` row for one case (raw, before the table's standardisation)."""
-    from .data import LEADS
-
-    cv = np.asarray(consensus_kt, np.float64)
-    p = float(np.clip(ri_probability if ri_probability is not None and np.isfinite(ri_probability) else 0.05, 1e-3, 1 - 1e-3))
-    pi = _series_upto(along, "pi_warm_kt" if "pi_warm_kt" in along else "pi_kt", 72.0)
-    L = np.asarray(leads if leads is not None else LEADS, np.float64)
-    k24 = int(np.argmin(np.abs(L - 24.0)))
-    dp = np.asarray(model_dp, np.float64) if model_dp is not None else np.full(L.size, np.nan)
-    has_dp = bool(dp.size > k24 and np.isfinite(dp[k24]))
-    tchp = _series_upto(along, "tchp_kj_cm2", 48.0) if "tchp_kj_cm2" in along else np.array([np.nan])
-    with np.errstate(all="ignore"):
-        row = [1.0, case.wind_kt, np.nanmax(cv) - case.wind_kt, np.nanmax(cv), np.nanmax(pi) - case.wind_kt, np.nanmean(tchp),
-               np.nanmean(_series_upto(along, "shear_ms", 48.0)), np.nanmean(_series_upto(along, "rh_mid", 48.0)), p, np.log(p / (1 - p)),
-               dp[k24] if has_dp else 0.0, float(has_dp), np.nanmean(_series_upto(along, "land", 72.0)), abs(case.lat)]
-    return np.nan_to_num(np.asarray(row, np.float64))
-
-
-def peak_probability(case, along: dict, consensus_kt, ri_probability: float, model_dp=None, table: dict | None = None, leads=None) -> dict:
-    """
-    ``{"thresholds_kt": [64, 96, 113, 137], "probability": [...]}`` -- the probability that the storm's **peak**
-    intensity within the forecast window reaches each threshold (hurricane, major, category 4, category 5): a logistic
-    on :data:`PEAK_FEATURES` fitted on the tuning seasons (``coefficients.PEAK``). This is the question a point
-    forecast cannot answer: the consensus is the expected intensity, and for the storms that do explode it sits
-    30 kt under their peak; this says how likely the explosion is. 1 where the storm is already at the threshold.
-    """
-    if table is None:
-        from . import coefficients
-
-        table = getattr(coefficients, "PEAK", None)
-    if not table:
-        return {}
-    x = peak_features(case, along, consensus_kt, ri_probability, model_dp, leads)
-    mu, sd = np.asarray(table["mean"], np.float64), np.asarray(table["std"], np.float64)
-    z = np.concatenate([x[:1], (x[1:] - mu) / np.where(sd > 1e-9, sd, 1.0)])
-    out = []
-    for thr in table["thresholds_kt"]:
-        w = np.asarray(table["weights"][str(int(thr))], np.float64)
-        out.append(1.0 if case.wind_kt >= thr else float(1.0 / (1.0 + np.exp(-float(z @ w)))))
-    return {"thresholds_kt": [float(t) for t in table["thresholds_kt"]], "probability": out}
-
-
-def _peak_row(case, along: dict, consensus_kt, ri_probability, model_dp, intensity_if_ri, table: dict, leads=None) -> np.ndarray:
-    """The standardised PEAK features plus the rapid-intensification path's rise, as the peak-quantile tables were fitted."""
-    x = peak_features(case, along, consensus_kt, ri_probability, model_dp, leads)
-    mu, sd = np.asarray(table["mean"], np.float64), np.asarray(table["std"], np.float64)
-    n = x.size - 1
-    z = np.concatenate([x[:1], (x[1:] - mu[:n]) / np.where(sd[:n] > 1e-9, sd[:n], 1.0)])
-    scen = np.asarray(intensity_if_ri, np.float64) if intensity_if_ri is not None else np.array([np.nan])
-    rise = (np.nanmax(scen) - case.wind_kt) if np.isfinite(scen).any() else 0.0
-    return np.append(z, (rise - mu[n]) / (sd[n] if sd[n] > 1e-9 else 1.0))
-
-
-def peak_quantiles(case, along: dict, consensus_kt, ri_probability, model_dp=None, intensity_if_ri=None, table: dict | None = None,
-                   leads=None) -> dict:
-    """
-    ``{"levels": [0.5, 0.75, 0.9, 0.95], "peak_kt": [...]}`` -- calibrated quantiles of the storm's **peak** intensity
-    within the forecast window (``coefficients.PEAK_QUANTILES``: linear pinball-loss fits on the tuning seasons). The
-    point forecast cannot reach an explosive storm's top end and should not try; the 90% quantile can: on the held-out
-    storms that reached 137 kt it sits 4 kt above their true peak where the consensus maximum sits 37 kt below, with
-    91% of all held-out peaks under it. Quantiles are made monotone at prediction time.
-    """
-    if table is None:
-        from . import coefficients
-
-        table = getattr(coefficients, "PEAK_QUANTILES", None)
-    if not table:
-        return {}
-    z = _peak_row(case, along, consensus_kt, ri_probability, model_dp, intensity_if_ri, table, leads)
-    levels = sorted(float(q) for q in table["quantiles"])
-    rise = np.maximum.accumulate(np.array([float(z @ np.asarray(table["quantiles"][str(q)], np.float64)) for q in levels]))
-    return {"levels": levels, "peak_kt": [float(np.clip(case.wind_kt + r, 15.0, 200.0)) for r in rise]}
-
-
-def peak_if_ri(case, along: dict, consensus_kt, ri_probability, model_dp=None, intensity_if_ri=None, table: dict | None = None,
-               leads=None) -> float:
-    """
-    E[peak within the window | the storm intensifies rapidly], kt (``coefficients.PEAK_IF_RI``, a ridge fit on the
-    tuning seasons' rapid intensifiers): unbiased on the held-out storms that did go rapid (+0.6 kt, MAE 13) where the
-    rapid-intensification path's peak sat 17 kt low. To be read with ``ri_probability``, never as the forecast: on the
-    storms that do not go rapid it runs 35 kt high.
-    """
-    if table is None:
-        from . import coefficients
-
-        table = getattr(coefficients, "PEAK_IF_RI", None)
-    if not table:
-        return float("nan")
-    z = _peak_row(case, along, consensus_kt, ri_probability, model_dp, intensity_if_ri, table, leads)
-    return float(np.clip(case.wind_kt + float(z @ np.asarray(table["weights"], np.float64)), 15.0, 200.0))
-
-__all__ = ["LGEM_KAPPA", "PEAK_FEATURES", "RI_FEATURES", "RI_MODEL_FEATURES", "RI_OCEAN_FEATURES", "RI_SIZE_FEATURES", "SHIFOR_PREDICTORS",
-           "SHIPS_PREDICTORS",
-           "TREND_TAU_H",
-           "category_probabilities", "decay_along", "environment_along_track", "fit_ri", "fit_ri_path", "model_deficit_change",
-           "model_trend_intensity", "peak_features", "peak_if_ri", "peak_probability", "peak_quantiles", "recent_change", "ri_features", "ri_probability", "ri_scenario_intensity", "trend_intensity",
-           "fit_lgem", "fit_shifor", "fit_ships", "lgem_batch", "lgem_intensity", "lgem_table", "potential_intensity_at", "shifor_intensity",
-           "shifor_predictors", "ships_intensity", "ships_predictors"]

naturev1/cyclone/kalman.py

@@ -1,137 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-How the storm is moving right now, estimated rather than read off two fixes.
-
-The idea: extrapolation is nearly unbeatable at 6-12 hours because the current motion is the best
-predictor there is -- but extrapolation *measures* that motion with two noisy best-track fixes. A best-track
-position carries 20-50 km of uncertainty (more for a depression seen only by satellite), so a 12-hour motion
-from two fixes is uncertain by several km/h before the forecast even starts. A Kalman filter over the last 48
-hours of fixes, with a constant-acceleration motion model, estimates position, velocity and acceleration
-jointly and weighs each fix by how much it can be trusted. Two refinements:
-
-* **Robust updates** (Huber): a fix that disagrees with the motion by more than a few standard deviations
-  -- a centre reformation, a relocated depression -- is down-weighted instead of dragging the velocity.
-* **Damped acceleration** forecast (Gardner-McKenzie damped trend): the measured turn or speed-up carries
-  on but fades with an e-folding time, because storms that are accelerating now rarely keep accelerating for
-  days.
-
-All in the storm-centred azimuthal-equidistant frame, km and hours.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass
-
-import numpy as np
-
-from .geometry import from_local, to_local
-
-#: Per-axis position uncertainty of a best-track fix, km, by status (after Landsea and Franklin 2013).
-FIX_SIGMA_KM = {"HU": 15.0, "TS": 24.0, "SS": 30.0, "TD": 32.0}
-#: White-jerk process noise, km^2 h^-5 (tuned on the 2016/2017/2019 seasons only).
-PROCESS_NOISE = 2.0e-4
-#: Huber threshold, standard deviations.
-HUBER = 2.0
-#: E-folding time of the measured acceleration in a forecast, hours.
-ACCELERATION_TAU_H = 12.0
-
-
-@dataclass
-class MotionEstimate:
-    position_km: np.ndarray        # (2,) filtered offset from the best-track fix now (x east, y north)
-    velocity_kmh: np.ndarray       # (2,)
-    acceleration_kmh2: np.ndarray  # (2,)
-    covariance: np.ndarray         # (6, 6) state covariance
-    fixes: int
-
-    @property
-    def velocity_ms(self) -> np.ndarray:
-        return self.velocity_kmh / 3.6
-
-    @property
-    def speed_sigma_kmh(self) -> float:
-        return float(np.sqrt(0.5 * (self.covariance[2, 2] + self.covariance[3, 3])))
-
-
-def _transition(dt: float) -> np.ndarray:
-    f = np.eye(6)
-    for axis in range(2):
-        p, v, a = axis, 2 + axis, 4 + axis
-        f[p, v], f[p, a], f[v, a] = dt, 0.5 * dt * dt, dt
-    return f
-
-
-def _process(dt: float, q: float) -> np.ndarray:
-    block = q * np.array([[dt ** 5 / 20, dt ** 4 / 8, dt ** 3 / 6],
-                          [dt ** 4 / 8, dt ** 3 / 3, dt ** 2 / 2],
-                          [dt ** 3 / 6, dt ** 2 / 2, dt]])
-    out = np.zeros((6, 6))
-    for axis in range(2):
-        idx = [axis, 2 + axis, 4 + axis]
-        out[np.ix_(idx, idx)] = block
-    return out
-
-
-def estimate_motion(case, process_noise: float | None = None, huber: float | None = None) -> MotionEstimate | None:
-    """Filter the storm's last 48 hours of fixes into position, velocity and acceleration now."""
-    process_noise = PROCESS_NOISE if process_noise is None else process_noise
-    huber = HUBER if huber is None else huber
-    from .data import HISTORY_HOURS
-
-    hours = np.asarray(HISTORY_HOURS, np.float64)
-    lat, lon = case.history["lat"], case.history["lon"]
-    ok = np.isfinite(lat) & np.isfinite(lon)
-    if ok.sum() < 2:
-        return None
-    x, y = to_local(case.lat, case.lon, lat[ok], lon[ok])
-    t = hours[ok]
-    sigma = FIX_SIGMA_KM.get(case.status, 28.0)
-    r = np.eye(2) * sigma ** 2
-    h = np.zeros((2, 6))
-    h[0, 0] = h[1, 1] = 1.0
-    # Start at the first fix with a vague velocity.
-    state = np.array([x[0], y[0], 0.0, 0.0, 0.0, 0.0])
-    cov = np.diag([sigma ** 2, sigma ** 2, 30.0 ** 2, 30.0 ** 2, 2.0 ** 2, 2.0 ** 2])
-    if len(t) > 1:
-        dt0 = t[1] - t[0]
-        state[2:4] = [(x[1] - x[0]) / dt0, (y[1] - y[0]) / dt0]
-    previous = t[0]
-    for k in range(len(t)):
-        dt = t[k] - previous
-        if dt > 0:
-            f = _transition(dt)
-            state = f @ state
-            cov = f @ cov @ f.T + _process(dt, process_noise)
-        previous = t[k]
-        innovation = np.array([x[k], y[k]]) - h @ state
-        s = h @ cov @ h.T + r
-        distance = float(np.sqrt(innovation @ np.linalg.solve(s, innovation)))
-        inflate = max(1.0, distance / huber)
-        s = h @ cov @ h.T + r * inflate
-        gain = cov @ h.T @ np.linalg.inv(s)
-        state = state + gain @ innovation
-        cov = (np.eye(6) - gain @ h) @ cov
-    return MotionEstimate(state[:2], state[2:4], state[4:6], cov, int(ok.sum()))
-
-
-def damped_offsets(estimate: MotionEstimate, leads, tau_h: float | None = None,
-                   from_fix: bool = True) -> np.ndarray:
-    """``(L, 2)`` (x, y) km offsets at each lead, the acceleration fading with ``tau_h``."""
-    tau_h = ACCELERATION_TAU_H if tau_h is None else tau_h
-    t = np.asarray(leads, np.float64)[:, None]
-    decay = tau_h * (t - tau_h * (1.0 - np.exp(-t / tau_h)))
-    start = np.zeros(2) if from_fix else estimate.position_km
-    return start + estimate.velocity_kmh * t + estimate.acceleration_kmh2 * decay
-
-
-def kalman_track(case, leads, tau_h: float | None = None, from_fix: bool = True) -> np.ndarray:
-    """``(L, 2)`` lat/lon: the filtered motion carried forward with damped acceleration."""
-    estimate = estimate_motion(case)
-    if estimate is None:
-        return np.full((len(leads), 2), np.nan)
-    offsets = damped_offsets(estimate, leads, tau_h, from_fix)
-    lat, lon = from_local(case.lat, case.lon, offsets[:, 0], offsets[:, 1])
-    return np.stack([lat, lon], -1)
-
-
-__all__ = ["ACCELERATION_TAU_H", "FIX_SIGMA_KM", "MotionEstimate", "damped_offsets", "estimate_motion", "kalman_track"]

naturev1/cyclone/land.py

@@ -1,83 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Land and mountains along a forecast track: when the storm meets them, and what they do to it.
-
-The idea: a storm's intensity forecast is decided as much by *when it reaches land* as by anything over the
-ocean, and the track forecast says when. So land is read along the forecast track, hour by hour, from the
-analysis's land-sea mask and surface height:
-
-* **landfall time** -- the first hour the centre's land fraction passes one half;
-* **inland decay** -- Kaplan and DeMaria (1995): over land the wind decays exponentially towards a background
-  ``V_b`` with rate ``alpha``, starting from the landfall intensity times a reduction factor for the coastal
-  roughness jump;
-* **terrain** -- mountains disrupt the circulation far faster than flat land (Hispaniola, Taiwan, Luzon): the
-  decay rate grows with the surface height under the centre (``alpha * (1 + h / TERRAIN_SCALE_M)``), the effect
-  that tore up storms on Hispaniola's 3,000 m peaks and that Dorian avoided by re-forming east of it.
-
-:func:`land_along_track` samples the fields; :func:`apply_land_decay` turns an over-water intensity forecast
-into one that knows where the coast and the mountains are.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .fields import Environment
-from .geometry import interpolate_track
-
-BACKGROUND_KT = 26.7
-DECAY_PER_H = 0.095
-COAST_FACTOR = 0.9
-TERRAIN_SCALE_M = 1000.0
-
-
-def land_along_track(env: Environment, lat0: float, lon0: float, track: np.ndarray, leads, step_h: float = 1.0) -> dict:
-    """Hourly land fraction and surface height (m) along the forecast track (great-circle interpolated)."""
-    hours = np.concatenate([[0.0], np.asarray(leads, np.float64)])
-    lats = np.concatenate([[lat0], track[:, 0]])
-    lons = np.concatenate([[lon0], track[:, 1]])
-    good = np.isfinite(lats)
-    hourly = np.arange(0.0, hours[good][-1] + 1e-9, step_h)
-    la, lo = interpolate_track(hours[good], lats[good], lons[good], hourly)
-    land = np.clip(env.sample(env.fields["lsm"], la, lo), 0.0, 1.0)
-    height = np.maximum(env.sample(env.fields["zs"], la, lo) / 9.80665, 0.0)
-    landfall = hourly[np.argmax(land > 0.5)] if (land > 0.5).any() else np.nan
-    return {"hours": hourly, "lat": la, "lon": lo, "land": land, "height_m": height, "landfall_hour": float(landfall)}
-
-
-def land_weight(land: np.ndarray) -> np.ndarray:
-    """How much of the inland decay applies: none below 40% land, all of it above 90%. A 1.5-degree cell over the
-    Bahamas is partly land; a storm over it is still over water almost everywhere that matters."""
-    return np.clip((np.asarray(land, np.float64) - 0.4) / 0.5, 0.0, 1.0)
-
-
-def apply_land_decay(hours: np.ndarray, water_kt: np.ndarray, land: np.ndarray, height_m: np.ndarray) -> np.ndarray:
-    """
-    Intensity (kt) along ``hours`` given an over-water forecast ``water_kt``: over land the wind decays
-    Kaplan-DeMaria style from where it came ashore -- at a rate scaled by how much of the cell is land, faster over
-    high terrain; back over water it resumes from the decayed value and follows the over-water forecast's *changes*
-    (it does not jump back to it).
-    """
-    water = np.asarray(water_kt, np.float64)
-    out = water.copy()
-    weight = land_weight(land)
-    current = water[0]
-    ashore = False
-    for k in range(1, len(hours)):
-        dt = hours[k] - hours[k - 1]
-        change = water[k] - water[k - 1]
-        if weight[k] > 0.0:
-            if not ashore:
-                current = BACKGROUND_KT + (1.0 - (1.0 - COAST_FACTOR) * weight[k]) * (current - BACKGROUND_KT)
-                ashore = True
-            rate = DECAY_PER_H * weight[k] * (1.0 + height_m[k] / TERRAIN_SCALE_M)
-            current = BACKGROUND_KT + (current - BACKGROUND_KT) * np.exp(-rate * dt)
-            current = min(current + (1.0 - weight[k]) * max(change, 0.0), water[k])
-        else:
-            ashore = False
-            current = min(current + change, water[k])
-        out[k] = max(current, 15.0)
-    return out
-
-
-__all__ = ["BACKGROUND_KT", "DECAY_PER_H", "apply_land_decay", "land_along_track", "land_weight"]

naturev1/cyclone/members.py

@@ -1,251 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The member suite: every physics and statistical track forecast for one storm, computed from one analysis.
-
-Each member is a different answer to "where will it go", built from the modules of this package. They are
-deliberately diverse -- persistence, climatology, analogs, steering trajectories through frozen, evolving and
-climatology-relaxing flows, a barotropic model, an ensemble mean -- because a consensus gains most from members
-whose errors differ (:mod:`naturev1.cyclone.consensus`). All of them start from the analysis at the initial
-time and the best track up to it; nothing reads the future.
-
-Shared ingredients are computed once in :func:`build_context`: the vortex removed from the analysis
-(:mod:`.vortex`), the vortex's outer strength, the climatological environment for the date (:mod:`.climatology`),
-the steering flows of three layers in both, beta drift (:mod:`.beta`), the observed motion and the vorticity-
-budget motion (:mod:`.vorticity_advection`), and the 12-hour-earlier steering for the flow tendency.
-"""
-
-from __future__ import annotations
-
-from dataclasses import dataclass, field
-
-import numpy as np
-
-from .baselines import xtrp_latlon
-from .beta import BetaDrift, outer_strength
-from .data import HISTORY_HOURS, LEADS, PREVIOUS_LEVELS
-from .fields import Environment
-from .geometry import from_local, to_local, velocity_from_positions
-from .steering import SteeringFlow
-from .trajectory import DecayingResidual, EvolvingFlow, combined, frozen, integrate
-from .vortex import remove_vortex
-
-#: The members the shipped consensus weighs (order matters: it is the column order of the weights).
-DEFAULT_MEMBERS = ("xtrp6", "cliper", "analog", "budget_mix", "evo12", "med_anom48", "int_anom48", "budget_anom96",
-                   "evo_anom48", "evo_anom96", "ens48_mean", "baro_res12", "baro")
-
-
-def observed_motion(case) -> tuple[float, float] | None:
-    """(east, north) m/s over the last 6 hours (else 12)."""
-    for h in (6, 12):
-        k = HISTORY_HOURS.index(-h)
-        la, lo = case.history["lat"][k], case.history["lon"][k]
-        if np.isfinite(la):
-            return velocity_from_positions(la, lo, case.lat, case.lon, h)
-    return None
-
-
-def previous_environment(env: Environment) -> Environment | None:
-    """The analysis 12 hours earlier, as an :class:`Environment` of its stored winds."""
-    if "u" not in env.previous:
-        return None
-    return Environment(lat=env.lat, lon=env.lon, levels=PREVIOUS_LEVELS,
-                       fields={"u": env.previous["u"], "v": env.previous["v"]})
-
-
-@dataclass
-class PhysicsContext:
-    case: object
-    env: Environment
-    clean: Environment
-    outer_ms: float
-    motion: tuple[float, float]
-    motion_mix: tuple[float, float]
-    beta: BetaDrift
-    flows: dict
-    climate: Environment | None = None
-    climate_flows: dict = field(default_factory=dict)
-    before: SteeringFlow | None = None
-    split: object = None
-
-    def start_velocity(self, name: str) -> tuple[float, float]:
-        u, v = self.flows[name].velocity(self.case.lat, self.case.lon)
-        return float(u[0]), float(v[0])
-
-    def beta0(self) -> tuple[float, float]:
-        u, v = self.beta.velocity(self.case.lat, self.case.lon)
-        return float(u[0]), float(v[0])
-
-    def residual(self, name: str, motion=None, tau_h: float = 24.0) -> DecayingResidual:
-        m = motion or self.motion
-        u0, v0 = self.start_velocity(name)
-        b0 = self.beta0()
-        return DecayingResidual(m[0] - u0 - b0[0], m[1] - v0 - b0[1], tau_h)
-
-    def beta_velocity(self):
-        return lambda lat, lon, hours: self.beta.velocity(lat, lon)
-
-
-def build_context(case, env: Environment, climatology=None) -> PhysicsContext | None:
-    """Everything the members share; None when the storm has no motion history."""
-    from .climatology import DampedAnomalyFlow  # noqa: F401  (imported for its side-effect-free availability)
-    from .steering import intensity_layer
-    from .vorticity_advection import budget_motion
-
-    motion = observed_motion(case)
-    if motion is None:
-        return None
-    split = remove_vortex(env, case.lat, case.lon)
-    clean = split.environment
-    ows = outer_strength(split)
-    top, bottom = intensity_layer(case.wind_kt)
-    layers = {"med": (400, 850), "dlm": (200, 850), "shal": (700, 850), "int": (top, bottom)}
-    flows = {k: SteeringFlow(clean, *v) for k, v in layers.items()}
-    climate, cflows = None, {}
-    if climatology is not None:
-        climate = climatology.environment(clean, case.time, shift_days=2)
-        cflows = {k: SteeringFlow(climate, max(v[0], 200), min(v[1], 850)) for k, v in layers.items()}
-    budget = budget_motion(env, case.lat, case.lon)
-    mix = motion if budget is None else (0.5 * (budget["u"] + motion[0]), 0.5 * (budget["v"] + motion[1]))
-    before = None
-    k = HISTORY_HOURS.index(-12)
-    la12, lo12 = case.history["lat"][k], case.history["lon"][k]
-    prev = previous_environment(env)
-    if prev is not None and np.isfinite(la12):
-        before = SteeringFlow(remove_vortex(prev, la12, lo12).environment, 400, 850)
-    return PhysicsContext(case, env, clean, ows, motion, mix, BetaDrift(clean, ows), flows, climate, cflows, before, split)
-
-
-class _EvolvingDamped:
-    """Evolving flow (12-hour tendency) whose departure from climatology then decays."""
-
-    def __init__(self, now, before, climate, tau_evo: float, tau_anom: float) -> None:
-        self.evo = EvolvingFlow(frozen(now), frozen(before), tau_evo)
-        self.climate, self.tau = climate, tau_anom
-
-    def __call__(self, lat, lon, hours):
-        u, v = self.evo(lat, lon, hours)
-        uc, vc = self.climate.velocity(lat, lon)
-        m = np.exp(-np.asarray(hours, np.float64) / self.tau)
-        return uc + m * (u - uc), vc + m * (v - vc)
-
-
-def _anomaly_member(ctx: PhysicsContext, layer: str, tau: float, motion=None, leads=LEADS):
-    from .climatology import DampedAnomalyFlow
-
-    if layer not in ctx.climate_flows:
-        return None
-    flow = DampedAnomalyFlow(ctx.flows[layer], ctx.climate_flows[layer], tau)
-    return integrate(ctx.case.lat, ctx.case.lon, combined(flow, ctx.beta_velocity(), ctx.residual(layer, motion)), leads)
-
-
-def run_members(case, env: Environment, climatology=None, analogs=None, cliper_table: dict | None = None,
-                names=DEFAULT_MEMBERS, leads=LEADS, ensemble_members: int = 24, forecast_flow=None,
-                model_track: np.ndarray | None = None) -> dict:
-    """
-    ``{member: (L, 2) lat/lon}`` for every requested member that can be computed, plus ``"_context"`` (the shared
-    :class:`PhysicsContext`) and ``"_ensemble"`` (members, spread) when the ensemble ran.
-
-    With dynamical models' forecasts (:class:`naturev1.cyclone.forecastflow.ForecastFlow`, one or ``{name: flow}``,
-    and/or the models' own tracked storms at ``leads``, one or ``{name: (L, 2)}``) more members join: ``fflow``, the
-    storm carried through the forecast steering (the equal-weight mean over the models, each also as
-    ``fflow_<name>``), and ``model``, the models' mean track (each also as ``model_<name>``).
-    """
-    from .cliper import cliper_track
-
-    out: dict = {}
-    wanted = set(names)
-    if "xtrp6" in wanted:
-        out["xtrp6"] = xtrp_latlon(case, leads, 6)
-    if "xtrp12" in wanted:
-        out["xtrp12"] = xtrp_latlon(case, leads, 12)
-    if "cliper" in wanted:
-        out["cliper"] = cliper_track(case, leads, cliper_table)
-    if "analog" in wanted and analogs is not None:
-        out["analog"] = analogs.forecast(case, 100, 1.5)
-    from .multimodel import model_mean
-
-    if model_track is not None:
-        # one model's track, or several ({name: (L, 2)}): each is a member, and their equal-weight mean is ``model``
-        tracks = model_track if isinstance(model_track, dict) else {"model": np.asarray(model_track, np.float64)}
-        for name, t in tracks.items():
-            if t is not None and name != "model":
-                out[f"model_{name}"] = np.asarray(t, np.float64)
-        mean = model_mean(case, tracks, leads)
-        if mean is not None:
-            out["model"] = mean
-    ctx = build_context(case, env, climatology)
-    if ctx is None:
-        return out
-    out["_context"] = ctx
-    if forecast_flow is not None:
-        from .forecastflow import fflow_member
-
-        flows = (forecast_flow if isinstance(forecast_flow, dict)
-                 else {str(i): f for i, f in enumerate(forecast_flow)} if isinstance(forecast_flow, (list, tuple))
-                 else {"fflow": forecast_flow})
-        per = {}
-        for name, flow in flows.items():
-            try:
-                per[name] = fflow_member(ctx, flow, leads)
-            except Exception:                        # one unreadable model's flow must not drop the member
-                continue
-        if len(per) > 1:
-            for name, t in per.items():
-                out[f"fflow_{name}"] = t
-        mean = model_mean(case, per, leads)
-        if mean is not None:
-            out["fflow"] = mean
-    lat0, lon0 = case.lat, case.lon
-    beta = ctx.beta_velocity()
-    if "steer_med" in wanted:
-        out["steer_med"] = integrate(lat0, lon0, combined(frozen(ctx.flows["med"]), beta, ctx.residual("med")), leads)
-    if "budget_mix" in wanted:
-        out["budget_mix"] = integrate(lat0, lon0, combined(frozen(ctx.flows["med"]), beta, ctx.residual("med", ctx.motion_mix)), leads)
-    if "evo12" in wanted and ctx.before is not None:
-        out["evo12"] = integrate(lat0, lon0, combined(EvolvingFlow(frozen(ctx.flows["med"]), frozen(ctx.before), 12.0), beta,
-                                                      ctx.residual("med")), leads)
-    for name, (layer, tau, mot) in {"med_anom48": ("med", 48.0, None), "med_anom96": ("med", 96.0, None),
-                                    "int_anom48": ("int", 48.0, None), "budget_anom48": ("med", 48.0, "mix"),
-                                    "budget_anom96": ("med", 96.0, "mix")}.items():
-        if name in wanted:
-            track = _anomaly_member(ctx, layer, tau, ctx.motion_mix if mot == "mix" else None, leads)
-            if track is not None:
-                out[name] = track
-    for name, tau in (("evo_anom48", 48.0), ("evo_anom96", 96.0)):
-        if name in wanted and ctx.before is not None and "med" in ctx.climate_flows:
-            flow = _EvolvingDamped(ctx.flows["med"], ctx.before, ctx.climate_flows["med"], 12.0, tau)
-            out[name] = integrate(lat0, lon0, combined(flow, beta, ctx.residual("med", ctx.motion_mix)), leads)
-    if {"ens48_mean", "ens96_mean"} & wanted:
-        from .ensemble import physics_ensemble
-
-        flows = {k: ctx.flows[k] for k in ("med", "dlm", "shal")}
-        cflows = {k: ctx.climate_flows[k] for k in ("med", "dlm", "shal")} if ctx.climate_flows else None
-        tau = 48.0 if "ens48_mean" in wanted else 96.0
-        ens = physics_ensemble(case, ctx.clean, flows, ctx.beta, ctx.motion_mix, leads, climate=ctx.climate,
-                               climate_flows=cflows, anomaly_tau_h=tau, members=ensemble_members)
-        out["ens48_mean" if tau == 48.0 else "ens96_mean"] = ens["mean"]
-        out["_ensemble"] = ens
-    if {"baro_res24", "baro_res12", "baro"} & wanted:
-        from .barotropic import BarotropicModel
-
-        try:
-            baro = BarotropicModel(ctx.clean, lat0, lon0, ctx.outer_ms, case.r34_nmi).run(leads)["track"]
-        except (FloatingPointError, np.linalg.LinAlgError, ValueError):
-            baro = None
-        if baro is not None:
-            out["baro"] = baro
-            first = list(leads).index(min(leads))
-            x0, y0 = to_local(lat0, lon0, baro[first, 0], baro[first, 1])
-            hours = float(leads[first])
-            ru = ctx.motion_mix[0] - x0 / hours / 3.6
-            rv = ctx.motion_mix[1] - y0 / hours / 3.6
-            for name, tau in (("baro_res12", 12.0), ("baro_res24", 24.0)):
-                if name in wanted:
-                    shift = tau * 3.6 * (1 - np.exp(-np.asarray(leads, float) / tau))
-                    bx, by = to_local(lat0, lon0, baro[:, 0], baro[:, 1])
-                    la, lo = from_local(lat0, lon0, bx + ru * shift, by + rv * shift)
-                    out[name] = np.stack([la, lo], -1)
-    return out
-
-
-__all__ = ["DEFAULT_MEMBERS", "PhysicsContext", "build_context", "observed_motion", "previous_environment", "run_members"]

naturev1/cyclone/multimodel.py

@@ -1,134 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-Several models at once -- the one thing in track forecasting that always helps.
-
-NHC's best guidance is not any single model but their equal-weight average (TVCN, GUNA): the models' errors are
-partly independent, so the average errs less than the best of them. Measured here on the held-out 2018 and
-2020-2022 seasons, replacing HRES alone by the equal-weight mean of every archived model available for a forecast
-(HRES, Pangu-Weather, GraphCast, FuXi, Aurora, FGN) cut the blended track error by 11% at 24 h and 19-23% at
-48-120 h, with no weight fitted. Live, the models are GFS, ECMWF IFS, AIFS and GraphCast-GFS, read by
-:mod:`naturev1.swarm.models`.
-
-Two pieces live here:
-
-* :func:`model_mean`: the equal-weight mean of model tracks in the storm-centred frame, lead by lead over whichever
-  models still have the storm (a model that lost it drops out at that lead, nothing else changes). It is what the
-  consensus is blended with (:func:`naturev1.cyclone.consensus.blend_with_model`), and the forecast-flow members of
-  several models are averaged the same way.
-* :func:`flow_dependent_cone`: the cone sized for *this* forecast rather than for the average one (Goerss's GPCE
-  idea): a regression, fitted on the tuning seasons, of the consensus error on how far the physics members spread,
-  how far the model mean sits from the consensus, how far the forecast-flow member sits from the model, the storm's
-  speed, latitude and intensity. On the held-out seasons its radius ranks the actual errors with correlation
-  0.17-0.38 (the fixed cone, by construction, 0) at the same 67% coverage.
-
-Two things that did **not** help, measured the same way and left out: anchoring the model track to the observed
-position (it makes the model's error correlated with the consensus's and loses the averaging), and shrinking the
-model's weight when it disagrees with the forecast-flow member (when they disagree, the model is still the better
-of the two).
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .geometry import from_local, to_local
-
-
-def model_mean(case, tracks: dict | list | np.ndarray | None, leads) -> np.ndarray | None:
-    """
-    ``(L, 2)`` equal-weight mean of model tracks (``{name: (L, 2)}``, a list, or one ``(L, 2)`` array), in the
-    storm-centred frame; NaN at a lead no model reaches. ``None`` when there is nothing.
-    """
-    if tracks is None:
-        return None
-    arrays = list(tracks.values()) if isinstance(tracks, dict) else ([tracks] if isinstance(tracks, np.ndarray) else list(tracks))
-    arrays = [np.asarray(t, np.float64) for t in arrays if t is not None]
-    if not arrays:
-        return None
-    if len(arrays) == 1:
-        return arrays[0]
-    stack = np.stack(arrays)                                               # (M, L, 2)
-    east, north = to_local(case.lat, case.lon, stack[..., 0], stack[..., 1])
-    ok = np.isfinite(east) & np.isfinite(north)
-    count = ok.sum(0)
-    with np.errstate(invalid="ignore"):
-        e = np.where(ok, east, 0.0).sum(0) / np.where(count > 0, count, np.nan)
-        n = np.where(ok, north, 0.0).sum(0) / np.where(count > 0, count, np.nan)
-    lat, lon = from_local(case.lat, case.lon, e, n)
-    out = np.stack([lat, lon], -1)
-    out[count == 0] = np.nan
-    return out
-
-
-def model_spread_km(case, tracks: dict | list | None) -> np.ndarray | None:
-    """``(L,)`` mean distance of the model tracks from their mean (NaN where fewer than two models remain)."""
-    if tracks is None:
-        return None
-    arrays = [np.asarray(t, np.float64) for t in (tracks.values() if isinstance(tracks, dict) else tracks) if t is not None]
-    if len(arrays) < 2:
-        return None
-    stack = np.stack(arrays)
-    east, north = to_local(case.lat, case.lon, stack[..., 0], stack[..., 1])
-    ok = np.isfinite(east) & np.isfinite(north)
-    count = ok.sum(0)
-    me = np.where(ok, east, 0.0).sum(0) / np.maximum(count, 1)
-    mn = np.where(ok, north, 0.0).sum(0) / np.maximum(count, 1)
-    d = np.where(ok, np.hypot(east - me, north - mn), 0.0).sum(0) / np.maximum(count, 1)
-    return np.where(count >= 2, d, np.nan)
-
-
-#: Predictors of :func:`flow_dependent_cone`, in order.
-CONE_PREDICTORS = ("one", "member_spread_km", "model_consensus_km", "fflow_model_km", "speed_kmh", "abs_lat", "wind_kt")
-
-
-def cone_predictors(case, consensus: np.ndarray, members: dict, member_names, model: np.ndarray | None,
-                    fflow: np.ndarray | None, leads) -> np.ndarray:
-    """``(L, 7)`` predictor rows for one forecast (missing pieces fall back to typical values via NaN -> 0 / medians)."""
-    from .baselines import motion_back
-    from .geometry import local_displacement_km
-
-    L = len(leads)
-    ce, cn = to_local(case.lat, case.lon, consensus[:, 0], consensus[:, 1])
-    spread = np.full(L, np.nan)
-    stack = [np.asarray(members[m], np.float64) for m in member_names if m in members]
-    if stack:
-        arr = np.stack(stack)                                               # (M, L, 2)
-        e, n = to_local(case.lat, case.lon, arr[..., 0], arr[..., 1])
-        d = np.hypot(e - ce[None], n - cn[None])
-        spread = np.nanmean(d, axis=0)
-    dmc = np.full(L, np.nan)
-    if model is not None:
-        me, mn = to_local(case.lat, case.lon, model[:, 0], model[:, 1])
-        dmc = np.hypot(me - ce, mn - cn)
-    dfm = np.full(L, np.nan)
-    if model is not None and fflow is not None:
-        fe, fn = to_local(case.lat, case.lon, fflow[:, 0], fflow[:, 1])
-        dfm = np.hypot(fe - me, fn - mn)
-    speed = np.nan
-    rate = motion_back(case, 6)
-    if rate is not None:
-        e6, n6 = local_displacement_km(case.lat - rate[0] * 6, case.lon - rate[1] * 6, case.lat, case.lon)
-        speed = float(np.hypot(e6, n6)) / 6.0
-    rows = np.stack([np.ones(L), spread, dmc, dfm, np.full(L, speed), np.full(L, abs(case.lat)), np.full(L, case.wind_kt)], -1)
-    return rows
-
-
-def flow_dependent_cone(predictors: np.ndarray, table: dict, leads) -> np.ndarray:
-    """``(L,)`` cone radius (km) from the fitted regression ``table`` (``coefficients.CONE_FLOW``)."""
-    coef = np.asarray(table["coef"], np.float64)                            # (L_table, 7)
-    scale = np.asarray(table["scale"], np.float64)
-    medians = np.asarray(table.get("medians", np.zeros(coef.shape[1])), np.float64)
-    x = np.where(np.isfinite(predictors), predictors, medians[None])
-    hours = np.asarray(leads, np.float64)
-    tl = np.asarray(table["leads"], np.float64)
-    out = np.empty(len(hours))
-    for k, h in enumerate(hours):
-        j = int(np.clip(np.searchsorted(tl, h, side="right") - 1, 0, tl.size - 2))
-        a = float(np.clip((h - tl[j]) / max(tl[j + 1] - tl[j], 1e-9), 0.0, 1.0))
-        c = (1 - a) * coef[j] + a * coef[j + 1]
-        s = (1 - a) * scale[j] + a * scale[j + 1]
-        out[k] = max(float(x[k] @ c), 5.0) * s
-    return out
-
-
-__all__ = ["CONE_PREDICTORS", "cone_predictors", "flow_dependent_cone", "model_mean", "model_spread_km"]

naturev1/cyclone/neural.py

@@ -1,80 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-NatureV1's own forecast as consensus members: the storm followed through the model's rollout, and steered by it.
-
-The physics members start from a single analysis; their weakness is the flow they cannot forecast. A distilled
-NatureV1 forecasts that flow. This module runs the full-state rollout once per initial time of a hindcast season
-(:func:`naturev1.tracker.rollout_member_tracks`, one rollout for every storm active then) and turns the result
-into two more members on the same footing as the physics ones -- the vortex tracked in the forecast pressure
-field, and the storm carried by the forecast steering flow. :func:`hybrid_consensus` then blends them with the
-physics members by along/cross-track weights fitted on past seasons: physics where it is strong (the first
-hours, where persistence and the vorticity budget know more than any 1.5-degree field), the model's flow where
-it is strong (days two to five).
-"""
-
-from __future__ import annotations
-
-import json
-from pathlib import Path
-
-import numpy as np
-import torch
-
-
-def rollout_tracks(model, era5: str | Path, stepper, variables, cases, leads, precision: str = "bf16",
-                   history: int | None = None, log=print) -> dict:
-    """``{case key: {"rollout_vortex": (L, 2), "rollout_steering": (L, 2)}}`` lat/lon for every case."""
-    from ..era5 import Normalizer
-    from ..model import calendar_features
-    from ..satdata import prepared_to_state
-    from ..tracker import rollout_member_tracks
-
-    era5 = Path(era5)
-    meta = json.loads(era5.with_suffix(".json").read_text())
-    normalizer = Normalizer.from_dict(meta["statistics"])
-    times = np.asarray(meta["time"], np.int64)
-    index = {int(t): i for i, t in enumerate(times)}
-    values = np.load(era5, mmap_mode="r")
-    history = history or model.config.history_frames
-    device = next(model.parameters()).device
-    by_time: dict[int, list] = {}
-    for case in cases:
-        by_time.setdefault(int(np.datetime64(case.time, "s").astype(np.int64)), []).append(case)
-    out = {}
-    for n, (t0, group) in enumerate(sorted(by_time.items()), start=1):
-        i0 = index.get(t0)
-        if i0 is None or i0 < history - 1:
-            continue
-        window = torch.stack([prepared_to_state(values[i0 - history + 1 + k], normalizer, model.config.analysis_channels)
-                              for k in range(history)])[None].to(device)
-        stamps = torch.tensor(times[i0 - history + 1:i0 + 1], dtype=torch.float64)[None]
-        batch = {"analysis": window, "calendar": calendar_features(stamps).to(device), "valid_time": stamps[:, -1].to(device)}
-        centres = torch.tensor([[c.lat, c.lon] for c in group], dtype=torch.float32, device=device)
-        wind = torch.tensor([c.wind_kt if np.isfinite(c.wind_kt) else 50.0 for c in group], device=device)
-        with torch.no_grad():
-            members = rollout_member_tracks(model, batch, stepper, centres, leads, variables, precision, wind_kt=wind)
-        for s, case in enumerate(group):
-            entry = {}
-            for name in ("rollout_vortex", "rollout_steering"):
-                d = members[name][s].detach().cpu().numpy().astype(np.float64)        # (L, 2) degrees
-                entry[name] = np.stack([case.lat + d[:, 0], ((case.lon + d[:, 1] + 180.0) % 360.0) - 180.0], -1)
-            out[case.key] = entry
-        if log and n % 100 == 0:
-            log(f"[rollout-tracks] {n}/{len(by_time)} initial times")
-    return out
-
-
-def hybrid_consensus(cases, physics: dict, rollout: dict, weights: dict) -> np.ndarray:
-    """``(N, L, 2)``: physics members and rollout members blended by ``weights`` (``fit_consensus`` output plus
-    ``"members"``, the column order)."""
-    from .consensus import apply_consensus
-
-    nan = np.full((len(weights["along"]), 2), np.nan)
-    columns = []
-    for name in weights["members"]:
-        source = rollout if name.startswith("rollout_") else physics
-        columns.append(np.stack([source.get(c.key, {}).get(name, nan) for c in cases]))
-    return apply_consensus(cases, np.stack(columns, 2), weights)
-
-
-__all__ = ["hybrid_consensus", "rollout_tracks"]

naturev1/cyclone/ocean.py

@@ -1,182 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The ocean fights back: the cold wake a storm stirs up, and how much of it the storm itself has to sit on.
-
-The idea: a hurricane's winds mix cold thermocline water up to the surface. A storm moving at 5 m/s leaves the
-cold water behind it; a storm that stalls -- Dorian over Grand Bahama, 1 mph for a day and a half -- sits on top
-of its own wake, its fuel supply drops, and it weakens even with everything else favourable. Potential
-intensity computed from the analysis's sea-surface temperature knows none of this. Here, after the
-observational fits of Lloyd and Vecchi (2011) and Mei et al. (2012):
-
-* **wake cooling** grows with intensity (wind stress goes as speed squared, mixing faster still) and falls
-  with translation speed (less time over each patch of ocean), and is smaller over very warm water (a warmer
-  surface usually means a deeper mixed layer, more water to stir before the cold arrives);
-* **the share under the core**: a fast storm feels a small fraction of its wake, a stalled one nearly all;
-* **residence time**: cooling under a stalled storm accumulates (e-folding ``RESIDENCE_H``), so the longer it
-  sits, the colder its ocean.
-
-:func:`effective_sst` gives the sea-surface temperature the core actually feels at each forecast hour, which
-the intensity model passes to potential intensity (:mod:`naturev1.cyclone.intensity`).
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-#: Peak wake cooling for a 100 kt storm moving at 5 m/s over 28.5 C water, K.
-COOLING_K = 1.4
-#: Speed scale of the translation dependence, m/s, and its exponent.
-SPEED_SCALE_MS = 5.0
-SPEED_POWER = 0.8
-#: E-folding time over which cooling under a slow storm accumulates, hours.
-RESIDENCE_H = 18.0
-
-
-#: Depth of the 26 C isotherm the cooling constants refer to (m), and how cooling falls with a deeper warm layer.
-D26_REFERENCE_M = 50.0
-D26_POWER = 0.5
-
-
-# With the climatology present and ``d26_power`` 0 (the shipped value), the depth branch is taken with a factor of exactly 1:
-# the 0.14 surface-temperature warm-water factor is replaced, and the 0.15 refit absorbed the difference.
-def wake_cooling_k(vmax_kt, translation_ms, sst_k, d26_m=None, d26_power: float | None = None) -> np.ndarray:
-    """
-    Peak cooling of the wake, K: rises with intensity^1.5, falls with translation speed and warm water -- and, when the
-    depth of the 26 C isotherm ``d26_m`` is known, with the depth of warm water (there is more of it to stir before
-    the cold arrives: a storm over 100 m of warm water cools its surface about 0.7 times what it would over 50 m).
-    Without ``d26_m`` the surface temperature stands in for it, as before.
-    """
-    v = np.clip(np.asarray(vmax_kt, np.float64), 0.0, 200.0) / 100.0
-    u = np.maximum(np.asarray(translation_ms, np.float64), 0.3)
-    speed = np.clip((SPEED_SCALE_MS / u) ** SPEED_POWER, 0.4, 4.0)
-    if d26_m is None:
-        warm = np.clip(1.0 - 0.25 * (np.asarray(sst_k, np.float64) - 273.15 - 28.5), 0.5, 1.3)
-    else:
-        depth = np.where(np.isfinite(d26_m), np.asarray(d26_m, np.float64), D26_REFERENCE_M)
-        power = D26_POWER if d26_power is None else float(d26_power)
-        warm = np.clip((D26_REFERENCE_M / np.maximum(depth, 5.0)) ** power, 0.35, 1.8)
-    return COOLING_K * v ** 1.5 * speed * warm
-
-
-def core_share(translation_ms) -> np.ndarray:
-    """Fraction of the wake cooling felt under the core: ~1 for a stalled storm, ~0.25 at 7 m/s."""
-    u = np.maximum(np.asarray(translation_ms, np.float64), 0.0)
-    return 1.0 / (1.0 + u / 2.3)
-
-
-def effective_sst(sst_k: np.ndarray, vmax_kt: np.ndarray, translation_ms: np.ndarray, hours: np.ndarray,
-                  d26_m: np.ndarray | None = None, d26_power: float | None = None) -> np.ndarray:
-    """
-    Sea-surface temperature under the core along a forecast, K.
-
-    All arguments are ``(T,)`` along the forecast (``hours`` from now). Slow stretches accumulate cooling with
-    :data:`RESIDENCE_H`; moving off resets the residence (the storm reaches new water). With ``d26_m`` (the depth of
-    the 26 C isotherm along the track, from :class:`OceanClimatology`) the cooling knows how deep the warm water is:
-    Melissa crawled over the central Caribbean, where the 26 C water runs 100 m deep in October, and intensified --
-    a surface-temperature-only wake would have had her cooling her own ocean.
-    """
-    sst_k = np.asarray(sst_k, np.float64)
-    out = sst_k.copy()
-    residence = 0.0
-    hours = np.asarray(hours, np.float64)
-    for k in range(sst_k.size):
-        dt = hours[k] - hours[k - 1] if k else 0.0
-        slow = translation_ms[k] < 3.0
-        residence = residence + dt if slow else max(residence - 2.0 * dt, 0.0)
-        build = 1.0 - np.exp(-(residence + 6.0) / RESIDENCE_H)
-        depth = None if d26_m is None else d26_m[k]
-        cooling = wake_cooling_k(vmax_kt[k], translation_ms[k], sst_k[k], depth, d26_power) * core_share(translation_ms[k]) * build
-        out[k] = sst_k[k] - cooling
-    return out
-
-
-def anomaly_adjusted_depth(d26_m, sst_k, sst_clim_c, per_c: float) -> np.ndarray:
-    """
-    The climatological 26 C depth deepened (or shoaled) by this year's surface anomaly: ``D26 * (1 + per_c * dSST)``,
-    clipped to 0.5-2 times. The climatology cannot know a record-warm year; the analysis's sea-surface temperature can,
-    and a warmer surface over the same water column usually means a deeper warm layer. ``per_c`` is fitted on the
-    tuning seasons (``coefficients.OCEAN["sst_anomaly_per_c"]``); 0 leaves the climatology alone.
-    """
-    d = np.asarray(d26_m, np.float64)
-    if not per_c:
-        return d
-    anomaly = np.asarray(sst_k, np.float64) - 273.15 - np.asarray(sst_clim_c, np.float64)
-    factor = np.clip(1.0 + per_c * np.nan_to_num(anomaly, nan=0.0), 0.5, 2.0)
-    return np.where(np.isfinite(d), d * factor, d)
-
-
-class OceanClimatology:
-    """
-    Monthly depth of the 26 C isotherm (m) and tropical-cyclone heat potential (kJ/cm2, the heat above 26 C down to
-    that depth) on a 1-degree grid, computed from the World Ocean Atlas 2023 decadal-average temperature analysis
-    (0-1500 m, 57 levels). ``ocean_climatology.npz`` ships with the package; :meth:`default` loads it once.
-
-    Heat potential is what the SHIPS rapid-intensification index uses in place of surface temperature where it
-    can, because a storm's fuel is the warm *layer*, not the skin: 28.5 C over 30 m of warm water and 28.5 C over
-    120 m are different oceans to a hurricane sitting on them for a day.
-    """
-
-    _default = None
-
-    def __init__(self, d26_m: np.ndarray, tchp_kj_cm2: np.ndarray, lat: np.ndarray, lon: np.ndarray, sst_c=None) -> None:
-        self.d26 = np.asarray(d26_m, np.float32)                    # (12, 180, 360)
-        self.tchp = np.asarray(tchp_kj_cm2, np.float32)
-        self.sst = None if sst_c is None else np.asarray(sst_c, np.float32)      # the climatology's own surface, C
-        self.lat = np.asarray(lat, np.float64)
-        self.lon = np.asarray(lon, np.float64)
-
-    @classmethod
-    def default(cls) -> "OceanClimatology | None":
-        """The packaged climatology (None when the package was installed without it)."""
-        if cls._default is None:
-            try:
-                from importlib import resources
-
-                with resources.files("naturev1.cyclone").joinpath("ocean_climatology.npz").open("rb") as handle:
-                    data = np.load(handle)
-                    cls._default = cls(data["d26_m"], data["tchp_kj_cm2"], data["lat"], data["lon"], data.get("sst_c"))
-            except Exception:
-                cls._default = False
-        return cls._default or None
-
-    def _month_weights(self, time) -> tuple[int, int, float]:
-        """The two months around ``time`` and the weight of the second (monthly means sit mid-month)."""
-        t = np.datetime64(time, "s")
-        year = t.astype("datetime64[Y]").astype(int) + 1970
-        day_of_year = (t - np.datetime64(f"{year}-01-01", "s")) / np.timedelta64(1, "D")
-        pos = day_of_year / 365.25 * 12.0 - 0.5                     # 0 at mid-January
-        m0 = int(np.floor(pos)) % 12
-        return m0, (m0 + 1) % 12, float(pos - np.floor(pos))
-
-    def sample(self, lat, lon, time) -> dict:
-        """``{"d26_m", "tchp_kj_cm2", "sst_c"}`` at points (degrees), bilinear in space between the two months around
-        ``time``; land points take the nearest ocean value within a degree or two (NaN beyond)."""
-        la = np.atleast_1d(np.asarray(lat, np.float64))
-        lo = (np.atleast_1d(np.asarray(lon, np.float64)) + 180.0) % 360.0 - 180.0
-        m0, m1, w = self._month_weights(time)
-        fi = np.clip((la - self.lat[0]) / (self.lat[1] - self.lat[0]), 0, self.lat.size - 1.001)
-        fj = ((lo - self.lon[0]) / (self.lon[1] - self.lon[0])) % self.lon.size
-        i0, j0 = np.floor(fi).astype(int), np.floor(fj).astype(int) % self.lon.size
-        di, dj = fi - i0, fj - j0
-        i1, j1 = np.minimum(i0 + 1, self.lat.size - 1), (j0 + 1) % self.lon.size
-        out = {}
-        for name, grid in (("d26_m", self.d26), ("tchp_kj_cm2", self.tchp)) + ((("sst_c", self.sst),) if self.sst is not None else ()):
-            g = (1.0 - w) * grid[m0] + w * grid[m1]
-            corners = np.stack([g[i0, j0], g[i0, j1], g[i1, j0], g[i1, j1]])
-            weights = np.stack([(1 - di) * (1 - dj), (1 - di) * dj, di * (1 - dj), di * dj])
-            ok = np.isfinite(corners)
-            total = (weights * ok).sum(0)
-            value = np.where(total > 0, (np.where(ok, corners, 0.0) * weights).sum(0) / np.maximum(total, 1e-9), np.nan)
-            missing = ~np.isfinite(value)
-            if missing.any():                                        # coastal points: the nearest ocean cell within 2 degrees
-                for k in np.nonzero(missing)[0]:
-                    ii = slice(max(i0[k] - 2, 0), min(i0[k] + 3, self.lat.size))
-                    jj = np.arange(j0[k] - 2, j0[k] + 3) % self.lon.size
-                    patch = g[ii][:, jj]
-                    value[k] = np.nanmean(patch) if np.isfinite(patch).any() else np.nan
-            out[name] = value
-        return out
-
-
-__all__ = ["COOLING_K", "D26_POWER", "D26_REFERENCE_M", "OceanClimatology", "RESIDENCE_H", "anomaly_adjusted_depth", "core_share",
-           "effective_sst", "wake_cooling_k"]

naturev1/cyclone/ocean_climatology.npz

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

naturev1/cyclone/outflow.py

@@ -1,75 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The top of the storm: upper-tropospheric outflow, and the troughs that feed it or tear it.
-
-The idea: a hurricane is a heat engine whose exhaust is the 200 hPa outflow. How easily it can vent decides
-whether it intensifies, and the upper-level environment acts in two ways the low-level predictors miss:
-
-* **divergence aloft** -- strong 200 hPa divergence over the storm (an outflow jet, a trough's right entrance
-  region nearby) evacuates mass and favours deepening;
-* **eddy flux convergence of angular momentum** (EFC; Molinari and Vollaro 1989, a SHIPS predictor) -- the
-  convergence of the eddy flux of relative angular momentum by the environment's asymmetric flow at 200 hPa,
-  300-600 km out: ``EFC = -(1 / r^2) d(r^2 <u_L' v_T'>) / dr``. Large positive EFC from an approaching trough
-  spins up the outflow anticyclone and can trigger intensification -- *if* shear stays moderate; with strong
-  shear the same trough destroys the storm. The classification below encodes that distinction.
-* **outflow channels** -- the number of azimuthal sectors (of eight) with strong radial outflow at 500-1000 km:
-  one channel is ordinary, two (poleward into a jet and equatorward) is the signature of the most intense storms;
-* **outflow temperature** comes from the potential intensity calculation (:mod:`naturev1.thermo`).
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .fields import Environment
-from .geometry import destination
-
-
-def _ring_winds(env: Environment, lat0: float, lon0: float, radius_km: float, level: int, azimuths: int = 32):
-    bearing = np.arange(azimuths) * 360.0 / azimuths
-    plat, plon = destination(lat0, lon0, bearing, radius_km)
-    u = env.sample(env.level("u", level), plat, plon)
-    v = env.sample(env.level("v", level), plat, plon)
-    b = np.radians(bearing)
-    radial = u * np.sin(b) + v * np.cos(b)
-    tangential = -u * np.cos(b) + v * np.sin(b)
-    return radial, tangential
-
-
-def eddy_flux_convergence(env: Environment, lat0: float, lon0: float, level: int = 200,
-                          radii_km=(300.0, 400.0, 500.0, 600.0)) -> float:
-    """EFC in m/s per day, averaged over 300-600 km (cyclonic sign per hemisphere)."""
-    sign = 1.0 if lat0 >= 0 else -1.0
-    radii = np.asarray(radii_km) * 1000.0
-    flux = []
-    for r in radii_km:
-        radial, tangential = _ring_winds(env, lat0, lon0, r, level)
-        flux.append(np.mean((radial - radial.mean()) * (sign * tangential - np.mean(sign * tangential))))
-    flux = np.asarray(flux)
-    d = np.gradient(radii ** 2 * flux, radii)
-    efc = -(d / radii ** 2)
-    return float(np.mean(efc) * 86400.0)
-
-
-def outflow_diagnostics(env: Environment, env_clean: Environment, lat0: float, lon0: float, shear_ms: float) -> dict:
-    """Divergence aloft, EFC, outflow channels and a trough-interaction class (favourable / hostile / none)."""
-    div = env.divergence(env.level("u", 200), env.level("v", 200))
-    r = env.distance_km(lat0, lon0)
-    disc = r < 1000.0
-    divergence = float(div[disc].mean()) * 1e5 if disc.any() else 0.0
-    efc = eddy_flux_convergence(env_clean, lat0, lon0)
-    channels = 0
-    for radius in (500.0, 750.0, 1000.0):
-        radial, _ = _ring_winds(env, lat0, lon0, radius, 200, azimuths=32)
-        sectors = radial.reshape(8, 4).mean(1)
-        channels = max(channels, int((sectors > 6.0).sum()))
-    if efc > 10.0 and shear_ms < 10.0:
-        interaction = "favourable"
-    elif efc > 10.0:
-        interaction = "hostile"
-    else:
-        interaction = "none"
-    return {"divergence_200": divergence, "efc_ms_day": efc, "outflow_channels": channels, "trough_interaction": interaction}
-
-
-__all__ = ["eddy_flux_convergence", "outflow_diagnostics"]

naturev1/cyclone/pouch.py

@@ -1,66 +0,0 @@
-# Copyright 2026 Nathan. Apache-2.0.
-"""
-The marsupial pouch: a closed circulation in the frame that moves with the wave.
-
-The idea (Dunkerton, Montgomery and Wang 2009): most Atlantic and many Pacific storms form inside tropical
-waves, and the wave matters because of what it looks like *in its own moving frame*. In the Earth-relative
-frame a wave's circulation is usually open -- air blows straight through it. In the frame moving west with the
-wave, a critical layer forms where the flow speed equals the wave's phase speed, and the streamlines close
-into a "pouch" that protects the moist, rotating core from dry air, letting convection organise long enough
-for a vortex to spin up. A disturbance with a closed pouch is a disturbance that can become a storm; one
-without, usually cannot.
-
-:func:`pouch_closedness` evaluates the circulation of the wave-relative 850/700 hPa flow on rings around a
-disturbance: the share of the ring where the relative tangential wind is cyclonic, the mean relative tangential
-wind, and the relative circulation -- 1 for a perfectly closed, strongly cyclonic pouch, 0 for none. The phase
-speed comes from the disturbance's own motion (its candidate track) or a climatological -7 m/s westward.
-"""
-
-from __future__ import annotations
-
-import numpy as np
-
-from .geometry import destination, hemisphere
-
-DEFAULT_PHASE_MS = (-7.0, 0.0)
-
-
-def pouch_closedness(env, lat0: float, lon0: float, phase_ms=DEFAULT_PHASE_MS, levels=("850", "600"),
-                     radii_km=(250.0, 400.0, 550.0), azimuths: int = 24) -> dict:
-    """Closedness of the wave-relative circulation around (lat0, lon0) in an analysis band."""
-    sign = float(hemisphere(lat0))
-    shares, speeds = [], []
-    for level in levels:
-        u = env.fields[f"u{level}"] - phase_ms[0]
-        v = env.fields[f"v{level}"] - phase_ms[1]
-        for radius in radii_km:
-            bearing = np.arange(azimuths) * 360.0 / azimuths
-            plat, plon = destination(lat0, lon0, bearing, radius)
-            uu, vv = env.sample(u, plat, plon), env.sample(v, plat, plon)
-            b = np.radians(bearing)
-            # Tangential unit vector for counter-clockwise rotation at a point bearing b from the centre.
-            te, tn = -np.cos(b), np.sin(b)
-            vt = sign * (uu * te + vv * tn)
-            shares.append(float(np.mean(vt > 0)))
-            speeds.append(float(np.mean(vt)))
-    share = float(np.mean(shares))
-    speed = float(np.mean(speeds))
-    score = share * float(np.clip(speed / 5.0, 0.0, 1.0))
-    return {"share_cyclonic": share, "mean_tangential_ms": speed, "closedness": score}
-
-
-def phase_from_history(candidate) -> tuple[float, float]:
-    """Phase speed (m/s) of a genesis candidate from its last 12-24 hours of positions, or the default."""
-    from .geometry import velocity_from_positions
-
-    if not candidate.history:
-        return DEFAULT_PHASE_MS
-    earlier = candidate.history[-2] if len(candidate.history) >= 2 else candidate.history[-1]
-    hours = (candidate.time - earlier.time) / np.timedelta64(1, "h")
-    if hours <= 0:
-        return DEFAULT_PHASE_MS
-    u, v = velocity_from_positions(earlier.lat, earlier.lon, candidate.lat, candidate.lon, hours)
-    return float(np.clip(u, -15, 5)), float(np.clip(v, -5, 5))
-
-
-__all__ = ["DEFAULT_PHASE_MS", "phase_from_history", "pouch_closedness"]