Zonal Harmonic Gravity Model

R2026b

Calculate zonal harmonic representation of planetary gravity

• 

Zonal Harmonic Gravity Model block

To add a block to a model, double-click the canvas and start typing the block name. Then, select the block from the list.

Libraries:
Aerospace Blockset / Environment / Gravity

Description

The Zonal Harmonic Gravity Model block calculates the zonal harmonic representation of planetary gravity at a specific location based on planetary gravitational potential. This block provides a convenient way to describe the gravitational field of a planet outside its surface.

By default, the block uses the fourth order zonal coefficient for Earth to calculate the zonal harmonic gravity. It also allows you to specify the second or third zonal coefficient.

For information on the planetary parameter values for each planet in the block implementation, see Algorithms.

Examples

Developing the Apollo Lunar Module Digital Autopilot

Develop Apollo Lunar Module digital autopilot using Simulink^® and Aerospace Blockset™.

• Open Live Script

Limitations

The block excludes the centrifugal effects of planetary rotation and the effects of a precessing reference frame.

Ports

Input

X_ecef — Planet-centered planet-fixed coordinates

m-by-3 matrix

Planet-centered planet-fixed coordinates, specified as an m-by-3 matrix, from the center of the planet in the selected length units. If Planet model has a value of Earth, this matrix contains Earth-centered Earth-fixed (ECEF) coordinates.

Data Types: double

Output

g_ecef — Gravity values

m-by-3 array

Gravity values, returned as an m-by-3 array, in the x-axis, y-axis and z-axis of the planet-centered planet-fixed coordinates, in the selected length units per second squared.

Data Types: double

Parameters

Units — Input units

Metric (MKS) (default) | English

Input units, specified as:

Units	Position	Equatorial Radius	Gravitational Parameter
Metric (MKS)	Meters	Meters	Meters cubed per second squared
English	Feet	Feet	Feet cubed per second squared

Programmatic Use

Block Parameter: units

Type: character vector

Values: 'Metric (MKS)' | 'English'

Default: 'Metric (MKS)'

Degree — Degree of harmonic model

4 (default) | 2 | 3

Degree of harmonic model, specified as.

• 2 — Second degree, J2. Most significant or largest spherical harmonic term, which accounts for the oblateness of a planet.

• 3 — Third degree, J3.

• 4 — Fourth degree, J4 (default).

Programmatic Use

Block Parameter: degree

Type: character vector

Values: '2' | '3' | '4'

Default: '4'

Action for out-of-range input — Out-of-range input behavior

Warning (default) | ErrorNone

Out-of-range input behavior, specified as:

Value	Description
None	No action.
Warning	Warning in the Diagnostic Viewer, model simulation continues.
Error	MATLAB® returns an exception, model simulation stops.

Programmatic Use

Block Parameter: action

Type: character vector

Values: 'None' | 'Warning' | 'Error'

Default: 'Warning'

Planet model — Planetary model

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

Planetary model, specified as Mercury, Venus, Earth, Moon, Mars, Jupiter, Saturn, Uranus, Neptune, or Custom.

Selecting Custom enables you to specify your own planetary model.

• Selecting Mercury, Venus, Moon, Uranus, or Neptune limits the degree to 2.

• Selecting Mars limits the degree to 3.

Dependencies

Selecting Custom enables the Equatorial radius, Gravitational parameter and J values rate parameters.

Programmatic Use

Block Parameter: ptype

Type: character vector

Values: 'Mercury' | 'Venus' | 'Earth' | 'Moon' | 'Mars' | 'Jupiter' | 'Saturn' | 'Uranus' | 'Neptune' | 'Custom'

Default: 'Earth'

Equatorial radius — Planetary equatorial radius

6378137 (default) | scalar

Planetary equatorial radius, specified as a scalar, in the length units that the Units parameter defines.

Dependencies

To enable this parameter, set Planet model to Custom.

Programmatic Use

Block Parameter: R

Type: character vector

Values: scalar

Default: '6378137'

Gravitational parameter — Planetary gravitational parameter

398600441800000 (default) | scalar

Planetary gravitational parameter, specified as a scalar, in the length units cubed per second squared that the Units parameter defines.

Dependencies

To enable this parameter, set Planet model to Custom.

Programmatic Use

Block Parameter: GM

Type: character vector

Values: scalar

Default: '398600441800000'

J values — Zonal harmonic coefficients

[1.08262617385222e-03 -2.53241051856772e-06 -1.61989759991697e-06] (default) | 3-element array

Zonal harmonic coefficient, specified as a 3-element array.

Dependencies

To enable this parameter, set Planet model to Custom.

Programmatic Use

Block Parameter: jvalue

Type: character vector

Values: scalar

Default: '[1.08262617385222e-03 -2.53241051856772e-06 -1.61989759991697e-06]'

Algorithms

This block is implemented using the following planetary parameter values for each planet:

Planet	Equatorial Radius (Re) in Meters	Gravitational Parameter (GM) in m 3 /s 2	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.

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using Simulink® Coder™.

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. Default values for equatorial radius and gravitational parameter have been updated. You might see small numerical differences in results compared to previous releases.