← freeCAM docs
PI-atm · ne16 · CAM5 · 512 ranks · online-coupled · 1488 steps

The new shallow-convection model over a full month

CAM's shallow-convection calculation, compute_uwshcu_inv, was replaced by a new model and run for a full month, then compared with the original Fortran and with the MLP model now in use, for accuracy and speed. The new model needs a layer of limits on its outputs to get through the month; that layer is shown below as well.

Accuracy · Figure 3 0.41 vs 0.50–0.54

Median deviation of all output fields from the original Fortran over the month. Variable by variable, it is closer than the MLP on 18–19 of the 19 main variables.

Speed · Figure 2 1.32× / 1.60×

The new model's run time for the month as a multiple of the original Fortran's (GPU / CPU). The MLP model: 1.10× / 0.98×.

Precondition · Figure 1 Step 100

Without limits, the run stops here on a NaN. With the output limits, both runs complete the month.

Configuration
iCESM1.3.1 PI-atm, ne16, CAM5 physics, SE dynamics, 512 MPI ranks
Length
1488 steps of 30 minutes, 31 days in all
Coupling
Online: land, sea ice, ocean and rivers all run live, not an offline replay
Timing
Time in the coupled main loop. Each job runs the original Fortran first, then the model; every multiple is taken against the original Fortran in the same job
Hardware
CPU: 4 nodes. GPU: 4 nodes with 4 A100s each (shared through MPS)
Calls
About 1.52 million shallow-convection calls per run (512 ranks combined)
Figure 1 · Limits

Dropped in as is, the model cannot finish a run

With the model plugged in directly, the run stops at about step 100. Traced back, it starts from a negative number that is almost zero:

  1. From step 1The model's convective cloud fraction cufrc is about −5×10⁻¹⁰, just below 0. The original Fortran never gives a negative cloud fraction.
  2. Thencloud_fraction.F90 uses it directly, and the total cloud fraction CLD turns negative.
  3. ThenThe photochemistry in mo_photo.F90 computes clouds1.5; a negative number raised to the power 1.5 gives NaN.
  4. Step 3H2O2 becomes NaN over the whole globe. H2O2 is one of the model's inputs, so the model then outputs NaN in every column.
  5. Step 100When the output file is written, netCDF refuses to write NaN and the run stops.

The first attempt replaced every NaN with 0. The run no longer failed, but from step 3 on, shallow convection was in effect switched off: the results looked normal but were wrong. So the limit layer now sets only the padding rows, which carry no data, to 0; a NaN in a real column is left as it is, so that the model stops.

The limit layer puts back, around the model's outputs, the bounds the original Fortran already guarantees. The items tagged "original guarantee" matter most:

LimitOutputs affectedWhy
Non-negative quantities stay ≥ 0original guaranteeumf, flxprc1, flxsnow1, qrten, qsten, precip, snow, evapc, cufrc, qcu, qlu, qiu, cbmf, qc, rliqIn a month of samples the original Fortran never makes these 15 negative; they are clipped to ≥ 0
Cloud fraction at most 1original guaranteecufrc ≤ 1Cloud fraction is a proportion
Cloud-top / cloud-base levels roundedoriginal guaranteecnt, cnb → rounded, limited to 1–30Level indices are integers; the model has 30 levels
No-convection flagcush ≥ −1The original Fortran gives −1 when there is no convection
Water not taken below zeroqvten, qlten, qitenWithin one step, vapor, liquid water and ice cannot be reduced below 0
Snow at most precipitationsnow ≤ precip; flxsnow1 ≤ flxprc1 at every levelSnow is part of precipitation
Isotopes derived from water ratios608 water-isotope outputsThe model's isotope outputs exceed 10¹⁹ and cannot be used. They are derived instead from the limited water tendencies, at each isotope's ratio to water in the column
Padding rows output 0Rows beyond each chunk's actual columnsThese rows have no pressure data and the model outputs NaN on them; they are never used
Figure 2 · Speed

The new model computes more per call and is slower than the MLP

Month run time as a multiple of the original Fortran 0× 0.5× 1× 1.5× 1.60× 1.32× 0.98× 1.10× Original Fortran = 1 CPU GPU
Month run time divided by that of the original Fortran in the same job. Below the dashed line means faster than the original Fortran. Hover to see the seconds.

The gap comes from the computation in each call. One call computes one chunk of at most 16 columns (pcols = 16), and each rank makes 2 calls per step: over the month's 1488 steps that is 2,976 calls per rank and 1,523,712 across the 512 ranks. A rank's total shallow-convection time is its number of calls times the milliseconds per call. The 512 ranks run at the same time, so the month's run time follows each rank's 2,976 calls; the 1,523,712 calls of all 512 ranks times the milliseconds per call is the computation summed over the ranks, not wall-clock time. The original Fortran takes about 8.2 ms per call (CPU node). The new model takes 92.6 ms per call on CPU, 11 times the original Fortran and 22 times the MLP (4.3 ms); over the month the model alone costs each rank 276 seconds, where the original Fortran's shallow convection needs only about 24 seconds. The GPU brings the new model down to 39.7 ms per call, so it is clearly faster on GPU than on CPU. The MLP takes only half the original Fortran's time per call, so on CPU its month is slightly faster than the original Fortran.

These per-call figures agree with the month run times: on CPU the new model's shallow convection costs about 252 seconds more than the original Fortran, and the month is in fact 262 seconds slower; the MLP costs about 12 seconds less, and the month is 10 seconds faster. On GPU, both models' month times exceed this estimate by about 40–46 seconds, a fixed cost of running on the GPU (startup, warm-up and so on) that does not depend on the computation per call. The original Fortran's per-call times come from 50-step shadow runs (the model and the original Fortran both run on the same call and are timed separately; CPU-node job 7541265, GPU-node job 7546109), averaged over 51,200 calls (512 ranks × 50 steps × 2); the month runs time only the model. In the 2 initialization steps each rank makes another 4 calls, computed by the original Fortran and not included in the counts above.

Month run timeModel calls in the monthShallow convection per call (ms)Shallow convection per rank over the month (s)
Original Fortran (s)Model run (s)MultiplePer rank512 ranks totalOriginal FortranModelModel ÷ originalOriginal FortranModel
New model · CPU440.1702.61.602,9761,523,7128.292.611.34×24276.1
New model · GPU462.7609.41.322,9761,523,7126.139.76.54×18118.6
MLP model · CPU442.4432.00.982,9761,523,7128.24.30.52×2412.7
MLP model · GPU467.1513.21.102,9761,523,7126.14.30.72×1824.7
Figure 3 · Accuracy

The new model stays closer to the original Fortran

For each variable at each output time: the root-mean-square difference between the model run and the original Fortran, divided by the standard deviation of the original Fortran's field itself. 0 means identical; 1 means the difference is as large as the field's own variability. Output is written every 100 steps (about 2 days), 14 times over the month. When freeCAM replaces nothing, all 19 variables are 0.

One variable per row. The longer the line between the two dots, the more the two models differ; the further left a dot, the closer to the original Fortran. Click a row to see below how that variable evolves over the month.
T (Temperature): deviation from the original Fortran over the month, one point every 100 steps. The vertical axis scales with the selected variable.

By the month median, the new model is closer to the original Fortran than the MLP on 18 (CPU) and 19 (GPU) of the 19 variables. Deviations grow with time, and by the end of the month the gap narrows: for clouds, precipitation and meridional wind both models are near or above 1, essentially uncorrelated with the original Fortran by then, and the new model is smaller on 17 (CPU) and 12 (GPU) of the variables. The same new model run twice, on CPU and on GPU, also differs by 0.00–0.09 at month end; smaller differences than that are treated as noise.

CPUGPU
Month medianMonth endMonth medianMonth end
New modelMLPNew modelMLPNew modelMLPNew modelMLP
Atmospheric state
T Temperature0.050.070.100.120.050.070.100.11
Q Specific humidity0.130.150.250.240.130.150.220.22
U Zonal wind0.270.300.480.540.260.280.490.52
V Meridional wind0.670.811.131.200.640.711.101.14
PS Surface pressure0.070.100.130.140.070.080.140.14
TS Surface temperature0.120.190.230.270.130.180.230.23
TMQ Column water vapor0.240.270.470.450.230.260.440.42
Precipitation
PRECT Total precipitation0.840.831.061.110.820.831.051.07
PRECC Convective precipitation0.670.700.991.070.680.680.991.01
PRECL Large-scale precipitation1.041.081.111.151.031.111.091.11
Clouds
CLDLOW Low cloud cover0.690.890.880.960.670.890.820.96
CLDMED Mid cloud cover0.830.931.101.140.810.931.061.09
CLDHGH High cloud cover0.880.981.241.280.830.911.231.19
CLDTOT Total cloud cover0.780.921.081.090.740.911.041.05
TGCLDLWP Cloud liquid water path0.951.051.151.290.931.091.211.27
Radiation and surface fluxes
FLNT TOA net longwave0.590.610.840.870.570.580.830.81
FSNT TOA net shortwave0.270.290.390.390.270.300.370.39
LHFLX Latent heat flux0.450.520.700.700.430.510.710.69
SHFLX Sensible heat flux0.540.720.770.860.500.600.860.83

Bold cells are those where the new model is smaller than the MLP.

All 2838 output fields together

The 19 above are the main variables. Counting every time-varying field in the output files, with one deviation value per field, the distribution of those values is shown below.

Deviation of each output field from the original Fortran over the month 0 0.5 1 1.5 2 2.5 3 3.5 New model · CPU 0.41 New model · GPU 0.41 MLP model · CPU 0.54 MLP model · GPU 0.50
Here each field's deviation is computed over all output times of the month together.

The new model's median of 0.41 is about 20% below the MLP's 0.50–0.54; its maximum, 1.6 against the MLP's 2.9–3.3, differs more clearly. Results on CPU and GPU are almost the same.

Median90th percentileMaximumWater-isotope BIG ERROR warningsFields with NaN/InfJob ID
New model · CPU0.411.061.63107614456
New model · GPU0.411.041.60007614457
MLP model · CPU0.541.252.8614707580687
MLP model · GPU0.501.213.3422307591565

BIG ERROR is a warning in the model log: the tendencies of the tracer water tagged as H2O should equal those of ordinary water, and the warning is printed when their relative difference exceeds 10⁻¹⁰. Over the month the new model triggered it 1 time (CPU) and 0 times (GPU); the MLP model 147 and 223 times. The new model's isotopes and tracer water are derived proportionally from the limited water tendencies, so they match ordinary water essentially by construction. The 1 warning on CPU came at about step 294, on one rank, with a relative difference of 8.9×10⁻⁸. The difference between 1 and 0 is chance and does not mean the GPU is better: CPU and GPU compute in different orders, so after a few days the weather differs, and the two runs are like two samples of the same month; for the MLP it is the other way round, with more on the GPU. None of the four runs produced NaN or infinity.

Figure 4 · Limit-layer code

wrap_v4.py

Written with Claude Code. It wraps the original model compute_uwshcu_inv_trigger_gated_r5_packed.pt, passes its outputs through the limits of Figure 1, and saves the result as a new TorchScript file, uwshcu_trigger_gated_r5_v4.pt, which both runs in Figures 2 and 3 use. Click a note on the right to highlight the matching lines of code.

"""Version 4 of the wrapper around a packed compute_uwshcu_inv model: physical limits on its outputs.    wrap_v4.py <model.pt> <out.pt>The model's 582 bulk outputs pass through, then:  * outputs the original kernel never makes negative (in the month capture) are floored at 0:    umf, flxprc1, flxsnow1, qrten, qsten, precip, snow, evapc, cufrc, qcu, qlu, qiu, cbmf, qc, rliq;  * cufrc <= 1; cush >= -1 (the original's no-convection value); cnt and cnb rounded into [1, 30];  * the water tendencies may not take vapour, liquid or ice below zero within the step;  * snow <= precip, and the snow flux <= the precipitation flux at every interface;  * the water-isotope slots are derived from those (limited) water tendencies at the column's ratios;  * padding rows (the hook's rows past the chunk's columns: no surface pressure) answer 0.A NaN in a real column is left in place, so that CAM stops on it rather than running on zeros."""import sysimport torch SL = {"cush": (0, 1), "umf": (1, 32), "slflx": (32, 63), "qtflx": (63, 94), "flxprc1": (94, 125), "flxsnow1": (125, 156),      "qvten": (156, 186), "qlten": (186, 216), "qiten": (216, 246), "sten": (246, 276), "uten": (276, 306), "vten": (306, 336),      "qrten": (336, 366), "qsten": (366, 396), "precip": (396, 397), "snow": (397, 398), "evapc": (398, 428), "cufrc": (428, 458),      "qcu": (458, 488), "qlu": (488, 518), "qiu": (518, 548), "cbmf": (548, 549), "qc": (549, 579), "rliq": (579, 580),      "cnt": (580, 581), "cnb": (581, 582)}NON_NEGATIVE = ["umf", "flxprc1", "flxsnow1", "qrten", "qsten", "precip", "snow", "evapc", "cufrc", "qcu", "qlu", "qiu", "cbmf", "qc", "rliq"]  class Limited(torch.nn.Module):    def __init__(self, inner):        super().__init__()        self.inner = inner        mask = torch.zeros(582, dtype=torch.bool)        for n in NON_NEGATIVE:            a, b = SL[n]; mask[a:b] = True        self.register_buffer("nonneg", mask)        self.register_buffer("iv", torch.tensor([9, 16, 23, 30])); self.register_buffer("il", torch.tensor([10, 17, 24, 31]))        self.register_buffer("ii", torch.tensor([11, 18, 25, 32]))     def forward(self, dt, ps0_inv, zs0_inv, p0_inv, z0_inv, dp0_inv, u0_inv, v0_inv, qv0_inv, ql0_inv, qi0_inv, t0_inv, s0_inv,                tr0_inv, tke_inv, cldfrct_inv, concldfrct_inv, pblh, cush, dpdry0_inv):        # type: (Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor, Tensor) -> Tensor        n = t0_inv.shape[0]        # the hook's padding rows carry no pressure profile; the model answers NaN on them.  A real        # column's interface pressures reach the surface's (1e5 Pa); index 0 of the _inv arrays is the top        real = (torch.amax(ps0_inv, 1) > 1000.0) & torch.all(torch.isfinite(ps0_inv), 1)        full = self.inner(dt, ps0_inv, zs0_inv, p0_inv, z0_inv, dp0_inv, u0_inv, v0_inv, qv0_inv, ql0_inv, qi0_inv, t0_inv, s0_inv,                          tr0_inv, tke_inv, cldfrct_inv, concldfrct_inv, pblh, cush, dpdry0_inv)        y = full[:, 0:582].to(torch.float64)        y = torch.where(self.nonneg.unsqueeze(0), torch.clamp_min(y, 0.0), y)        rdt = 0.999999 / dt.reshape(1, 1)        qv = torch.maximum(y[:, 156:186], -torch.clamp_min(qv0_inv - 1.0e-12, 0.0) * rdt)        ql = torch.maximum(y[:, 186:216], -torch.clamp_min(ql0_inv, 0.0) * rdt)        qi = torch.maximum(y[:, 216:246], -torch.clamp_min(qi0_inv, 0.0) * rdt)        snow = torch.minimum(y[:, 397:398], y[:, 396:397])        flxsnow = torch.minimum(y[:, 125:156], y[:, 94:125])        y = torch.cat([torch.clamp_min(y[:, 0:1], -1.0), y[:, 1:125], flxsnow, qv, ql, qi, y[:, 246:397], snow, y[:, 398:428],                       torch.clamp_max(y[:, 428:458], 1.0), y[:, 458:580], torch.clamp(torch.round(y[:, 580:582]), 1.0, 30.0)], dim=1)        # water isotopes at the column's ratios, from the limited water tendencies        qv0 = qv0_inv.unsqueeze(2); ql0 = ql0_inv.unsqueeze(2); qi0 = qi0_inv.unsqueeze(2)        trv = torch.index_select(tr0_inv, 2, self.iv); trl = torch.index_select(tr0_inv, 2, self.il); tri = torch.index_select(tr0_inv, 2, self.ii)        rv = torch.clamp(torch.where(qv0 > 1.0e-12, trv / torch.clamp_min(qv0, 1.0e-30), torch.zeros_like(qv0)), 0.0, 4.0)        rl = torch.clamp(torch.where(ql0 > 1.0e-12, trl / torch.clamp_min(ql0, 1.0e-30), rv), 0.0, 4.0)        ri = torch.clamp(torch.where(qi0 > 1.0e-12, tri / torch.clamp_min(qi0, 1.0e-30), rv), 0.0, 4.0)        rdt3 = rdt.unsqueeze(2)        tv = torch.maximum(qv.unsqueeze(2) * rv, -torch.clamp_min(trv, 0.0) * rdt3)        tl = torch.maximum(ql.unsqueeze(2) * rl, -torch.clamp_min(trl, 0.0) * rdt3)        ti = torch.maximum(qi.unsqueeze(2) * ri, -torch.clamp_min(tri, 0.0) * rdt3)        trten = torch.stack([tv, tl, ti], dim=3).reshape(n, 360)        lf = torch.clamp((t0_inv - 248.0) / 20.0, 0.0, 1.0).unsqueeze(2)        qc = y[:, 549:579].unsqueeze(2)        wtqc = torch.stack([qc * lf * rv, qc * (1.0 - lf) * rv], dim=3).reshape(n, 240)        w = (qv0_inv * dp0_inv).unsqueeze(2)        rp = (rv * w).sum(1) / torch.clamp_min(w.sum(1), 1.0e-30)        out = torch.cat([y, trten, wtqc, y[:, 396:397] * rp, y[:, 397:398] * rp], dim=1)        return torch.where(real.unsqueeze(1), out, torch.zeros_like(out))  inner = torch.jit.load(sys.argv[1], map_location="cpu").eval()torch.jit.script(Limited(inner).eval()).save(sys.argv[2])print("saved", sys.argv[2])