velocity

WLS cell-centre velocity reconstruction from HEC-RAS face normal velocities.

This module contains pure-numpy functions for cell-centre WLS velocity reconstruction. They are called by FlowAreaResults which provides the mesh geometry arrays. Face and facepoint velocity reconstruction uses the RASMapper-exact pipeline in rivia.geo._rasmap.

Background

HEC-RAS 2-D solves for face normal velocities (velocity component perpendicular to each cell face) as primary unknowns. Cell-centre velocity vectors are a derived quantity reconstructed via the weighted least-squares (WLS) method described in the HEC-RAS Technical Reference Manual (Section: 2D Unsteady Flow - Numerical Methods - Cell Velocity).

The 2x2 WLS system (per cell, summing over its k faces):

[a11 a12] [u] [b1] [a12 a22] [v] = [b2]

a11 = sum(w_k * nx_k**2) a22 = sum(w_k * ny_k**2) a12 = sum(w_k * nx_k * ny_k) b1 = sum(w_k * V_n,k * nx_k) b2 = sum(w_k * V_n,k * ny_k)

Solved via Cramer’s rule:

det = a11*a22 - a12**2 u = (a22*b1 - a12*b2) / det v = (a11*b2 - a12*b1) / det

Weights w_k are either:

• "area_weighted"wetted face flow areas interpolated from the

  per-face hydraulic property tables at the estimated face WSE. This matches HEC-RAS’s internal reconstruction.

• "length_weighted": face plan-view lengths (column 2 of

  Faces NormalUnitVector and Length). Simpler; no table lookup.

Sign convention note

The stored face normal n_hat_stored points from the left cell to the right cell (Faces Cell Indexes col 0 -> col 1). Orientation (+1/-1) records whether n_hat_stored is outward (+1) or inward (-1) relative to the current cell. Orientation cancels in the WLS product V_n * n_hat, so the stored values are used directly.

rivia.hdf.velocity.compute_all_cell_velocities(n_cells, cell_face_info, cell_face_values, face_normals, face_cell_indexes, face_ae_info, face_ae_values, face_normal_velocity, cell_wse, method='area_weighted', face_flow=None, wse_interp='average', cell_centers=None, face_velocity_coords=None)

Compute WLS cell-centre velocity vectors for real cells.

Ghost cells are not reconstructed: HEC-RAS stores no face normal velocities for ghost-only faces, so the WLS system for a ghost cell would be severely underdetermined (one face, two unknowns). Ghost-cell WSE values in cell_wse are still used by the face-WSE estimators to improve accuracy at boundary faces of real cells.

Parameters:

• n_cells (int) – Number of real computational cells.

• cell_face_info (ndarray, shape (>= n_cells, 2)) – [start_index, count] into cell_face_values.

• cell_face_values (ndarray, shape (total, 2)) – [face_index, orientation] for each cell-face pair.

• face_normals (ndarray, shape (n_faces, 3)) – [nx, ny, face_length].

• face_cell_indexes (ndarray, shape (n_faces, 2)) – Left and right cell indices per face.

• face_ae_info (ndarray, shape (n_faces, 2)) – Area-elevation table index for each face.

• face_ae_values (ndarray, shape (total, 4)) – Area-elevation table values.

• face_normal_velocity (ndarray, shape (n_faces,)) – Signed face normal velocities for this timestep.

• cell_wse (ndarray, shape (n_cells,) or (n_cells + n_ghost,)) – Cell-centre water-surface elevations. Ghost-cell WSEs (indices >= n_cells) are used by the face-WSE estimators but are not reconstructed as velocity vectors.

• method (str) – "area_weighted" (default, matches HEC-RAS), "length_weighted" (simpler, no table lookup), or "flow_ratio" (requires face_flow; back-calculates flow area as |Q|/|V_n|, exactly as HEC-RAS computed internally).

• face_flow (ndarray, shape (n_faces,), optional) – Volumetric face flows. Required when method="flow_ratio".

• wse_interp (str) – How to estimate face WSE when method="area_weighted". "average" (default) — simple mean of the two adjacent cell WSEs. "sloped" — distance-weighted linear interpolation at the face’s actual position between the two cell centres (requires cell_centers and face_velocity_coords). "max" — maximum of the two adjacent cell WSEs (conservative; tends to increase flow area at partially-wet faces).

• cell_centers (ndarray, shape (n_cells + n_ghost, 2), optional) – X, Y coordinates of cell centres. Must cover ghost rows when wse_interp="sloped" so boundary faces are interpolated correctly. Required when wse_interp="sloped".

• face_velocity_coords (ndarray, shape (n_faces, 2), optional) – X, Y position of the face normal velocity measurement point. Typically the face centroid or the face normal intercept. Required when wse_interp="sloped".

Returns:

[Vx, Vy] depth-averaged velocity at each real cell centre.

Return type:

ndarray, shape (n_cells, 2)