quad_utils_mod

Overview

The quad_utils_mod module provides horizontal interpolation utilities for longitude–latitude grids that are logically rectangular. It supports regular, irregularly spaced, and fully curvilinear grids. Various forward operators use this interpolation routine to map between observation locations and model state variables.

The module implements both grid search and interpolation capabilities.

Supported Grid Types

The module supports three grid types:

GRID_QUAD_FULLY_REGULAR

A regular latitude–longitude grid with uniform spacing. Grid coordinates are defined analytically using starting values and constant increments. Example:

lat ↑
     (0,2) --- (1,2) --- (2,2)
       |        |        |
     (0,1) --- (1,1) --- (2,1)
       |        |        |
     (0,0) --- (1,0) --- (2,0)
                     → lon
GRID_QUAD_IRREG_SPACED_REGULAR

A logically rectangular grid with non-uniform spacing in longitude and/or latitude. Coordinates are defined using 1D arrays. Example:

lat ↑
     (0,2) ---- (1.5,2) ------ (3,2)
       |          |            |
     (0,1) ---- (1.5,1) ------ (3,1)
       |          |            |
     (0,0) ---- (1.5,0) ------ (3,0)
                          → lon
GRID_QUAD_FULLY_IRREGULAR

A curvilinear grid defined by 2D longitude and latitude arrays. Grid cells are general quadrilaterals and may be distorted. This type is used for dipole and tripole grids. Example:

lat ↑
         o--------o-------o
        /        /       /
       /        /       /
      o--------o-------o
      |      / |     /
      |    /   |   /
      o------o---o
                       → lon

All grid types are assumed to be logically rectangular.

General Workflow

Before using the interpolation utilities, the user must first identify the structure of the model grid. In particular, determine whether the grid is:

  • fully regular (uniform spacing),

  • logically rectangular with non-uniform spacing, or

  • fully irregular (curvilinear, defined by 2D coordinate arrays).

This classification determines how the interpolation handle is initialized and how grid coordinates are provided.

The typical usage pattern is:

  1. Initialize an interpolation handle using init_quad_interp with the appropriate grid type.

  2. Provide grid coordinate information using one of the set_* routines corresponding to the grid type.

  3. Locate the grid cell containing a given longitude/latitude using quad_lon_lat_locate.

  4. Interpolate values using quad_lon_lat_evaluate.

  5. Finalize and deallocate resources using finalize_quad_interp.

Interpolation Methods

Regular and Irregularly Spaced Grids

For regular and semi-regular grids, interpolation is performed using standard bilinear interpolation in index space. The method:

  • identifies the bounding grid indices,

  • computes fractional distances in longitude and latitude, and

  • performs sequential linear interpolation.

Fully Irregular Grids

For fully irregular grids, interpolation is performed in physical space using the four corners of the enclosing quadrilateral.

The interpolant is assumed a surface, defined as:

\[f(x, y) = a + b x + c y + d x y\]

The coefficients are determined from the values at the four corners of the quadrilateral by solving a local 3x3 linear system. This system is solved using Gaussian elimination with partial pivoting.

An optional rotation of the quadrilateral can be applied prior to interpolation to improve numerical behavior.

Search Algorithm

For fully irregular grids, a two-stage search is used to efficiently locate the containing quadrilateral:

  1. A coarse regular latitude–longitude grid is constructed.

  2. Each coarse grid cell stores a list of overlapping quadrilaterals.

  3. At runtime, only the subset of candidate quadrilaterals associated with the relevant coarse cell is searched.

This significantly reduces the computational cost compared to a global search.

Interpolation Options

The interpolation handle supports several configuration options:

global_grid

Indicates that the grid is global. Enables cyclic longitude and pole wrapping.

spans_lon_zero

Indicates that the grid crosses the 0/360 longitude discontinuity.

pole_wrap

Enables wrapping across the poles.

north_to_south

Indicates latitude ordering.

grid_staggering

Specifies the location of grid points relative to the cell (center, edges, or corners).

These options influence both search and interpolation behavior.

Special Considerations

Dipole and Tripole Grids

Dipole and tripole grids are treated as fully irregular grids. No special interpolation algorithm is used for these grids; instead, they are handled through the general quadrilateral interpolation framework.

Mask Handling

An optional mask can be provided for fully irregular grids. If any of the four corners of a quadrilateral cell are masked, interpolation within that cell is not performed.

Pole Handling

The module includes limited support for grids that wrap over the poles. In some cases, particularly for staggered grids, interpolation may fail near the pole. These cases are identified and flagged during the location step.

Limitations

  • Only logically rectangular grids are supported.

  • Fully unstructured meshes are not supported.

  • Fully irregular grids require storage of 2D longitude and latitude arrays, which may increase memory usage for very high-resolution grids.

  • Mask handling is conservative; partial-cell interpolation is not supported.

  • Interpolation in highly distorted or nearly degenerate quadrilaterals may fail due to ill-conditioning of the local system.

  • Multiple interpolation schemes are not currently implemented, although the framework allows for future extension.