rdb_ocean_porous Module

Adcroft (2013) three-parameter porous-barrier fit for the ocean C-grid dyn-core.

A model face is a straight segment of length dy_cu (u-face) or dx_cv (v-face), but the real seafloor along that segment is not flat: a strait or a sill leaves only PART of the segment open at a given depth. Porous barriers replace the binary open/closed face with a depth-dependent OPEN FRACTION, so a deep sill blocks the bottom layers while the surface layers stay fully open. The face stays a single C-grid degree of freedom — only the transport width narrows.

The along-face seafloor is summarised by three numbers per face, all TOPOGRAPHIC HEIGHTS (positive up, negative below the sea surface) so they compare directly against interface heights. NOTE the ocean path’s barotropic%b is the opposite sign — a reference column DEPTH, positive down (SSH = sum(h_layer) - b) — so the caller negates it once when filling metrics%por_bed: * d_min — deepest along-face point (most negative), * d_max — shallowest along-face point (least negative), * d_avg — mean along-face height, d_min <= d_avg <= d_max.

Adcroft’s fit picks the one-parameter family of monotone profiles that reproduces exactly those three numbers. With m = (d_avg - d_min) / (d_max - d_min) (nondim, in [0,1]) zeta = (eta - d_min) / (d_max - d_min) (nondim) a = (1 - m) / m the OPEN WIDTH FRACTION at an interface of height eta is w(eta) = 0 for eta <= d_min, w(eta) = zeta**(1/a) for m < 1/2, w(eta) = zeta for m = 1/2, w(eta) = 1 - (1 - zeta)**a for m > 1/2, w(eta) = 1 for eta > d_max, and its vertical integral from the bottom (units of length) is A(eta) = 0 eta <= d_min, A(eta) = (d_max-d_min) * (1-m) * zeta**(1/(1-m)) m < 1/2, A(eta) = (d_max-d_min) * 0.5*zeta*zeta m = 1/2, A(eta) = (d_max-d_min) * (zeta - m + m*(1-zeta)**(1/m)) m > 1/2, A(eta) = eta - d_avg eta > d_max. dA/d(eta) = w(eta) identically, and both branches join continuously at eta = d_max where A = (d_max-d_min)*(1-m).

The LAYER-AVERAGED open AREA fraction of layer k, whose lower and upper interfaces sit at face heights eta_lo / eta_hi, is the mean of w over the layer, obtained exactly from the cumulative integral: por_face_area(k) = min(1, (A(eta_hi) - A(eta_lo))/(eta_hi - eta_lo)) with a zero fallback for a vanishing layer. It multiplies the face width in the transport: uh = u * h_face * dy_cu * por_face_area_u.

Reference: Adcroft, A. (2013), “Representation of topography by porous barriers and objective interpolation of topographic data”, Ocean Modelling 67, 13-27. MOM6’s MOM_porous_barriers was the inspiration for the discrete layer-averaging and the eta-at-velocity interpolation options; this is an independent implementation re-derived from the paper’s fit.

SUBGRID DATA CAVEAT. The fit needs min/max/mean of the HIGH-RESOLUTION seafloor along each face — a statistic that can only come from a bathymetry dataset finer than the model grid (MOM6 reads it from an offline-generated topog_edge.nc). Roundabout has no such file plumbing yet, so the shipped source is POROUS_SOURCE_RESOLVED: min/max/mean of the RESOLVED bathymetry sampled at three along-face points (south corner, midpoint, north corner for a u-face). That is a genuine along-face statistic of the data we have, NOT true subgrid information — it captures along-face slope but cannot see structure below the grid scale. POROUS_SOURCE_FILE is the honest MOM6-parity path and fails loud pending the file-forcing backend (the same gate the barotropic wave-drag form="file" waits on).

WHAT THE PROXY ACTUALLY DOES — read this before trusting it. All three samples are CELL-CENTRE AVERAGES, so the statistic only sees variation ALONG the face. * Bathymetry uniform ALONG the face — a ridge or shelf break that runs parallel to it, the common case — collapses all three samples onto one value. The fit would then be a STEP at the two-cell mean height: a hard wall on every layer below it, on a face the grid already resolves as open. That wall is manufactured by the fill routine, not information, so porous_update_face_areas treats a DEGENERATE face (d_max <= d_min) as FULLY OPEN and blocks nothing. A flat seafloor is the same degenerate case, which is also what makes the resolved source a literal no-op on a flat basin. * Where the bathymetry DOES vary along the face, the narrowing is set by the spread of the three corner-mean samples. A face whose along-face spread is small compared with the water depth still yields a near-step over that narrow spread — the fit is only ever as smooth as the sampled spread. Genuinely graded narrowing needs real subgrid data (source="file").

WET-CELL GATING. A corner sample averages four cells; if any of them is LAND its elevation would pull d_max up and manufacture blockage on a face the grid resolves as fully open. porous_fill_stats_resolved therefore drops a corner sample whose four-cell stencil is not entirely wet, falling back to the two-cell face midpoint for that sample.

VANISHING-LAYER THRESHOLD. A layer whose face thickness is at or below H_VANISHED (1.5e-4 m) is given por = 0. MOM6 instead uses Angstrom_Z (1e-10 m), 1.5 million times smaller, so a layer between the two thresholds gets a real open fraction there and zero here. The consequence is that por_col (the column-integrated fraction the barotropic width carries) is the thickness-weighted mean of the per-layer fractions only over the NON-vanished layers. H_VANISHED is the repo-wide dynamic-vanish constant (rdb_constants), not a porous-barrier choice.

NOT NARROWED. areaCu / areaCv keep their full geometric value: only the TRANSPORT widths are narrowed (dy_cu / dx_cv per layer and dy_cu_bt / dx_cv_bt for the barotropic mode). The barotropic Coriolis and KE terms therefore combine a narrowed transport with an un-narrowed cell area — the same split MOM6 has, but worth knowing before reading a BT energy budget under a strong barrier.