pyfvcom2.bathy_smoother module

class pyfvcom2.bathy_smoother.BathymetrySmoother

Bases: ABC

Abstract base class for FVCOM bathymetry smoothers.

All concrete smoothers must implement smooth(). The shared r_factor() method computes the Haney r-factor distribution for the current grid bathymetry.

Note

Only cold-start workflows are supported. Smoothing the bathymetry after a hot-start restart file has been generated would produce an internally inconsistent restart because the stored 3-D fields are referenced to the original sigma-coordinate depths. Apply smoothing before generating any forcing or restart files.

r_factor(grid: Grid) → np.ndarray

Return the Haney r-factor for every inter-element edge.

Edges adjacent to at least one intertidal element (element-mean depth ≤ 0) are returned as numpy.nan and excluded from the assessment. Use numpy.nanmax() / numpy.nanmean() to compute statistics, and note that r > threshold comparisons naturally treat NaN as False.

Args:

grid: Grid instance to evaluate.

Returns:

Array of r-factor values, one per shared edge. Values near zero indicate a smooth transition; values near 1 indicate a near-step change. Intertidal edges are numpy.nan. A commonly used threshold is \(r < 0.2\).

abstractmethod smooth(grid: Grid) → None

Smooth the bathymetry of grid in-place.

Modifies grid._h (node depths) and grid._hc (element-centroid depths) directly.

Args:

grid: Grid instance to modify.

class pyfvcom2.bathy_smoother.GlobalBathymetrySmoother(passes: int = 1)

Bases: BathymetrySmoother

Global ping-pong bathymetry smoother.

Applies one or more passes of a two-step linear interpolation:

1. Interpolate node depths → element-centroid depths (LinearNDInterpolator over the node positions).

2. Interpolate the smoothed element depths → node depths (LinearNDInterpolator over the centroid positions).

Each pass is mathematically equivalent to one iteration of graph-Laplacian smoothing, reducing sharp depth gradients uniformly across the entire mesh. Boundary nodes that fall outside the convex hull of the centroids (step 2) retain their original depth.

Args:

passes: Number of complete node→centroid→node round-trips to apply.

More passes produce stronger smoothing but progressively erode bathymetric features. Defaults to 1.

smooth(grid: Grid) → None

Apply global ping-pong smoothing to grid in-place.

Args:

grid: Grid instance to modify.