""" Central configuration for MicroClimate-X. EVERY Veto threshold below has an academic / regulatory citation. This is intentional — at thesis defence the panel WILL ask "why 3500 m, why -5 °C, why 40 km/h?". Be ready to point to this file. """ from __future__ import annotations import os import subprocess from pathlib import Path ROOT = Path(__file__).resolve().parent.parent MODEL_DIR = ROOT / "models" DATA_DIR = ROOT / "data" DB_PATH = Path(os.environ.get("MICROCLIMATEX_DB", str(ROOT / "cache.sqlite3"))) def _detect_git_revision() -> str: """Best-effort short SHA. Returns "unknown" if git is not available or this directory isn't a checkout (e.g. inside a Docker image).""" env = os.environ.get("MICROCLIMATEX_GIT_REV") if env: return env try: out = subprocess.run( ["git", "rev-parse", "--short", "HEAD"], cwd=ROOT, capture_output=True, text=True, timeout=2.0, ) if out.returncode == 0: return out.stdout.strip() except (FileNotFoundError, subprocess.SubprocessError): # pragma: no cover pass return "unknown" GIT_REVISION = _detect_git_revision() # ────────────────────────────────────────────────────────────────────────── # Veto thresholds — one-vote rejection rules # ────────────────────────────────────────────────────────────────────────── # Citation: Luks et al. (2019) "Wilderness Medical Society Practice # Guidelines for the Prevention and Treatment of Acute Altitude # Illness." High altitude (>2500 m) carries clinical risk; severe # hypoxia onset is well-documented above ~3500 m. ALTITUDE_HYPOXIA_M = 3500.0 # Citation: WMO Beaufort scale — Force 6 "Strong breeze" ≈ 39-49 km/h, # the threshold above which outdoor activity becomes hazardous. GALE_WIND_KMH = 40.0 # Citation: UIAA Medical Commission frostbite risk guidance — exposed skin # freezes rapidly below approximately -5 °C with wind chill. EXTREME_COLD_C = -5.0 # Citation: U.S. NWS convective forecasting handbook — CAPE > 1000 J/kg # indicates moderate-to-strong instability suitable for # thunderstorm development. HIGH_CAPE_JKG = 1000.0 # Citation: FAA AIM 7-1-12 — visibility below 100 m is classified as # Category III instrument-only conditions. Used here as an extreme # low-visibility threshold (whiteout / dense fog). LOW_VISIBILITY_M = 100.0 # Wind alignment with slope normal vector (orographic uplift). The # threshold 0.7 corresponds to ~45 degrees of slope-facing wind. OROGRAPHIC_DOT_THRESHOLD = 0.7 # Wet-flood trigger in a valley basin: high probability of localised rain # combined with valley-floor topography. VALLEY_FLOOD_PROB = 0.80 # ────────────────────────────────────────────────────────────────────────── # Risk scoring (additive penalties when no Veto fires) # ────────────────────────────────────────────────────────────────────────── PENALTY = { "ml_high_rain_prob": 35, # ML predicts >= 70 % rain probability "ml_mid_rain_prob": 15, # ML predicts 40-70 % rain probability "valley_floor": 10, "windward_slope": 20, "orographic_lift": 25, "altitude_high": 15, # 2500-3500 m, sub-Veto altitude band "wind_strong": 10, # 25-40 km/h } # ────────────────────────────────────────────────────────────────────────── # Four hazard categories — matches D5 proposal §3.7 / P4.3 # ────────────────────────────────────────────────────────────────────────── # Fog risk: # WMO surface synoptic code: fog ≈ visibility < 1 km, RH typically > 95 %, # dew-point depression < ~2 °C. Valley/Slope basins trap radiation fog. FOG_HUMIDITY_PCT = 95.0 FOG_DEW_DEP_MAX_C = 2.0 FOG_CLOUD_BASE_MAX_M = 800.0 # from D5 §3.7.2 decision table # Wind gust risk: # On exposed ridges and mountain passes, sustained 25 km/h winds with # topographic acceleration commonly gust to Beaufort F6 levels. GUST_WIND_MIN_KMH = 25.0 # below GALE_WIND_KMH but still risky # Thunderstorm risk: # NWS "moderate instability" begins at CAPE 500 J/kg; sharp pressure drop # often precedes convective initiation. THUNDER_CAPE_MIN_JKG = 500.0 THUNDER_PRESSURE_DROP = -2.0 # hPa over past 3 h (matches D5 §1.3 example) # ────────────────────────────────────────────────────────────────────────── # Decision Table — D5 §3.7.2 / Table 4.2 (one-to-one with the thesis) # ────────────────────────────────────────────────────────────────────────── # Each rule fires when ALL of its non-None conditions hold. The thesis # narrative motivates this table as: "macro forecast says no rain, but # the local terrain conditions imply hidden risk". DECISION_TABLE_3_7_2 = { "R1": { "description": "Hidden rain risk — macro says no, terrain says yes", "macro_rain_prob_max": 0.30, "macro_rain_prob_min": None, "humidity_min_pct": 85.0, "wind_into_slope": True, "terrain": "WindwardSlope", "pressure_change_3h_max": -1.5, "cloud_base_max_m": FOG_CLOUD_BASE_MAX_M, "conclusion_en": "Hidden rain risk: terrain analysis indicates orographic precipitation despite low macro probability.", "conclusion_zh": "隐藏降雨风险：宏观预报概率低，但地形分析表明存在地形抬升降水。", }, "R2": { "description": "No significant risk — terrain not aligned", "macro_rain_prob_max": 0.30, "macro_rain_prob_min": None, "humidity_min_pct": 85.0, "wind_into_slope": False, "terrain": "LeewardOrValley", "pressure_change_3h_max": -1.5, "cloud_base_max_m": FOG_CLOUD_BASE_MAX_M, "conclusion_en": "No significant rainfall danger at this spot in this period.", "conclusion_zh": "此地此时无显著降雨危险。", }, "R3": { "description": "Heavy downpour incoming — avoid exposure", "macro_rain_prob_max": None, "macro_rain_prob_min": 0.70, "humidity_min_pct": None, "wind_into_slope": True, "terrain": "WindwardSlope", "pressure_change_3h_max": None, "cloud_base_max_m": None, "conclusion_en": "Heavy downpour incoming. Avoid mountains and valleys.", "conclusion_zh": "强降雨即将到来。请避开山区与峡谷。", }, "R4": { "description": "Normal rain — no terrain amplification", "macro_rain_prob_max": None, "macro_rain_prob_min": 0.70, "humidity_min_pct": None, "wind_into_slope": None, "terrain": None, "pressure_change_3h_max": None, "cloud_base_max_m": None, "conclusion_en": "Rain expected, but no terrain-induced amplification. Standard rain precautions apply.", "conclusion_zh": "预计有雨，但无地形抬升放大。按一般雨天措施应对即可。", }, } # ────────────────────────────────────────────────────────────────────────── # Activity-aware weighting — D5 §3.7 / P4.4 # ────────────────────────────────────────────────────────────────────────── # Composite = Σ w_i · subscore_i, then renormalised to 0-100. # Rows: activity. Cols: rainfall, fog, wind_gust, thunderstorm. ACTIVITY_WEIGHTS = { "hiker": {"rainfall": 1.0, "fog": 1.3, "wind_gust": 1.0, "thunderstorm": 1.4}, "driver": {"rainfall": 0.8, "fog": 1.5, "wind_gust": 1.3, "thunderstorm": 0.9}, "construction": {"rainfall": 1.0, "fog": 0.8, "wind_gust": 1.5, "thunderstorm": 1.4}, "general": {"rainfall": 1.0, "fog": 1.0, "wind_gust": 1.0, "thunderstorm": 1.0}, } # ────────────────────────────────────────────────────────────────────────── # Cache TTL (risk-adaptive) # ────────────────────────────────────────────────────────────────────────── # Safety-critical apps must not serve stale "Safe" verdicts during developing # storms. Bucket TTL by risk band. TTL_HIGH_RISK_SEC = 60 # any Veto fired OR risk >= 70 TTL_MID_RISK_SEC = 300 # risk 40-70 TTL_LOW_RISK_SEC = 600 # risk < 40 # Grid resolution used as cache key (0.01° ≈ 1.1 km at the equator). GRID_RESOLUTION_DEG = 0.01 # ────────────────────────────────────────────────────────────────────────── # External API endpoints # ────────────────────────────────────────────────────────────────────────── OPEN_METEO_FORECAST_URL = "https://api.open-meteo.com/v1/forecast" OPEN_TOPO_URL = "https://api.opentopodata.org/v1/srtm30m" # ────────────────────────────────────────────────────────────────────────── # Domain constants # ────────────────────────────────────────────────────────────────────────── # WMO definition of trace precipitation. RAIN_THRESHOLD_MM = 0.1