gravitysphericalharmonic - Implement spherical harmonic representation of planetary gravity

Syntax

[gx gy gz] = gravitysphericalharmonic(planet_coordinates) [gx gy gz] = gravitysphericalharmonic(planet_coordinates, model) [gx gy gz] = gravitysphericalharmonic(planet_coordinates, degree) [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

[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. It performs these calculations using planet_coordinates, an M-by-3 array of Planet-Centered Planet-Fixed coordinates. By default, this function assumes 120th degree and order spherical coefficients for the 'EGM2008' (Earth) planetary model.

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

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

[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.

[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.

This function has the following limitations:

The function excludes the centrifugal effects of planetary rotation, and the effects of a precessing reference frame.
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:
http://www.mathworks.com/support/tech-notes/1100/1107.html
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:
http://www.mathworks.com/support/tech-notes/1100/1110.html

Input Arguments

planet_coordinates

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.

model

String that specifies the planetary model. Default is 'EGM2008'. Specify one:

Planetary Model Planet

'EGM2008'
Earth Gravitational Model 2008

'EGM96'
Earth Gravitational Model 1996

'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.

'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:

http://www.mathworks.com/support/tech-notes/1100/1107.html

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:

http://www.mathworks.com/support/tech-notes/1100/1110.html

degree

Scalar value that specifies the degree and order of the harmonic gravity model.

Planetary Model Degree and Order

'EGM2008'
Maximum degree and order is 2159.
Default degree and order are 120.

'EGM96'
Maximum degree and order is 360.
Default degree and order are 70.

'LP100K'
Maximum degree and order is 100.
Default degree and order are 60.

'LP165P'
Maximum degree and order is 165.
Default degree and order are 60.

'GMM2B'
Maximum degree and order is 80.
Default degree and order are 60.

'Custom'
Maximum degree is default degree and order.

'EIGENGL04C'
Maximum degree and order is 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:

http://www.mathworks.com/support/tech-notes/1100/1107.html

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:

http://www.mathworks.com/support/tech-notes/1100/1110.html

action

String that defines action for out-of-range input. Specify one:

'Error'

'Warning' (default)

'None'

'Custom'

String that specifies that datafile contains definitions for a custom planetary model.

datafile

File that contains definitions for a custom planetary model. For an example of file content, see aerogmm2b.mat.

This file must contain the following variables.

Variable Description

Re
Scalar of planet equatorial radius in meters (m)

GM
Scalar of planetary gravitational parameter in meters cubed per second squared (m³/s²)

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

This parameter requires that you specify a program in the dfreader parameter to read the data file.

dfreader

Specify a MATLAB function to read datafile. The reader file that you specify depends on the file type of datafile.

Data File Type Description

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.

Output Arguments

`gx`	Array of `N` gravity values in the x-axis of the Planet-Centered Planet-Fixed coordinates in meters per second squared (m/s²).
`gy`	Array of `N` gravity values in the y-axis of the Planet-Centered Planet-Fixed coordinates in meters per second squared (m/s²).
`gz`	Array of `N` gravity values in the z-axis of the Planet-Centered Planet-Fixed coordinates in meters per second squared (m/s²).

Examples

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.1363e3 0 0] )

Calculate the gravity at 25000 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' )

Calculate the gravity at 15000 m over the equator and 11000 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 3376.2e3]
[gx, gy, gz] = gravitysphericalharmonic( p, 'GMM2B', 30, 'Warning' )

Calculate the gravity at 15000 m over the equator and 11000 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 3376e3]
[gx, gy, gz] = gravitysphericalharmonic( p, 'custom', 60, ...
{'GMM2BC80_SHA.txt' @astReadSHAFile}, 'None' )

Calculate the gravity at 25000 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' )

Search MATLAB Documentation
R2012a Documentation → Aerospace Toolbox
View documentation for other releases	Learn more about Aerospace Toolbox