{"data":{"kind":"file","path":"README.md","version_id":"reit0oxi71oxsfxub7sj68h0","entry":{"name":"README.md","path":"README.md","is_directory":false,"size":4170,"modified_at":"2026-09-28T10:48:56.056000","content_hash":"0811dd48de42f499b59ebdc9f84686b5fc7edd596335d214ee6351bc95a2e876"},"entries":[],"content":"# Tropical Cyclone Forecasting (v1.0.0)\n\nAn operational storm-forecasting environment for reinforcement learning and evaluation of\nLLMs on tropical cyclone (typhoon / hurricane) analysis. Every sample is a realistic\nforecast-desk task whose answer is derived from first-principles meteorology and spherical\ntrigonometry, so ground truth is exact, deterministic, and reproducible from a fixed seed.\n\n## Task types\n\n| Task type | Skill tested | Ground truth |\n|---|---|---|\n| `classify_intensity` | Map 1-min max sustained wind to the Saffir-Simpson scale | Standard NHC thresholds (TD <34 kt, TS 34-63, C1 64-82, C2 83-95, C3 96-112, C4 113-136, C5 >=137 kt) |\n| `intensity_trend` | Detect rapid intensification / rapid weakening | NHC operational definition: >=30 kt change in 24 h |\n| `eta_landfall` | Great-circle distance + forward-speed ETA | Haversine (R = 6371 km), 1 kt = 1.852 km/h |\n| `wind_field_impact` | Quadrant wind-radii geometry | City bearing selects NE/SE/SW/NW quadrant; distance (nm) vs that quadrant's 34-kt radius |\n| `advisory_decision` | Operational warning/watch decision | NHC lead-time convention (warning <=36 h, watch <=48 h) applied to storm intensity |\n| `ace_computation` | Accumulated Cyclone Energy | ACE = 1e-4 * sum(V^2) over 6-hourly obs with V >= 34 kt (NOAA convention) |\n| `track_error` | Forecast verification | Mean great-circle track error (nm) over the 12-48 h period |\n\n## Sample format\n\nEach dataset row carries:\n\n- `prompt`: message list (system + user) with a structured situation, a data block, and a\n  strict JSON output contract\n- `answer`: ground-truth JSON string with `value`, `unit`, `givens` (scenario numbers),\n  `intermediates` (the numbers a correct solution must compute along the way), and\n  `tolerance` / `plausible_range`\n- `info`: task type and sample id\n\nThe model must answer exactly one JSON object:\n\n```json\n{\"answer\": 42.5, \"unit\": \"hours\", \"reasoning\": \"step-by-step with the actual numbers\"}\n```\n\n## Scoring\n\n| Reward function | Weight | What it measures |\n|---|---|---|\n| `answer_accuracy` | 0.50 | Exact/near-exact match to ground truth. Numeric answers get graded credit that decays with relative error; string answers accept documented synonyms (e.g. \"Cat 3\" == \"Category 3\") |\n| `reasoning_grounding` | 0.20 | The explanation must actually contain the scenario numbers and the correct intermediate values (distance, bearing, wind change, ...), plus units and causal connectives |\n| `format_compliance` | 0.10 | Valid JSON with `answer`, `unit`, `reasoning` and a substantive explanation |\n| `unit_accuracy` | 0.10 | Correct unit (or correct \"no unit\") with synonym handling |\n| `physical_plausibility` | 0.10 | The answer lies in the physically plausible range for the task (no 500 kt hurricanes, no negative ETAs) |\n\n### Anti-gaming design\n\n- `answer_accuracy` requires genuinely correct meteorology or arithmetic; keyword stuffing\n  cannot move it.\n- `reasoning_grounding` is multi-signal: it needs (a) at least two givens from the prompt,\n  (b) at least one *correct intermediate* value (only obtainable by doing the computation),\n  (c) unit tokens and domain terms, and (d) numeric, causal reasoning structure. Filler text\n  with varied vocabulary scores zero on (b).\n- `physical_plausibility` rejects template answers that ignore the scenario magnitudes.\n\n## Usage\n\n```python\nimport verifiers as vf\nenv = vf.load_environment(\"tropical_cyclone_forecasting\")\n# or\nfrom tropical_cyclone_forecasting import load_environment\nenv = load_environment(n_per_type=8)\n```\n\nEnvironment knobs (all optional): `task_types` (list), `n_per_type` (int, default 8),\n`seed` (int, default 20260928).\n\n## Meteorological references\n\n- Saffir-Simpson Hurricane Wind Scale (NOAA/NHC)\n- Rapid intensification / rapid weakening operational thresholds, NHC (>=30 kt / 24 h)\n- Accumulated Cyclone Energy, NOAA definition (6-hourly V^2, V >= 34 kt)\n- NHC watch/warning lead-time convention (hurricane warning <=36 h, watch <=48 h)\n- Great-circle distance and initial bearing on a spherical Earth (R = 6371 km)\n\n## Version\n\n1.0.0 - initial release: 7 task types, deterministic seeded generation, 56 samples by default.\n","encoding":"utf-8","truncated":false,"total_bytes":4170},"status":null}