propagateOrbit

Calculate position and velocity in International Celestial Reference Frame (ICRF)

Since R2023b

Syntax

``[positions,velocities] = propagateOrbit(time,tleStruct)``
``[positions,velocities] = propagateOrbit(time,a,ecc,incl,RAAN,argp,nu)``
``[positions,velocities] = propagateOrbit(time,rEpoch,vEpoch)``
``[positions,velocities] = propagateOrbit(___,time,Name=Value)``

Description

example

````[positions,velocities] = propagateOrbit(time,tleStruct)` calculates the positions and velocities in the International Celestial Reference Frame (ICRF) corresponding to the time specified by `time` using the two-line-element (TLE) data defined by `tleStruct`.`[positions,velocities] = propagateOrbit(time,a,ecc,incl,RAAN,argp,nu)` calculates the positions and velocities using specified orbital elements to define epoch states. The function assumes that the epoch is the current Universal Time Coordinated (UTC) date and time and is the first element in the `time` argument.`[positions,velocities] = propagateOrbit(time,rEpoch,vEpoch)` calculates the positions and velocities at the epoch defined by `rEpoch` and `vEpoch`. The function assumes that the epoch is the current UTC date and time and is the first element in the `time` argument..`[positions,velocities] = propagateOrbit(___,time,Name=Value)` calculates the positions and velocities using one or more name-value arguments.```

Examples

collapse all

Read data from the TLE file `'leoSatelliteConstellation.tle'` and calculate the position and velocity from the TLE structure, `tleStruct`.

Read the data from the TLE file `'leoSatelliteConstellation.tle'`, which is on the MATLAB® path and provided with Aerospace Toolbox.

`tleStruct = tleread('leoSatelliteConstellation.tle')`
```tleStruct=40×1 struct array with fields: Name SatelliteCatalogNumber Epoch BStar RightAscensionOfAscendingNode Eccentricity Inclination ArgumentOfPeriapsis MeanAnomaly MeanMotion ```

Calculate the position and velocity corresponding to the input time using the TLE data defined in `tleStruct`.

`[r,v] = propagateOrbit(datetime(2022, 1, 3, 12, 0, 0),tleStruct)`
```r = r(:,:,1) = 1.0e+06 * -4.3726 1.2106 -5.6292 r(:,:,2) = 1.0e+06 * 2.8278 3.3101 5.7417 r(:,:,3) = 1.0e+06 * -1.6252 6.4804 2.7661 r(:,:,4) = 1.0e+06 * -6.4733 3.1872 -0.4959 r(:,:,5) = 1.0e+06 * -6.5300 -1.8740 -2.5197 r(:,:,6) = 1.0e+06 * 4.2696 -2.9549 5.0050 r(:,:,7) = 1.0e+06 * -4.3207 -0.2621 -5.8029 r(:,:,8) = 1.0e+06 * -0.4354 6.3188 3.5007 r(:,:,9) = 1.0e+06 * 3.1625 -4.6176 -4.5565 r(:,:,10) = 1.0e+06 * -6.4680 -0.5957 -3.1486 r(:,:,11) = 1.0e+06 * -5.0509 -4.3876 -2.7586 r(:,:,12) = 1.0e+06 * -4.5717 4.3305 3.5445 r(:,:,13) = 1.0e+06 * -4.8265 0.2134 5.3573 r(:,:,14) = 1.0e+06 * 3.3022 -3.9510 -5.0798 r(:,:,15) = 1.0e+06 * -6.4064 -2.3789 -2.3156 r(:,:,16) = 1.0e+06 * 4.9215 -1.5755 -5.0658 r(:,:,17) = 1.0e+06 * -4.2865 0.5024 5.7884 r(:,:,18) = 1.0e+06 * -4.1508 -5.3584 -2.5396 r(:,:,19) = 1.0e+06 * 0.8586 -4.2505 -5.8000 r(:,:,20) = 1.0e+06 * 1.6331 -3.9315 -5.8582 r(:,:,21) = 1.0e+06 * -3.4834 -2.7205 5.7141 r(:,:,22) = 1.0e+06 * -0.3378 -5.8660 4.1801 r(:,:,23) = 1.0e+06 * -2.3699 -5.9500 -3.3499 r(:,:,24) = 1.0e+06 * -3.5223 -3.3199 5.3567 r(:,:,25) = 1.0e+06 * 5.8316 -2.5668 -3.4419 r(:,:,26) = 1.0e+06 * 0.5307 -4.0214 5.9809 r(:,:,27) = 1.0e+06 * -2.5070 -3.5297 5.7770 r(:,:,28) = 1.0e+06 * 5.2806 -1.5994 -4.6575 r(:,:,29) = 1.0e+06 * -6.7516 -2.5075 0.5515 r(:,:,30) = 1.0e+06 * -4.7709 2.9142 -4.5849 r(:,:,31) = 1.0e+06 * -3.5965 2.7142 -5.6577 r(:,:,32) = 1.0e+06 * -3.5367 -2.2889 5.8683 r(:,:,33) = 1.0e+06 * -7.2201 0.2849 0.1373 r(:,:,34) = 1.0e+06 * -4.9627 -1.2222 -5.1376 r(:,:,35) = 1.0e+06 * 0.6899 -4.5016 5.5907 r(:,:,36) = 1.0e+06 * 4.0468 2.2131 -5.5739 r(:,:,37) = 1.0e+06 * -5.3549 -4.8576 -0.1584 r(:,:,38) = 1.0e+06 * 6.0404 -1.8887 3.4976 r(:,:,39) = 1.0e+06 * 5.4127 1.6086 4.5006 r(:,:,40) = 1.0e+06 * -6.4090 1.6928 -2.9143 ```
```v = v(:,:,1) = 1.0e+03 * 0.4943 -7.1498 -1.9149 v(:,:,2) = 1.0e+03 * -4.0192 6.0766 -1.5144 v(:,:,3) = 1.0e+03 * -4.9766 1.0605 -5.4091 v(:,:,4) = 1.0e+03 * -1.4616 -3.9252 -6.1322 v(:,:,5) = 1.0e+03 * 3.2088 -3.7044 -5.5631 v(:,:,6) = 1.0e+03 * 0.9341 6.6797 3.1401 v(:,:,7) = 1.0e+03 * 1.8369 -7.1027 -1.0508 v(:,:,8) = 1.0e+03 * -5.0858 2.3556 -4.8638 v(:,:,9) = 1.0e+03 * 6.3179 0.5077 3.8802 v(:,:,10) = 1.0e+03 * 2.9293 -4.4690 -5.1661 v(:,:,11) = 1.0e+03 * 4.6556 -1.9379 -5.4413 v(:,:,12) = 1.0e+03 * -5.3740 -1.6816 -4.8478 v(:,:,13) = 1.0e+03 * -3.2646 -6.1068 -2.7019 v(:,:,14) = 1.0e+03 * 6.5709 1.5692 3.0633 v(:,:,15) = 1.0e+03 * 3.3442 -3.5794 -5.5948 v(:,:,16) = 1.0e+03 * 4.7665 4.7091 3.1755 v(:,:,17) = 1.0e+03 * -2.5062 -6.8824 -1.2637 v(:,:,18) = 1.0e+03 * 4.8713 -1.1945 -5.4657 v(:,:,19) = 1.0e+03 * 6.7905 2.7845 -1.0447 v(:,:,20) = 1.0e+03 * 6.4822 3.5498 -0.5660 v(:,:,21) = 1.0e+03 * 2.5726 -6.7711 -1.6434 v(:,:,22) = 1.0e+03 * 4.9552 -3.4072 -4.3792 v(:,:,23) = 1.0e+03 * 5.5151 0.5805 -4.9428 v(:,:,24) = 1.0e+03 * 2.2327 -6.5935 -2.6017 v(:,:,25) = 1.0e+03 * -0.5055 5.4920 -4.9559 v(:,:,26) = 1.0e+03 * 7.3355 1.1602 0.1376 v(:,:,27) = 1.0e+03 * 6.8592 -2.4664 1.4629 v(:,:,28) = 1.0e+03 * -1.4396 6.2341 -3.7779 v(:,:,29) = 1.0e+03 * 1.8985 -3.7666 6.1154 v(:,:,30) = 1.0e+03 * -5.5694 -3.0137 3.8774 v(:,:,31) = 1.0e+03 * -6.0027 -3.8907 1.9583 v(:,:,32) = 1.0e+03 * 4.3350 -6.0269 0.2515 v(:,:,33) = 1.0e+03 * -0.0514 -4.3235 6.0454 v(:,:,34) = 1.0e+03 * -1.5791 -6.5457 3.0929 v(:,:,35) = 1.0e+03 * 7.1302 -1.1357 -1.7937 v(:,:,36) = 1.0e+03 * -5.2628 4.8689 -1.8870 v(:,:,37) = 1.0e+03 * 2.8075 -3.2824 6.0458 v(:,:,38) = 1.0e+03 * 4.0290 3.9657 -4.8152 v(:,:,39) = 1.0e+03 * 1.4390 6.1548 -3.9152 v(:,:,40) = 1.0e+03 * -3.4278 -4.0127 5.2093 ```

Input Arguments

collapse all

Julian dates or `datetime`, specified as a 1-by-m vector or m-by-1 vector of `datetime` objects or doubles. `time` must be strictly increasing.

When you specify a `datetime` object whose `TimeZone` property is empty, `propagateOrbit` assumes that the `datetime` object time zone is UTC.

Example: `datetime(2023,6,16)`

Example: `juliandate(2023,6,16)`

Data Types: `double`

Semimajor axes, specified as a numSc-element vector or scalar, in meters. If all spacecraft have the same semimajor axis, you can specify `a` as a scalar. numSc is the number of spacecraft.

Example: `10000000`

Example: `[8000000 10000000]`

Data Types: `double`

Orbit eccentricity (deviation of orbital curve from circular), specified as an numSc-element vector or scalar. If all spacecraft have the same eccentricity, you can specify `ecc` as a scalar. numSc is the number of spacecraft.

Example: `0.1`

Example: `[0.1 0.2]`

Inclination, vertical tilt of the ellipse with respect to the ICRF xy plane measured at the ascending node, specified as a numSc-element vector or scalar. numSc is the number of spacecraft.

Example: `10`

Example: `[20 30]`

Right ascension of ascending node (RAAN), specified as a numSc-element vector or scalar in degrees. If all spacecraft have the same right ascension of ascending node, you can specify `RAAN` as a scalar. numSc is the number of spacecraft.

Example: `10`

Example: `[20 30]`, if there are two spacecraft

Argument of periapsis, the angle from orbit ascending node to periapsis (closest point of orbit to the central body), specified as a numSc-element vector or a scalar. If all spacecraft have the same argument of periapsis, you can specify `RAAN` as a scalar.numSc is the number of spacecraft.

Example: `10`

Example: `[20 30]`, if there are two spacecraft

True anomaly, the angle between periapsis and initial position of spacecraft, specified as a numSc-element vector or scalar. If all spacecraft have the same argument of periapsis, you can specify `nu` as a scalar. numSc is the number of spacecraft.

Example: `10`

Example: `[20 30]`, if there are two spacecraft

Position at epoch, specified as a 3-by-1 vector or 3-by-numSc matrix. If all spacecraft have the same initial position at epoch, you can specify `rEpoch` as a 3-element vector. numSc is the number of spacecraft.

Example: `[10000000;1000;2000]`

Example: `[10000000 12000000;1000 2000;2000 4000]`, if there are two spacecraft

Dependencies

`rEpoch` and the corresponding `vEpoch` vectors cannot be parallel.

Velocity at epoch, specified as a 3-by-1 vector or 3-by-numSc matrix. If all spacecraft have the same initial velocity at epoch, you can specify `vEpoch` as a 3-element vector. numSc is the number of spacecraft.

Example: `[0;8000;0]`

Example: `[0 100;8000 9000;200 300]`, if there are two spacecraft

Dependencies

`vEpoch` and the corresponding `rEpoch` vectors cannot be parallel.

TLE structures representing TLE data, specified as an numSc-element vector. numSc is the number of spacecraft. To create the TLE structure file, consider using `tleread`. For more information on TLE-file structures, see Two Line Element (TLE) Files.

Example: `tleread("leoSatelliteConstellation.tle")`

Data Types: `string`

Name-Value Arguments

Specify optional pairs of arguments as `Name1=Value1,...,NameN=ValueN`, where `Name` is the argument name and `Value` is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Before R2021a, use commas to separate each name and value, and enclose `Name` in quotes.

Example: `PropModel="two-body-keplerian"` specifies `two-body-keplerian` as the propagation method.

Epoch, specified as a scalar `datetime`, specified as a double.

When you specify a `datetime` object whose `TimeZone` property is empty, the `propagateOrbit` function assumes that the `datetime` object time zone is UTC.

Example: `datetime(2023,6,19)`

Dependencies

When the epoch states are specified using `tleStruct`, do not specify this name-value argument.

Data Types: `double`

Orbital state propagation method, specified as one of these values:

• `"general-perturbations"``"sgp4"` or `"sdp4"`, depending on orbital period. When the orbital period corresponding to the epoch states is less than 225 minutes, the propagation model is `"sgp4"`. Otherwise, it is `"sdp4"`.

• `"two-body-keplerian"` — Two-body Keplerian orbit propagator.

• `"sgp4"` — Simplified General Perturbations-4 orbit propagator.

• `"sdp4"` — Simplified Deep-Space Perturbations-4 orbit propagator.

Example: `PropModel="two-body-keplerian"`

Data Types: `char` | `string`

Aerodynamic drag term, specified as a numSc-element vector or scalar. If all spacecraft use the same `Bstar` value, you can specify this argument as a scalar. numSc is the number of spacecraft.

Example: `BStar=0`

Example: `BStar=[0.0001 0.0002]`, if there are two spacecraft

Dependencies

`propagateOrbit` uses this value when:

Data Types: `double`

Input coordinate frame of `rEpoch` and `vEpoch`, specified as one of these values:

• `"icrf"``rEpoch` and `vEpoch` are defined in the ICRF in meters and m/s respectively.

• `"fixed-frame"``rEpoch` and `vEpoch` are defined in the Earth-centered Earth-fixed (ECEF) frame in m and m/s respectively.

• `"geographic"``rEpoch` is defined as latitude (degrees), longitude (degrees), and altitude (meters). `vEpoch` is defined in the fixed-frame velocity represented in the North-East-Down (NED) frame defined by `rEpoch`.

Example: `InputCoordinateFrame="fixed-frame"`

Data Types: `char` | `string`

Output coordinate frame of output `positions` and `velocities`, specified as one of these values:

• `"icrf"``positions` and `velocities` are defined in the ICRF in m and m/s respectively

• `"fixed-frame"``positions` and `velocities` are defined in the Earth-centered Earth-fixed (ECEF) frame in m and m/s respectively .

• `"geographic"``positions` is defined as latitude (degrees), longitude (degrees), and altitude (meters). `velocities` is defined in the fixed-frame velocity represented in the North-East-Down (NED) frame defined by `rEpoch`.

Example: `OutputCoordinateFrame="geographic"`

Data Types: `char` | `string`

Output Arguments

collapse all

Positions, returned as a 3-by-m-by-numSc array. m is the number of time samples. numSc is the number of spacecraft.

Velocities, returned as a 3-by-m-by-numSc array. m is the number of time samples. numSc is the number of spacecraft.

Version History

Introduced in R2023b