Main Content

gravitysphericalharmonic

Implement spherical harmonic representation of planetary gravity

collapse all in page

Syntax

[gx gy gz] = gravitysphericalharmonic(planet_coordinates)
[gx gy gz] = gravitysphericalharmonic(planet_coordinates,degree)
[gx gy gz] = gravitysphericalharmonic(planet_coordinates,model)
[gx gy gz] = gravitysphericalharmonic(planet_coordinates,model,degree)
[gx gy gz] = gravitysphericalharmonic(planet_coordinates,model,degree,action)
[gx gy gz] = gravitysphericalharmonic(planet_coordinates,'Custom',degree,{datafile dfreader},action)

Description

Default Planetary Model

example

[gx gy gz] = gravitysphericalharmonic(planet_coordinates) implements the mathematical representation of spherical harmonic planetary gravity based on planetary gravitational potential. This function calculates arrays of N gravity values in the x-axis, y-axis, and z-axis of the Planet-Centered Planet-Fixed coordinates for the planet. The function performs these calculations using planet_coordinates, an M-by-3 array of Planet-Centered Planet-Fixed coordinates.

[gx gy gz] = gravitysphericalharmonic(planet_coordinates,degree) uses the degree and order that degree specifies.

Specified Planetary Model

example

[gx gy gz] = gravitysphericalharmonic(planet_coordinates,model) implements the mathematical representation for the planetary model, model.

[gx gy gz] = gravitysphericalharmonic(planet_coordinates,model,degree) uses the degree and order that degree specifies. model specifies the planetary model.

[gx gy gz] = gravitysphericalharmonic(planet_coordinates,model,degree,action) uses the specified action when input is out of range.

Custom Planetary Model

example

[gx gy gz] = gravitysphericalharmonic(planet_coordinates,'Custom',degree,{datafile dfreader},action) implements the mathematical representation for a custom model planet. datafile defines the planetary model. dfreader specifies the reader for datafile.

Examples

collapse all

Calculate the gravity in the x-axis at the equator on the surface of Earth. This example uses the default 120 degree model of EGM2008 with default warning actions.

gx = gravitysphericalharmonic([-6378.137e3 0 0])
gx =

    9.8143

Calculate the gravity at 25,000 m over the south pole of Earth. This example uses the 70 degree model of EGM96 with error actions.

[gx, gy, gz] = gravitysphericalharmonic([0 0 -6381.751e3],'EGM96','Error')
gx =
     0

gy =
     0

gz =
    9.7552

Calculate the gravity at 15,000 m over the equator and 11,000 m over the North Pole. This example uses a 30th order GMM2B Mars model with warning actions.

p  = [2412.648e3 -2412.648e3 0; 0 0 3397.2e3];
[gx, gy, gz] = gravitysphericalharmonic(p,'GMM2B',30,'Warning')
gx =
   -2.6085
         0

gy =
    2.6073
         0

gz =
    0.0000
   -3.6895

Calculate the gravity at 25,000 meters over the south pole of Earth using a 120th order EIGEN-GL04C Earth model with warning actions.

p = [0 0 -6381.751e3];
[gx, gy, gz] = gravitysphericalharmonic( p,'EIGENGL04C', ...
120,'Warning')
gx =
     0

gy =
     0

gz =
    9.7552

Calculate the gravity at 15,000 m over the equator and 11,000 m over the North Pole. This example uses a 60th degree custom planetary model with no actions.

p = [2412.648e3 -2412.648e3 0; 0 0 3397e3];
[gx, gy, gz] = gravitysphericalharmonic(p,'Custom',60, ...
{'GMM2BC80_SHA.txt' @astReadSHAFile},'None')
gx =
   -2.6079
         0

gy =
    2.6067
         0

gz =
    0.0002
   -3.6902

Input Arguments

collapse all

Planet coordinates, specified as an M-by-3 array of Planet-Centered Planet-Fixed coordinates in meters. The z-axis is positive toward the North Pole. If model is 'EGM2008' or 'EGM96' (Earth), the planet coordinates are ECEF coordinates.

Data Types: double

Planetary model, specified as one of these values.

Planetary ModelPlanet
'EGM2008'

Earth Gravitational Model 2008. Planet coordinates are ECEF (WGS84).

'EGM96'

Earth Gravitational Model 1996. Planet coordinates are ECEF (WGS84).

'LP100K'

100th degree Moon model.

'LP165P'

165th degree Moon model.

'GMM2B'

Goddard Mars model 2B.

'Custom'

Custom planetary model that you define in datafile.

Note

To deploy a custom planetary model, explicitly include the custom data and reader files to the MATLAB® Compiler™ (mcc) command at compilation. For example:

mcc -m mycustomsphericalgravityfunction...
-a customDataFile -a customReaderFile

For other planetary models, use the MATLAB Compiler as usual.

For more information, see 'Custom'.

'EIGENGL04C'

Combined Earth gravity field model EIGEN-GL04C.

When inputting a large PCPF array and a high-degree value, you might receive an out-of-memory error. For more information about avoiding out-of-memory errors in the MATLAB environment, see Resolve “Out of Memory” Errors.

When inputting a large PCPF array, you might receive a maximum matrix size limitation. To determine the largest matrix or array that you can create in the MATLAB environment for your platform, see Performance and Memory.

Data Types: char | string

Degree and order of harmonic gravity, specified as a scalar.

Planetary ModelDegree and Order

'EGM2008'

Maximum degree and order are 2159.

Default degree and order are 120.

'EGM96'

Maximum degree and order are 360.

Default degree and order are 70.

'LP100K'

Maximum degree and order are 100.

Default degree and order are 60.

'LP165P'

Maximum degree and order are 165.

Default degree and order are 60.

'GMM2B'

Maximum degree and order are 80.

Default degree and order are 60.

'Custom'

Maximum degree is default degree and order. For more information, see 'Custom'.

'EIGENGL04C'

Maximum degree and order are 360.

Default degree and order are 70.

When inputting a large PCPF array and a high-degree value, you might receive an out-of-memory error. For more information about avoiding out-of-memory errors in the MATLAB environment, see Performance and Memory.

When inputting a large PCPF array, you might receive a maximum matrix size limitation. To determine the largest matrix or array that you can create in the MATLAB environment for your platform, see Performance and Memory.

Data Types: char | string

Custom planetary model definitions, specified as 'Custom'. Specify the planetary model definitions with a definitions data file and accompanying reader. For more information, see datafile dfreader.

Data Types: char | string

Custom planetary model definitions file and reader, specified as a vector. datafile must contain these variables.

VariableDescription
Re

Scalar of planet equatorial radius in meters (m)

GM

Scalar of planetary gravitational parameter in meters cubed per second squared (m3/s2)

degree

Scalar of maximum degree

C

(degree+1)-by-(degree+1) matrix containing normalized spherical harmonic coefficients matrix, C

S

(degree+1)-by-(degree+1) matrix containing normalized spherical harmonic coefficients matrix, S

To read datafile, specify a MATLAB function in the dfreader parameter. The reader file that you specify depends on the file type of datafile.

Data File TypeDescription

MATLAB file

Specify the MATLAB load function, for example, @load.

Other file type

Specify a custom MATLAB reader function. For examples of custom reader functions, see astReadSHAFile.m and astReadEGMFile.m. Note the output variable order in these files.

Example: {'GMM2BC80_SHA.txt' @astReadSHAFile}

Data Types: double

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

collapse all

Gravity values in x-axis of Planet-Centered Planet-Fixed coordinates, returned as an array of M gravity values in meters per second squared (m/s2).

Gravity values in y-axis of Planet-Centered Planet-Fixed coordinates, returned as an array of M gravity values in meters per second squared (m/s2).

Gravity values in z-axis of Planet-Centered Planet-Fixed coordinates, returned as an array of M gravity values in meters per second squared (m/s2).

Limitations

  • The function excludes the centrifugal effects of planetary rotation, and the effects of a precessing reference frame.

  • The spherical harmonic gravity model is valid for radial positions greater than the planet equatorial radius. Minor errors might occur for radial positions near or at the planetary surface. The spherical harmonic gravity model is not valid for radial positions less than planetary surface.

Tips

  • When inputting a large PCPF array and a high-degree value, you might receive an out-of-memory error. For more information about avoiding out-of-memory errors in the MATLAB environment, see Performance and Memory.

  • When inputting a large PCPF array, you might receive a maximum matrix size limitation. To determine the largest matrix or array that you can create in the MATLAB environment for your platform, see Performance and Memory.

References

[1] ] Gottlieb, R. G. "Fast Gravity, Gravity Partials, Normalized Gravity, Gravity Gradient Torque and Magnetic Field: Derivation, Code and Data." Technical Report NASA Contractor Report 188243. Houston: NASA Lyndon B. Johnson Space Center, February 1993.

[2] Vallado, David A. Fundamentals of Astrodynamics and Applications. New York: McGraw-Hill, 1997.

[3] Defense Mapping Agency. Department of Defense World Geodetic System 1984, Its Definition and Relationship with Local Geodetic Systems. TR 8350.2, 2nd ed. Fairfax, VA: DMA, September 1, 1991.

[4] Konopliv, A. S., S. W. Asmar, E. Carranza, W. L. Sjogen, and D. N. Yuan. "Recent Gravity Models as a Result of the Lunar Prospector Mission, Icarus" 150, no. 1 (2001): 1–18.

[5] Lemoine, F. G., D. E. Smith, D. D. Rowlands, M. T. Zuber, G. A. Neumann, and D. S. Chinn. "An Improved Solution of the Gravity Field of Mars (GMM-2B) from Mars Global Surveyor." Journal of Geophysical Research 106, no. E10 (October 25, 2001): 23359–23376.

[6] Kenyon S., J. Factor, N. Pavlis, and S. Holmes. "Towards the Next Earth Gravitational Model." Paper presented at the Society of Exploration Geophysicists 77th Annual Meeting, San Antonio, Texas, September 23–28, 2007.

[7] Pavlis, N.K., S. A. Holmes, S. C. Kenyon, and J. K. Factor. "An Earth Gravitational Model to Degree 2160: EGM2008." Paper presented at the General Assembly of the European Geosciences Union, Vienna, Austria, April 13–18, 2008.

[8] Grueber, T., and A. Köhl. "Validation of the EGM2008 Gravity Field with GPS-Leveling and Oceanographic Analyses." Paper presented at the IAG International Symposium on Gravity, Geoid & Earth Observation, Chania, Greece, June 23–27, 2008.

[9] Förste, C., Flechtner et al, "A Mean Global Gravity Field Model From the Combination of Satellite Mission and Altimetry/Gravmetry Surface Data - EIGEN-GL04C." Geophysical Research Abstracts 8, 03462, 2006.

[10] Hill, K. A. "Autonomous Navigation in Libration Point Orbits." PhD diss. University of Colorado, Boulder, 2007.

[11] Colombo, Oscar L. Numerical Methods for Harmonic Analysis on the Sphere. Report no. 310. Columbus: Department of Geodetic Science at Ohio State University, 1981.

[12] Colombo, Oscar L. "The Global Mapping of Gravity with Two Satellites." Netherlands Geodetic Commission 7, no 3, Delft, The Netherlands, 1984., Reports of the Department of Geodetic Science. Report No. 310. Columbus: Ohio State University, March 1981.

[13] Jones, Brandon A. "Efficient Models for the Evaluation and Estimation of the Gravity Field." PhD diss. University of Colorado, Boulder, 2010.

[14] Report of the IAU/IAG Working Group on cartographic coordinates and rotational elements: 1991.

Version History

Introduced in R2010a

See Also

| |