gravityzonal

R2026b

Implement zonal harmonic representation of planetary gravity

Syntax

[gravityXcoord gravityYcoord,gravityZcoord] = gravityzonal(planetCoord)

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,action)

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,degreeGravityModel)

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,planetModel)

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,planetModel,degreeGravityModel)

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,planetModel,degreeGravityModel,action)

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,'Custom',Re,planetaryGravitional,zonalHarmonicCoeff)

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,'Custom',Re,planetaryGravitional,zonalHarmonicCoeff,action)

Description

Default Degree of Harmonic and Planetary Model

[gravityXcoord gravityYcoord,gravityZcoord] = gravityzonal(planetCoord) implements the mathematical representation of zonal harmonic planetary gravity based on planetary gravitational potential. The function takes an m-by-3 matrix that contains planet-centered planet-fixed coordinates from the center of the planet in meters. This function calculates the arrays of m gravity values in the x-, y-, and z-axes of the planet-centered planet-fixed coordinates.

This function does not include the potential due planet rotation, which excludes the centrifugal effects of planetary rotation and the effects of a precessing reference frame.

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,action) specifies the action for out-of-range input.

Degree of Harmonic Model and Planetary Model

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,degreeGravityModel) uses the degree of harmonic model.

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,planetModel) uses the planetary model.

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,planetModel,degreeGravityModel) uses the degree of harmonic model and planetary model.

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,planetModel,degreeGravityModel,action) specifies the action for out-of-range input.

Custom Planetary Model

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,'Custom',Re,planetaryGravitional,zonalHarmonicCoeff) uses the equatorial radius, planetary gravitational parameter, and zonal harmonic coefficients for the custom planetary model.

[gravityXcoord,gravityYcoord,gravityZcoord] = gravityzonal(planetCoord,'Custom',Re,planetaryGravitional,zonalHarmonicCoeff,action) specifies the action for out-of-range input.

Examples

Calculate Gravity in x-Axis at Equator on Surface of Earth Using Fourth Degree Model

Calculate the gravity in the x-axis at the equator on the surface of Earth using the fourth degree model with no warning actions.

gx = gravityzonal( [-6378.1363e3 0 0] )

gx = 
9.8142

Calculate Gravity at 15,000 Meters over Equator and 11,000 Meters over Geographic North Pole and Mars Model

Calculate the gravity at 15,000 m over the equator and 11,000 m over the geographic North Pole using a second order Mars model with warning actions.

p  = [2412.648e3 -2412.648e3 0; 0 0 3376.2e3]

p = 2×3

     2412648    -2412648           0
           0           0     3376200

[gx, gy, gz] = gravityzonal( p, 'Mars', 2, 'Warning' )

gx = 2×1

   -2.6089
         0

gy = 2×1

    2.6089
         0

gz = 2×1

         0
   -3.7349

Calculate Gravity at 15,000 Meters over Equator and 11,000 Meters over Geographic North Pole with Custom Planetary Model

Calculate the gravity at 15,000 m over the equator and 11,000 m over the geographic North Pole using a custom planetary model with no actions.

p= [2412.648e3 -2412.648e3 0; 0 0 3376e3]

p = 2×3

     2412648    -2412648           0
           0           0     3376000

GM      = 42828.371901e9  % m^3/s^2

GM = 
4.2828e+13

Re      = 3397e3          % m

Re = 
3397000

Jvalues = [1.95545367944545e-3 3.14498094262035e-5 ...
-1.53773961526397e-5]

Jvalues = 1×3

    0.0020    0.0000   -0.0000

[gx, gy, gz] = gravityzonal( p, 'custom', Re, GM, ...
Jvalues, 'None' )

gx = 2×1

   -2.6090
         0

gy = 2×1

    2.6090
         0

gz = 2×1

    0.0002
   -3.7352

Calculate Gravity Using Close Approximation Method at 100 Meters over Geographic South Pole of Earth

Calculate the gravity using the close approximation method at 100 m over the geographic South Pole of Earth with error actions.

[gx, gy, gz] = gravityzonal( [0 0 -6356.851e3], 'Error' )

gx = 
0

gy = 
0

gz = 
9.8317

Input Arguments

planetCoord — Planet-centered planet-fixed coordinates

m-by-3 matrix

Planet-centered planet-fixed coordinates from center of planet, specified as an m-by-3 matrix in meters. If planetModel has a value of 'Earth', this matrix contains Earth-centered Earth-fixed (ECEF) coordinates.

Data Types: double

planetModel — Planetary model

'Earth' (default) | 'Mercury' | 'Venus' | 'Moon' | 'Mars' | 'Jupiter' | 'Saturn' | 'Uranus' | 'Neptune' | 'Custom'

Planetary model, specified as:

• 'Mercury'

• 'Venus'

• 'Earth'

• 'Moon'

• 'Mars'

• 'Jupiter'

• 'Saturn'

• 'Uranus'

• 'Neptune'

• 'Custom'

'Custom' requires you to specify your own planetary model using the equatorialRadius, planetaryGravitional, and zonalHarmonicCoeff parameters.

Data Types: double

degreeGravityModel — Degree of harmonic model

scalar

Degree of harmonic model, specified as a scalar of one of these values.

Degree	Description	Default WhenplanetModel Is
4	Fourth degree, J4	'Earth 'Jupiter' 'Saturn' 'Custom'
2	Second degree, J2	'Mercury' 'Venus' 'Moon' 'Uranus' 'Neptune'
3	Third degree, J3	'Mars'

Data Types: double

Re — Equatorial radius

scalar

Equatorial radius, specified as a scalar in meters.

Data Types: double

planetaryGravitional — Planetary gravitational parameter

scalar

Planetary gravitational parameter, specified as a scalar in meters cubed per second squared.

Data Types: double

zonalHarmonicCoeff — Zonal harmonic coefficients

3-element array

Zonal harmonic coefficients to calculate zonal harmonics planetary gravity, specified as a 3-element array.

Data Types: double

action — Action

'None' (default) | 'Error' | 'Warning'

Action for out-of-range input, specified as:

• 'Error' — Displays warning and indicates that the input is out of range.

• 'Warning' — Displays error and indicates that the input is out of range.

• 'None' — Does not display warning or error.

Data Types: char | string

Output Arguments

gravityXcoord — Gravity values in the x-axis

array

Gravity values in the x-axis, returned as an array of m gravity values of the planet-centered planet-fixed coordinates in meters per second squared.

gravityYcoord — Gravity values in the y-axis

array

Gravity values in the y-axis, returned as an array of m gravity values of the planet-centered planet-fixed coordinates in meters per second squared.

gravityZcoord — Gravity values in the z-axis

array

Gravity values in the z-axis, returned as an array of m gravity values of the planet-centered planet-fixed coordinates in meters per second squared.

Algorithms

gravityzonal is implemented using the following planetary parameter values for each planet.

Planet	Equatorial Radius (Re) in Meters	Gravitational Parameter (GM) in m3/s2	Zonal Harmonic Coefficients (J Values)
Earth	6378.137e3	3.986004418e14	[ 1.08262617385222e-3 -2.53241051856772e-6 -1.61989759991697e-6 ]
Jupiter	7.1492e7	1.267127678577960e17	[14736e-6 0 -0.00058]
Mars	3.3962e6	4.2828314258067e13	[ 1960.45e-6 0.000036 ]
Mercury	2.4397e6	2.20320804864179e13	50.3e-6
Moon	1.7381e6	4.902801076e12	202.7e-6
Neptune	2.4764e7	6.836534063879261e15	3411e-6
Saturn	6.0268e7	3.794062606113729e16	[16298e-6 0 -0.001]
Uranus	2.5559e7	5.794549007071873e15	3343.43e-6
Venus	6.0518e6	3.248585988264598e14	4.458e-6

References

[1] NASA. "Planetary Fact Sheet." NASA National Space Science Data Center. Accessed June 30, 2026. https://nssdc.gsfc.nasa.gov/planetary/factsheet/.

[2] National Geospatial-Intelligence Agency. World Geodetic System 1984: Its Definition and Relationships with Local Geodetic Systems. Version 1.0.0. Department of Defense, July 8, 2014.

[3] Pavlis, N. K., S. A. Holmes, S. C. Kenyon, and J. K. Factor. "The Development and Evaluation of the Earth Gravitational Model 2008 (EGM2008)." Journal of Geophysical Research 117, B04406 (2012). doi:10.1029/2011JB008916.

Version History

Introduced in R2009b

R2026b: Standardized planetary constant values

Planetary constants for all supported planets are now standardized to WGS84, EGM2008, and NASA NSSDC reference values. You might see small numerical differences in results compared to previous releases.