Geoid Computation API

This section provides detailed API documentation for GeoidLab’s core modules.

Core Modules

Geoid Module (geoidlab.geoid)

The geoid module provides core functionality for geoid modeling and computation:

ResidualGeoid Class

Main class for computing residual geoid heights using various kernel modifications:

class ResidualGeoid

Compute residual geoid heights using the Stokes’ integral.

__init__(res_anomaly, sph_cap=1.0, sub_grid=None, method='hg', ellipsoid='wgs84', nmax=None, window_mode='cap')
Parameters:

  • res_anomaly – Gridded residual gravity anomalies as xarray Dataset

  • sph_cap – Spherical cap radius for integration (degrees)

  • sub_grid – Subgrid extents (min_lon, max_lon, min_lat, max_lat)

  • method – Kernel modification method (‘hg’, ‘wg’, ‘og’, or ‘ml’)

  • ellipsoid – Reference ellipsoid (‘wgs84’ or ‘grs80’)

  • nmax – Maximum degree for modified kernels

  • window_mode – Integration window mode (‘cap’ or ‘fixed’)

Gravity Module (geoidlab.gravity)

Core functions for gravity field computations:

normal_gravity(phi, ellipsoid='wgs84')

Compute normal gravity using truncated series expansion.

Parameters:

  • phi – Geodetic latitude (degrees)

  • ellipsoid – Reference ellipsoid (‘wgs84’ or ‘grs80’)

Returns:

Normal gravity (m/s²)

normal_gravity_somigliana(phi, ellipsoid='wgs84')

Compute normal gravity using Somigliana’s formula.

Parameters:

  • phi – Geodetic latitude (degrees)

  • ellipsoid – Reference ellipsoid (‘wgs84’ or ‘grs80’)

Returns:

Normal gravity (m/s²)

gravity_anomalies(lat, gravity, elevation, ellipsoid='wgs84', atm=False, atm_method='noaa')

Compute free-air and Bouguer gravity anomalies.

Parameters:

  • lat – Latitude array (degrees)

  • gravity – Surface gravity array (mGal)

  • elevation – Station elevations (m)

  • ellipsoid – Reference ellipsoid

  • atm – Apply atmospheric correction

  • atm_method – Atmospheric correction method (‘noaa’)

Returns:

Tuple of (free_air_anomaly, bouguer_anomaly) in mGal

Global Geopotential Models (geoidlab.ggm)

Classes for handling spherical harmonic gravity field models:

class GlobalGeopotentialModel

Primary class for synthesizing gravity field functionals from spherical harmonic coefficients.

__init__(shc=None, model_name=None, ellipsoid='wgs84', nmax=90, grav_data=None, zonal_harmonics=True, model_dir='downloads', chunk_size=None, dtm_model=None, force_parallel=False)
gravity_anomaly(parallel=True)

Synthesize gravity anomalies.

Parameters:

parallel – Enable parallel processing

Returns:

Array of gravity anomalies (mGal)

geoid(T=None, icgem=False, parallel=False)

Compute geoid heights.

Parameters:

  • T – Precomputed disturbing potential (optional)

  • icgem – Apply topographic effect using DTM2006

  • parallel – Enable parallel processing. Large batched arrays fall back to sequential processing unless force_parallel=True was set on the model.

Returns:

Array of geoid heights (m)

Constants (geoidlab.constants)

Reference systems and physical constants:

grs80()

Return GRS80 ellipsoid parameters.

Returns:

Dictionary of GRS80 constants

wgs84()

Return WGS84 ellipsoid parameters.

Returns:

Dictionary of WGS84 constants

earth()

Return Earth/Geoid constants including W0.

Returns:

Dictionary of Earth constants

Data Handling

Digital Elevation Models (geoidlab.dem)

Functions and utilities for handling digital elevation model data:

geoidlab.dem

Digital Terrain Models (geoidlab.dtm)

Tools for computing terrain effects:

geoidlab.dtm

ICGEM Interface (geoidlab.icgem)

Functions for handling ICGEM (International Centre for Global Earth Models) data:

geoidlab.icgem

get_ggm_tide_system(icgem_file, model_dir)

Get the tide system of a global geopotential model.

Parameters:

  • icgem_file – Path to ICGEM file

  • model_dir – Directory containing the model

Returns:

Tide system string (‘mean_tide’, ‘zero_tide’, or ‘tide_free’)

Mathematical Tools

Legendre Functions (geoidlab.legendre)

Classes for computing fully-normalized associated Legendre functions:

class ALF

Base class for associated Legendre functions.

class ALFsGravityAnomaly

Specialized class for gravity anomaly computations.

Stokes’ Kernel (geoidlab.stokes_func)

Implementations of the Stokes’ kernel and its modifications:

class Stokes4ResidualGeoid

Class implementing Stokes’ kernel modifications for residual geoid determination. Includes Heck & Gruninger (hg), Wong & Gore (wg), original Stokes (og), and Meissl (ml) kernels.

Coordinate Systems and Transformations

Coordinate Transformations (geoidlab.coordinates)

Functions for coordinate system conversions:

geodetic2geocentric(lat, height, ellipsoid='wgs84')

Convert geodetic coordinates to geocentric.

Parameters:

  • lat – Geodetic latitude (degrees)

  • height – Ellipsoidal height (meters)

  • ellipsoid – Reference ellipsoid

Returns:

Geocentric coordinates

Terrain Tools (geoidlab.terrain)

Utilities for terrain corrections and topographic reductions.

Tide Systems (geoidlab.tide)

Classes for tide system conversions:

class GravityTideSystemConverter

Convert gravity data between different tide systems.

__init__(path_to_data=None, data=None, k=0.3, h=0.6, d=1.53)
Parameters:

  • path_to_data – Path to data file

  • data – Data as array, DataFrame or dict

  • k – Elastic Love number

  • h – Elastic Love number

  • d – Dynamic form factor

mean2free()
Convert from mean tide to tide-free system
free2mean()
Convert from tide-free to mean tide system
mean2zero()
Convert from mean tide to zero tide system
zero2mean()
Convert from zero tide to mean tide system

Utilities and Tools

General Utilities (geoidlab.utils)

Helper functions and I/O utilities:

DATASETS_CONFIG

Configuration for common dataset variables including units and descriptions.

Supported variables include: - Gravity anomalies (free-air, Bouguer, Helmert) - Geoid heights (residual, reference, total) - Height anomalies - Terrain corrections

Mapping Tools (geoidlab.mapping)

Tools for data visualization and mapping.