I’ll design **humidityLang** as a domain-specific language that puts moisture in the air at the centre of every weather analysis. The language imagines that you have access to real‑time and forecast weather grids just like the layers on Zoom Earth (relative humidity, dew point, precipitable water, wind, temperature, pressure) and lets you write concise, readable programs to explore them.

---

## humidityLang – a weather‑understanding language

### Philosophy
- **Humidity is the main character.** Every value has a humidity context – even temperature is thought of as “how much water the air *could* hold”.
- **Zoom Earth–like data model.** The world is a grid (latitude × longitude × time). Layers are 2D fields: relative humidity, specific humidity, temperature, wind vectors, etc.
- **Declarative, functional style.** You write expressions that combine, filter, and visualise these fields. Side effects (like plotting) are only allowed in `show` statements.

---

### Data Types

| Type | Meaning |
|------|---------|
| `Humidity` | A floating‑point percentage (0–100% RH) or a mass ratio (g/kg). The language tracks which is which. |
| `Temp` | Temperature in °C, always associated with a pressure level. |
| `Wind` | A vector (u, v) in m/s. |
| `Grid<T>` | A regular lat‑lon grid of type `T`, for a specific timestamp. |
| `TimeSeries<T>` | A sequence of grids over time. |
| `Region` | A polygon defined by lat/lon points. |
| `BoolGrid` | A grid of true/false, created by comparisons. |
| `ColorMap` | A palette for visualisation. |

---

### Built‑in Functions (core weather library)

All functions work point‑wise on grids unless stated otherwise.

- `rh(T: Temp, q: Humidity) → Humidity`  
  relative humidity from temperature and specific humidity.
- `dewpoint(T: Temp, rh: Humidity) → Temp`
- `precipitable_water(q: Humidity, p: Pressure) → mm`
- `mixing_ratio(rh: Humidity, T: Temp, p: Pressure) → Humidity` (g/kg)
- `heat_index(T: Temp, rh: Humidity) → Temp`
- `humidex(T: Temp, rh: Humidity) → Temp`
- `vapor_pressure(T: Temp) → hPa`  (saturation vapour pressure)
- `wet_bulb(T: Temp, rh: Humidity) → Temp`
- `saturation_deficit(T: Temp, rh: Humidity) → Humidity`  (100% – RH)
- `wind_chill(T: Temp, wind: Wind) → Temp`
- `gradient(grid: Grid<T>) → Grid<(T,T)>` (magnitude and direction)
- `mean(grid: Grid<T>, region: Region?) → T`
- `time_change(series: TimeSeries<T>) → Grid<T>`  (tendency)
- `at(series: TimeSeries<T>, time: DateTime) → Grid<T>`
- `animate(series: TimeSeries<T>, cmap: ColorMap)`  (preview loop)
- `where(condition: BoolGrid) → Region`  (returns polygon of true cells)

---

### Syntax Overview

Programs are sequences of **definitions** and **show** commands.

```
# Comments start with # and are written as prose
```

**Loading data** – mimics pulling a Zoom Earth layer:
```
load humidity_now = layer("relative_humidity", timestamp = now)
load temp_sfc     = layer("temperature_2m",  timestamp = now)
load wind_10m     = layer("wind_10m",         timestamp = now)
load forecast_rh  = layer("relative_humidity",
                          from = now, to = now + 24h, step = 1h)
```

**Defining new grids:**
```
def uncomfortable = heat_index(temp_sfc, humidity_now) > 32
```

**Region of interest:**
```
region mumbai = [ (19.07, 72.87), (19.07, 72.90), (19.00, 72.90), (19.00, 72.87) ]
```

**Visualisation – the only side effect:**
```
show humidity_now
    title "Current relative humidity (%)"
    colormap HumidityGreen
    overlay borders
```

```
show uncomfortable
    title "Areas with heat index >32°C"
    colormap AlertRed
```

```
animate forecast_rh
    title "24‑hour RH forecast"
    colormap HumidityBlue
    output mp4 "rh_forecast.mp4"
```

**Time analysis:**
```
def rh_tendency = time_change(forecast_rh)
show rh_tendency
    title "RH change per hour (pp/h)"
    colormap DivergingCyanMagenta
```

**Spatial analysis:**
```
def coastal_rh = mean(humidity_now, where(distance_to_coast < 50km))
print "Average RH near coast: " + coastal_rh
```

---

### Example Programs

#### 1. Where will it feel muggiest tomorrow?
```
load tomorrow_t = layer("temperature_2m", timestamp = tomorrow)
load tomorrow_rh = layer("relative_humidity", timestamp = tomorrow)

def humidex_grid = humidex(tomorrow_t, tomorrow_rh)
def extreme = humidex_grid > 40

show extreme
    title "Humidex >40 tomorrow afternoon"
    colormap HotPink
```

#### 2. Find regions where dew point depression is <2°C (near fog)
```
load t_now = layer("temperature_2m", timestamp = now)
load rh_now = layer("relative_humidity", timestamp = now)

def td = dewpoint(t_now, rh_now)
def depression = t_now - td
def fog_risk = depression < 2

show fog_risk
    title "Fog risk (Dew point depression <2°C)"
    colormap GreyFog
```

#### 3. Watch humidity pour into a storm
```
load precip_water = layer("precipitable_water", from = now - 6h, to = now, step = 30min)

animate precip_water
    title "Precipitable water last 6 hours"
    colormap WaterVapor
    speed 2x
```

#### 4. Humidity‑first heatwave alert
```
def vapour_press = vapor_pressure(t_sfc)
def actual_vp   = vapour_press * (rh_now / 100)
def s_deficit   = saturation_deficit(t_sfc, rh_now)

def alert = (t_sfc > 35) and (s_deficit < 10)   # hot but humid

show alert
    title "Humid heat alert"
    colormap DangerPurple
```

---

### Control Structures (minimal)

`humidityLang` deliberately avoids full Turing‑complete loops. Instead it offers:

- **Map**: `apply(func, grid)`  
- **Reduce**: `reduce(func, grid, init)`  
- **Filter** (`where`), **Temporal aggregation** (`max_over`, `min_over`, `sum_over` a time series)

This keeps analysis declarative and close to the physics.

---

### Integration with Zoom Earth

The `layer` function can be configured to pull directly from the data sources that Zoom Earth uses (GFS, GEOS‑FP, etc.) by specifying:
- variable name (`relative_humidity`, `temperature_2m`, `cloud_top_temp`, `precipitable_water` …)
- level (`surface`, `850hPa`, `500hPa`)
- timestamps

The language engine would know the grid resolution (e.g., 0.25° for GFS) and automatically regrid when combining layers.

---

### Summary

**humidityLang** turns “what does Zoom Earth show me?” into “what is the atmosphere’s moisture story?”. Every expression centres on water in the air, making it natural to ask questions like:

- Where is the air almost saturated but not yet raining?
- How quickly is the humidity building ahead of a front?
- Which cities will experience oppressive humidity tomorrow?

It’s a playful but genuinely functional language for weather enthusiasts, forecasters, and educators who want to read the sky through a humid lens.