# gravityzonal

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

example

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

example

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

example

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

collapse all

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

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

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```

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]; [gx, gy, gz] = gravityzonal(p,'Mars',2,'Warning')```
```gx = -2.6224 0 gy = 2.6224 0 gz = 0 -3.7542```

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]; GM = 42828.371901e9; % m^3/s^2 Re = 3397e3; % m Jvalues = [1.95545367944545e-3 3.14498094262035e-5 ... -1.53773961526397e-5]; [gx, gy, gz] = gravityzonal(p,'custom',Re,GM, ... Jvalues,'None')```
```gx = -2.6090 0 gy = 2.6090 0 gz = 0.0002 -3.7352```

## Input Arguments

collapse all

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`

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`

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

DegreeDescriptionDefault When`planetModel` 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`

Equatorial radius, specified as a scalar in meters.

Data Types: `double`

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

Data Types: `double`

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

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 the x-axis, returned as an array of m gravity values of the planet-centered planet-fixed coordinates in meters per second squared.

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.

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.

PlanetEquatorial Radius (Re) in MetersGravitational Parameter (GM) in m3/s2 Zonal Harmonic Coefficients
(J Values)
Earth6378.1363e33.986004415e14[ 0.0010826269 -0.0000025323 -0.0000016204 ]
Jupiter71492.e31.268e17[0.01475 0 -0.00058]
Mars3397.2e34.305e13 [ 0.001964 0.000036 ]
Mercury2439.0e3 2.2032e130.00006
Moon1738.0e3 4902.799e90.0002027
Neptune24764e3 6.809e150.004
Saturn60268.e3 3.794e16 [0.01645 0 -0.001]
Uranus25559.e35.794e15 0.012
Venus6052.0e3 3.257e140.000027

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

 Fortescue, Peter, Graham Swinerd, and John Stark, eds. Spacecraft Systems Engineering, 3rd ed. West Sussex: Wiley & Sons, 2003.

 Tewari, Ashish. Atmospheric and Space Flight Dynamics Modeling and Simulation with MATLAB and Simulink. Boston. Birkhäuser, 2007.