pygmt.sph2grd: Compute grid from spherical harmonic coefficients

[seisman]

This issue serves as the central place for discussing and tracking the implementation of the pygmt.sph2grd function in PyGMT. The issue will be closed when the initial implementation is complete. Progress is tracked at PyGMT: Wrapping GMT modules.

Documentation

• GMT: https://docs.generic-mapping-tools.org/dev/sph2grd.html
• GMT.jl: https://www.generic-mapping-tools.org/GMTjl_doc/documentation/modules/sph2grd
• PyGMT: https://www.pygmt.org/dev/api/generated/pygmt.sph2grd.html

GMT Option Flags and Modifiers

☑️: Implemented; ⬜: To be implemented/discussed; Strikethrough: Won't implement.

• ⬜ -D [g|n]: Disable the cos(lat) conversion in the Legendre polynomials by selecting a normalization that is designed for geographic (g) or Cartesian (n) grids.
• ☑️ -G (outgrid): Output grid file name.
• ☑️ -I (spacing): Grid spacing.
• ⬜ -N m|s|g: Choose normalization for the coefficients: m for mathematical, s for Schmidt quasi-normalized, g for geodetic [Default is g].
• ⬜ -Q: If set, coefficients are expressed in terms of Legendre polynomials (not the default spherical harmonics).
• ☑️ -R (region): Output grid region.
• ☑️ -V (verbose): Verbosity level.
• -X/-Y: Use Figure.shift_origin instead.
• ☑️ -b (binary): Binary input/output.
• ⬜ -d: Replace NaN with a specified nodata value on input/output.
• ⬜ -e: Pattern matching to select input rows.
• ⬜ -f (coltypes): Column data types.
• ⬜ -g: Gap detection.
• ☑️ -h (header): Read/write header records.
• ☑️ -i (incols): Select input columns.
• ☑️ -r (registration): Set grid node registration to gridline or pixel.
• ⬜ -s: Skip rows containing NaN values.
• ⬜ -w: Wrap repeated cycles.
• ☑️ -x (cores): Set the number of cores for multi-threading.
• --PAR=value: Use pygmt.config instead.

Notes on Input Formats

• data: Accepts a file path or 2-D numpy.ndarray with columns L, M, C[L,M], S[L,M] (degree, order, cosine, and sine coefficients).
• outgrid: If not set, returns an xarray.DataArray; if set to a file path, writes the grid to disk and returns None.
• Both spacing and region are required parameters.
• The spherical harmonic coefficients are typically global (use region="g" for a 360°×180° grid).

Linked Pull Requests

• Initial feature implementation – Wrap sph2grd #1434
• Add inline docstring example – Add inline example for sph2grd #1718
• Implement -D (normalization for geographic vs. Cartesian) option
• Implement -N (coefficient normalization scheme) option
• Implement -Q (Legendre polynomial input) option
• Add common data I/O options (-d, -e, -f, -g, -s, -w)
• Add a gallery or tutorial example (e.g., reconstructing the EGM96 geoid from spherical harmonic coefficients and comparing to a reference model)

Related Issues and Discussions

• pygmt.sph2grd is the companion to pygmt.grd2sph (not yet implemented); together they form a round-trip spherical harmonic analysis/synthesis workflow.
• The output grid is typically global and can be visualized directly with Figure.grdimage or Figure.grdcontour.
• For non-global spherical harmonic models, restrict the output region with region to avoid computing unnecessary nodes.