CBottle Tropical Cyclone Guidance¶
Guided tropical cyclone sampling with cBottle and odds-ratio diagnostics.
This example demonstrates the cBottle TC guidance model for generating synthetic tropical cyclone samples at user-specified locations and computing the log-odds ratio between the guided and unguided distributions. The odds ratio quantifies how much more likely a particular sample is under guidance compared to the base model.
For more information on cBottle see:
For more information on the odds ratio see:
In this example you will learn:
- Running guided TC sampling with
earth2studio.models.dx.CBottleTCGuidance - Visualizing a guided sample over a regional domain
- Reloading the model with second-order derivative support for odds-ratio computation
- Computing and interpreting the log-odds ratio of a guided sample
Set Up¶
For this example we need the cBottle TC guidance diagnostic model. We load it twice:
- Default (fast) path for standard guided sampling
- Second-order-derivative path for odds-ratio computation
Thus, we need the following:
- Diagnostic Model: Use the built in CBottle TC Guidance Model
earth2studio.models.dx.CBottleTCGuidance.
import os
os.makedirs("outputs", exist_ok=True)
from dotenv import load_dotenv
load_dotenv() # TODO: make common example prep function
from datetime import datetime
import numpy as np
import torch
from earth2studio.models.dx import CBottleTCGuidance
device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
# Load the default model package which downloads the checkpoint from NGC
package = CBottleTCGuidance.load_default_package()
Guided TC Sampling (Fast Path)¶
The guidance tensor marks the location where we want TC activity. Here we place a
single guidance point near Florida and request one timestamp during hurricane season.
The fast model path (allow_second_order_derivatives=False) is optimized for
standard guided inference.
lat = torch.tensor([27.0], device=device) # Near Florida
lon = torch.tensor([-82.0], device=device) # Converted internally to [0, 360)
times = [datetime(2005, 10, 11, 12)]
model = CBottleTCGuidance.load_model(package, seed=0).to(device)
# Create guidance tensor
guidance, coords = model.create_guidance_tensor(lat, lon, times)
guidance = guidance.to(device)
# Run guided sampling
guided_sample, guided_coords = model(guidance, coords)
Console output41 lines
Downloading ema-checkpoint-002176000.checkpoint: 0%| | 0.00/568M [00:00<?, ?B/s]
Downloading ema-checkpoint-002176000.checkpoint: 2%|โ | 10.0M/568M [00:01<01:30, 6.46MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 4%|โ | 20.0M/568M [00:01<00:44, 12.8MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 5%|โ | 30.0M/568M [00:02<00:30, 18.7MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 7%|โ | 40.0M/568M [00:02<00:23, 23.2MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 9%|โ | 50.0M/568M [00:02<00:19, 28.2MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 11%|โ | 60.0M/568M [00:02<00:15, 33.9MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 12%|โโ | 70.0M/568M [00:03<00:13, 38.8MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 14%|โโ | 80.0M/568M [00:03<00:11, 43.2MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 16%|โโ | 90.0M/568M [00:03<00:10, 47.7MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 18%|โโ | 100M/568M [00:03<00:09, 54.0MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 19%|โโ | 110M/568M [00:03<00:07, 61.5MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 23%|โโโ | 130M/568M [00:03<00:05, 76.6MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 25%|โโโ | 140M/568M [00:03<00:05, 80.2MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 26%|โโโ | 150M/568M [00:04<00:05, 84.7MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 30%|โโโ | 170M/568M [00:04<00:04, 99.1MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 33%|โโโโ | 190M/568M [00:04<00:03, 103MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 37%|โโโโ | 210M/568M [00:04<00:03, 107MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 40%|โโโโ | 230M/568M [00:04<00:03, 107MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 44%|โโโโโ | 250M/568M [00:04<00:03, 107MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 48%|โโโโโ | 270M/568M [00:05<00:03, 99.2MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 51%|โโโโโ | 290M/568M [00:05<00:02, 102MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 55%|โโโโโโ | 310M/568M [00:05<00:02, 107MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 58%|โโโโโโ | 330M/568M [00:05<00:02, 112MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 62%|โโโโโโโ | 350M/568M [00:05<00:01, 116MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 65%|โโโโโโโ | 370M/568M [00:06<00:01, 117MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 69%|โโโโโโโ | 390M/568M [00:06<00:01, 99.9MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 72%|โโโโโโโโ | 410M/568M [00:07<00:03, 47.7MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 74%|โโโโโโโโ | 420M/568M [00:08<00:05, 30.8MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 76%|โโโโโโโโ | 430M/568M [00:09<00:07, 18.5MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 77%|โโโโโโโโ | 440M/568M [00:10<00:08, 15.7MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 79%|โโโโโโโโ | 450M/568M [00:11<00:08, 14.5MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 81%|โโโโโโโโ | 460M/568M [00:11<00:06, 17.7MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 83%|โโโโโโโโโ | 470M/568M [00:11<00:04, 22.3MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 84%|โโโโโโโโโ | 480M/568M [00:12<00:03, 28.5MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 88%|โโโโโโโโโ | 500M/568M [00:12<00:01, 42.9MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 91%|โโโโโโโโโโ| 520M/568M [00:12<00:00, 57.0MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 95%|โโโโโโโโโโ| 540M/568M [00:12<00:00, 64.4MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 97%|โโโโโโโโโโ| 550M/568M [00:13<00:00, 50.8MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 99%|โโโโโโโโโโ| 560M/568M [00:13<00:00, 56.8MB/s]
Downloading ema-checkpoint-002176000.checkpoint: 100%|โโโโโโโโโโ| 568M/568M [00:13<00:00, 45.0MB/s]Post Processing Guided Sample¶
Plot the 10-metre zonal wind (u10m) over a Caribbean domain to visualize the generated tropical cyclone structure.
import cartopy.crs as ccrs
import matplotlib.pyplot as plt
plt.close("all")
variables = guided_coords["variable"]
u_var = "u10m"
u_idx = int(np.where(variables == u_var)[0][0])
# guided_sample dims: [time, lead_time, variable, lat, lon]
u = guided_sample[0, 0, u_idx].detach().cpu().numpy()
lat_coords = guided_coords["lat"]
lon_coords = guided_coords["lon"]
# Caribbean box in 0-360 longitude convention
lon_min, lon_max = 260.0, 300.0 # 100W to 60W
lat_min, lat_max = 15.0, 40.0 # 15N to 40N
lon_mask = (lon_coords >= lon_min) & (lon_coords <= lon_max)
lat_mask = (lat_coords >= lat_min) & (lat_coords <= lat_max)
u_carib = u[np.ix_(lat_mask, lon_mask)]
lat_carib = lat_coords[lat_mask]
lon_carib = lon_coords[lon_mask]
# Convert to -180..180 for plotting
lon_carib_deg = ((lon_carib + 180.0) % 360.0) - 180.0
fig, ax = plt.subplots(subplot_kw={"projection": ccrs.PlateCarree()}, figsize=(8, 4.5))
pcm = ax.pcolormesh(
lon_carib_deg,
lat_carib,
u_carib,
shading="auto",
cmap="RdBu_r",
vmin=-30,
vmax=30,
transform=ccrs.PlateCarree(),
)
ax.set_extent([-100.0, -60.0, lat_min, lat_max], crs=ccrs.PlateCarree())
ax.coastlines(resolution="110m", linewidth=0.8)
ax.gridlines(draw_labels=True, linewidth=0.5, alpha=0.5, linestyle="--")
plt.colorbar(pcm, ax=ax, label=f"{u_var} (m/s)", pad=0.08, shrink=0.92)
ax.set_title("Guided TC Sample: 10m Zonal Wind")
plt.tight_layout()
plt.savefig("outputs/05_cbottle_tc_guided_sample.jpg")

Computing the Odds Ratio¶
The odds ratio requires computing Hutchinson divergence terms that need second-order
derivatives through the model. We reload with allow_second_order_derivatives=True
for odds ratio calculations.
Note: sampler_steps is also reduced in this section to speed up runtime. Use
the default sampler settings for improved quality and more stable odds-ratio values.
model = CBottleTCGuidance.load_model(
package,
seed=0,
sampler_steps=2,
allow_second_order_derivatives=True,
).to(device)
log_odds_ratio, forward_latents, latent_coords = model.calculate_odds_ratio(
guidance,
coords,
)
print(f"Log odds ratio: {log_odds_ratio:.4f}")
print(f"Forward latents shape: {tuple(forward_latents.shape)}")
Console output89 lines
calculate_odds_ratio[forward]: 0%| | 0/27 [00:00<?, ?it/s]
calculate_odds_ratio[forward]: 4%|โ | 1/27 [00:01<00:38, 1.49s/it]
calculate_odds_ratio[forward]: 7%|โ | 2/27 [00:02<00:35, 1.42s/it]
calculate_odds_ratio[forward]: 11%|โ | 3/27 [00:04<00:33, 1.41s/it]
calculate_odds_ratio[forward]: 15%|โโ | 4/27 [00:05<00:32, 1.41s/it]
calculate_odds_ratio[forward]: 19%|โโ | 5/27 [00:07<00:30, 1.41s/it]
calculate_odds_ratio[forward]: 22%|โโโ | 6/27 [00:08<00:29, 1.41s/it]
calculate_odds_ratio[forward]: 26%|โโโ | 7/27 [00:09<00:28, 1.41s/it]
calculate_odds_ratio[forward]: 30%|โโโ | 8/27 [00:11<00:26, 1.40s/it]
calculate_odds_ratio[forward]: 33%|โโโโ | 9/27 [00:12<00:25, 1.39s/it]
calculate_odds_ratio[forward]: 37%|โโโโ | 10/27 [00:14<00:26, 1.57s/it]
calculate_odds_ratio[forward]: 41%|โโโโ | 11/27 [00:16<00:24, 1.53s/it]
calculate_odds_ratio[forward]: 44%|โโโโโ | 12/27 [00:17<00:22, 1.49s/it]
calculate_odds_ratio[forward]: 48%|โโโโโ | 13/27 [00:18<00:20, 1.48s/it]
calculate_odds_ratio[forward]: 52%|โโโโโโ | 14/27 [00:20<00:19, 1.47s/it]
calculate_odds_ratio[forward]: 56%|โโโโโโ | 15/27 [00:21<00:17, 1.45s/it]
calculate_odds_ratio[forward]: 59%|โโโโโโ | 16/27 [00:23<00:15, 1.44s/it]
calculate_odds_ratio[forward]: 63%|โโโโโโโ | 17/27 [00:24<00:14, 1.44s/it]
calculate_odds_ratio[forward]: 67%|โโโโโโโ | 18/27 [00:26<00:12, 1.43s/it]
calculate_odds_ratio[forward]: 70%|โโโโโโโ | 19/27 [00:27<00:11, 1.43s/it]
calculate_odds_ratio[forward]: 74%|โโโโโโโโ | 20/27 [00:28<00:09, 1.42s/it]
calculate_odds_ratio[forward]: 78%|โโโโโโโโ | 21/27 [00:30<00:08, 1.44s/it]
calculate_odds_ratio[forward]: 81%|โโโโโโโโโ | 22/27 [00:31<00:07, 1.46s/it]
calculate_odds_ratio[forward]: 85%|โโโโโโโโโ | 23/27 [00:33<00:05, 1.45s/it]
calculate_odds_ratio[forward]: 89%|โโโโโโโโโ | 24/27 [00:34<00:04, 1.44s/it]
calculate_odds_ratio[forward]: 93%|โโโโโโโโโโ| 25/27 [00:36<00:02, 1.45s/it]
calculate_odds_ratio[forward]: 96%|โโโโโโโโโโ| 26/27 [00:37<00:01, 1.43s/it]
calculate_odds_ratio[forward]: 100%|โโโโโโโโโโ| 27/27 [00:38<00:00, 1.43s/it]
calculate_odds_ratio[backward]: 0%| | 0/26 [00:00<?, ?it/s]
calculate_odds_ratio[backward]: 4%|โ | 1/26 [00:07<02:55, 7.02s/it]
calculate_odds_ratio[backward]: 8%|โ | 2/26 [00:13<02:36, 6.50s/it]
calculate_odds_ratio[backward]: 12%|โโ | 3/26 [00:21<02:49, 7.39s/it]
calculate_odds_ratio[backward]: 15%|โโ | 4/26 [00:29<02:50, 7.74s/it]
calculate_odds_ratio[backward]: 19%|โโ | 5/26 [00:38<02:47, 7.97s/it]
calculate_odds_ratio[backward]: 23%|โโโ | 6/26 [00:46<02:42, 8.12s/it]
calculate_odds_ratio[backward]: 27%|โโโ | 7/26 [00:55<02:35, 8.19s/it]
calculate_odds_ratio[backward]: 31%|โโโ | 8/26 [01:03<02:28, 8.25s/it]
calculate_odds_ratio[backward]: 35%|โโโโ | 9/26 [01:11<02:20, 8.26s/it]
calculate_odds_ratio[backward]: 38%|โโโโ | 10/26 [01:19<02:12, 8.28s/it]
calculate_odds_ratio[backward]: 42%|โโโโโ | 11/26 [01:28<02:05, 8.33s/it]
calculate_odds_ratio[backward]: 46%|โโโโโ | 12/26 [01:36<01:56, 8.33s/it]
calculate_odds_ratio[backward]: 50%|โโโโโ | 13/26 [01:45<01:51, 8.56s/it]
calculate_odds_ratio[backward]: 54%|โโโโโโ | 14/26 [01:54<01:42, 8.56s/it]
calculate_odds_ratio[backward]: 58%|โโโโโโ | 15/26 [02:02<01:33, 8.48s/it]
calculate_odds_ratio[backward]: 62%|โโโโโโโ | 16/26 [02:11<01:24, 8.45s/it]
calculate_odds_ratio[backward]: 65%|โโโโโโโ | 17/26 [02:19<01:16, 8.48s/it]
calculate_odds_ratio[backward]: 69%|โโโโโโโ | 18/26 [02:28<01:07, 8.45s/it]
calculate_odds_ratio[backward]: 73%|โโโโโโโโ | 19/26 [02:36<00:59, 8.44s/it]
calculate_odds_ratio[backward]: 77%|โโโโโโโโ | 20/26 [02:44<00:50, 8.43s/it]
calculate_odds_ratio[backward]: 81%|โโโโโโโโ | 21/26 [02:53<00:42, 8.45s/it]
calculate_odds_ratio[backward]: 85%|โโโโโโโโโ | 22/26 [03:01<00:33, 8.45s/it]
calculate_odds_ratio[backward]: 88%|โโโโโโโโโ | 23/26 [03:10<00:25, 8.45s/it]
calculate_odds_ratio[backward]: 92%|โโโโโโโโโโ| 24/26 [03:18<00:16, 8.42s/it]
calculate_odds_ratio[backward]: 96%|โโโโโโโโโโ| 25/26 [03:26<00:08, 8.40s/it]
calculate_odds_ratio[backward]: 100%|โโโโโโโโโโ| 26/26 [03:33<00:00, 7.90s/it]
calculate_odds_ratio[backward_no_guidance]: 0%| | 0/26 [00:00<?, ?it/s]
calculate_odds_ratio[backward_no_guidance]: 4%|โ | 1/26 [00:05<02:17, 5.52s/it]
calculate_odds_ratio[backward_no_guidance]: 8%|โ | 2/26 [00:11<02:12, 5.53s/it]
calculate_odds_ratio[backward_no_guidance]: 12%|โโ | 3/26 [00:16<02:07, 5.54s/it]
calculate_odds_ratio[backward_no_guidance]: 15%|โโ | 4/26 [00:22<02:02, 5.55s/it]
calculate_odds_ratio[backward_no_guidance]: 19%|โโ | 5/26 [00:27<01:56, 5.55s/it]
calculate_odds_ratio[backward_no_guidance]: 23%|โโโ | 6/26 [00:33<01:51, 5.60s/it]
calculate_odds_ratio[backward_no_guidance]: 27%|โโโ | 7/26 [00:39<01:46, 5.59s/it]
calculate_odds_ratio[backward_no_guidance]: 31%|โโโ | 8/26 [00:44<01:41, 5.62s/it]
calculate_odds_ratio[backward_no_guidance]: 35%|โโโโ | 9/26 [00:50<01:35, 5.63s/it]
calculate_odds_ratio[backward_no_guidance]: 38%|โโโโ | 10/26 [00:55<01:29, 5.62s/it]
calculate_odds_ratio[backward_no_guidance]: 42%|โโโโโ | 11/26 [01:01<01:24, 5.62s/it]
calculate_odds_ratio[backward_no_guidance]: 46%|โโโโโ | 12/26 [01:07<01:18, 5.63s/it]
calculate_odds_ratio[backward_no_guidance]: 50%|โโโโโ | 13/26 [01:12<01:13, 5.64s/it]
calculate_odds_ratio[backward_no_guidance]: 54%|โโโโโโ | 14/26 [01:18<01:07, 5.63s/it]
calculate_odds_ratio[backward_no_guidance]: 58%|โโโโโโ | 15/26 [01:24<01:01, 5.61s/it]
calculate_odds_ratio[backward_no_guidance]: 62%|โโโโโโโ | 16/26 [01:30<00:57, 5.76s/it]
calculate_odds_ratio[backward_no_guidance]: 65%|โโโโโโโ | 17/26 [01:35<00:51, 5.70s/it]
calculate_odds_ratio[backward_no_guidance]: 69%|โโโโโโโ | 18/26 [01:41<00:45, 5.64s/it]
calculate_odds_ratio[backward_no_guidance]: 73%|โโโโโโโโ | 19/26 [01:46<00:39, 5.61s/it]
calculate_odds_ratio[backward_no_guidance]: 77%|โโโโโโโโ | 20/26 [01:52<00:33, 5.59s/it]
calculate_odds_ratio[backward_no_guidance]: 81%|โโโโโโโโ | 21/26 [01:57<00:27, 5.58s/it]
calculate_odds_ratio[backward_no_guidance]: 85%|โโโโโโโโโ | 22/26 [02:03<00:22, 5.57s/it]
calculate_odds_ratio[backward_no_guidance]: 88%|โโโโโโโโโ | 23/26 [02:08<00:16, 5.57s/it]
calculate_odds_ratio[backward_no_guidance]: 92%|โโโโโโโโโโ| 24/26 [02:14<00:11, 5.57s/it]
calculate_odds_ratio[backward_no_guidance]: 96%|โโโโโโโโโโ| 25/26 [02:20<00:05, 5.57s/it]
calculate_odds_ratio[backward_no_guidance]: 100%|โโโโโโโโโโ| 26/26 [02:25<00:00, 5.59s/it]
Log odds ratio: -0.1073
Forward latents shape: (1, 45, 721, 1440)Post Processing Forward Latents¶
The forward_latents tensor is returned on the same grid as the model output
(lat-lon when lat_lon=True). We visualize a single channel (u10m) over the same
Caribbean domain. This shows the latent-space representation that the odds-ratio
computation operates on.
plt.close("all")
# Identify the u10m channel in output variable ordering
latent_variables = latent_coords["variable"]
u_latent_idx = int(np.where(latent_variables == u_var)[0][0])
latent_u = forward_latents[0, u_latent_idx].detach().cpu().numpy()
latent_u_carib = latent_u[np.ix_(lat_mask, lon_mask)]
fig, ax = plt.subplots(subplot_kw={"projection": ccrs.PlateCarree()}, figsize=(8, 4.5))
pcm = ax.pcolormesh(
lon_carib_deg,
lat_carib,
latent_u_carib,
shading="auto",
cmap="viridis",
transform=ccrs.PlateCarree(),
)
ax.set_extent([-100.0, -60.0, lat_min, lat_max], crs=ccrs.PlateCarree())
ax.coastlines(resolution="110m", linewidth=0.8)
ax.gridlines(draw_labels=True, linewidth=0.5, alpha=0.5, linestyle="--")
plt.colorbar(pcm, ax=ax, label=f"Forward Latent ({u_var})", pad=0.08, shrink=0.92)
ax.set_title(f"Forward Latents: {u_var} Channel")
plt.tight_layout()
plt.savefig("outputs/05_cbottle_tc_forward_latents.jpg")
