Orbit Propagator

Propagate orbit of one or more spacecraft

• Library:

• Aerospace Blockset / Spacecraft / Spacecraft Dynamics

• 
• 

×

Description

The Orbit Propagator block propagates the orbit of one or more spacecraft by a propagation method. The library contains two versions of the Orbit Propagator block preconfigured for these propagation methods:

• Kepler (unperturbed) — Kepler universal variable formulation (quicker)

• Numerical (high precision) — More accurate

The size of the provided initial conditions determines the number of spacecraft being modeled. If you supply more than one value for a parameter in the Orbit tab, the block outputs a constellation of satellites. Any parameter with a single provided value is expanded and applied to all the satellites in the constellation. For example, if you provide a single value for all the parameters on the block except True anomaly, which contains six values, the block creates a constellation of six satellites, varying true anomaly only.

The block applies the same expansion behavior to input port A_icrf (applied acceleration). This port accepts either a single value expanded to all spacecraft being modeled, or individual values to apply to each spacecraft.

For more information on the propagation methods the Orbit Propagator block uses, see Orbit Propagation Methods.

You can define initial orbital states in the Orbit tab as:

• A set of orbital elements

• Position and velocity state vectors in International Celestial Reference Frame (ICRF) or fixed-frame coordinate systems.

The block uses quaternions, which are defined using the scalar-first convention.

For more information on the coordinate systems the Orbit Propagator block uses, see Coordinate Systems.

Ports

Input

Aicrf — Applied acceleration

3-element vector | m-3 array

Acceleration applied to the spacecraft with respect to the port coordinate system (ICRF or fixed-frame), specified as a 3-element vector or m-by-3 array, at the current time step.

Dependencies

To enable this port:

• Set Propagation method to Numerical (high precision).

• Select the Input external accelerations check box.

Data Types: double

φθψ — Moon libration angles

3-element vector

Moon libration angles for transformation between the ICRF and Moon-centric fixed-frame using the Moon-centric Principal Axis (PA) system, specified as a 3-element vector. To get these values, use the Moon Libration block.

Note

The fixed-frame used by this block when Central body is set to Moon is the Mean Earth/pole axis (ME) system. For more information, see Algorithms.

Dependencies

To enable this port:

• Set Propagation method to Numerical (high precision).

• Set Central body to Moon.

• Select the Input Moon libration angles check box.

Data Types: double

αδW — Right ascension, declination, and rotation angle

3-element vector

Central body spin axis instantaneous right ascension, declination, and rotation angle, specified as a 3-element vector. This port is available only for custom central bodies.

Dependencies

To enable this port:

• Set Propagation method to Numerical (high precision).

• Set Central body to Custom.

• Set Central body spin axis source to Port.

Data Types: double

Output

Xicrf — Position of spacecraft

3-element vector | numSat-by-3

Position of the spacecraft with respect to (ICRF or fixed-frame), returned as a 3-element vector or numSat-by-3 array, where m is number of spacecraft, at the current time step. The size of the initial conditions provided in the Orbit tab control the port dimension. numSat is the number of spacecraft.

Data Types: double

Vicrf — Velocity

3-element vector | numSat-by-3 array

Velocity of the spacecraft with respect to ICRF or fixed-frame, returned as a 3-element vector or numSat-by-3 array, at the current time step. numSat-by-3 array. The size of the initial conditions provided in the Orbit tab control the port dimension.

Data Types: double

qicrf2ff — Transformation

4-element quaternion (scalar first)

Transformation between the ICRF coordinate system and fixed-frame, returned as a 4-element vector (scalar first), at the current time step.

Dependencies

To enable this port:

• Set Propagation method to Numerical (high precision).

• Select the Output quaternion (ICRF to Fixed-frame) check box.

Data Types: double

tutc — Time at current time step

scalar | 6-element vector

Time at current time step, returned as a:

• scalar — If you specify the Start data/time parameter as a Julian date.

• 6-element vector — If you specify the Start data/time parameter as a Gregorian date with six elements (year, month, day, hours, minutes, seconds).

This value is equal to the Start date/time parameter value + the elapsed simulation time.

Dependencies

To enable this parameter, select the Output current date/time (UTC Julian date) check box.

Data Types: double

Parameters

Main

Propagation method — Orbit propagation method

Kepler (unperturbed) | Numerical (high precision)

Orbit propagation method, specified as:

• Kepler (unperturbed) — Uses a universal variable formulation of the Kepler problem to determine the spacecraft position and velocity at each time step. This method is faster than Numerical (high precision).

• Numerical (high precision) — Determine the spacecraft position and velocity at each time step using numerical integration. This option models central body gravity based on the settings in the Central body tab. This method is more accurate than Kepler (unperturbed), but slower.

Programmatic Use

Block Parameter: propagator

Type: character vector

Values: 'Kepler (unperturbed)' | 'Numerical (high precision)'

Default: 'Kepler (unperturbed)'

Input external accelerations — Input additional accelerations

off (default) | on

To enable additional external accelerations to be included in the integration of the spacecraft equations of motion, select this check box. Otherwise, clear this check box.

Dependencies

To enable this check box, set Propagation method to Numerical (high precision).

Programmatic Use

Block Parameter: accelIn

Type: character vector

Values: 'off' | 'on'

Default: 'off'

External acceleration coordinate frame — Frame for additional accelerations

ICRF (default) | Fixed-frame

Input additional accelerations, specified as ICRF or Fixed-frame. These accelerations are included in integration of the spacecraft equations of motion.

Dependencies

To enable this parameter:

• Set Propagation method to Numerical (high precision)

• Select the Input external accelerations check box

Programmatic Use

Block Parameter: accelFrame

Type: character vector

Values: 'ICRF' | 'Fixed-frame'

Default: 'ICRF'

State output coordinate frame — Port coordinate frame

ICRF (default) | Fixed-frame

Coordinate frame for output ports, specified as ICRF or Fixed-frame. These port labels are affected:

• Output port X

• Output port V

Dependencies

To enable this parameter, set Propagation method to Numerical (high precision).

Programmatic Use

Block Parameter: outportFrame

Type: character vector

Values: 'ICRF' | 'Fixed-frame'

Default: 'ICRF'

Start date/time (UTC Julian date) — Initial start time for simulation

juliandate (2020, 1, 1, 12, 0, 0) (default) | valid scalar Julian date | valid Gregorian date including year, month, day, hours, minutes, seconds as 6-element vector

Initial start date and time of simulation, specified as a Julian or Gregorian date. The block defines initial conditions using this value.

Tip

To calculate the Julian date, use the juliandate function.

Programmatic Use

Block Parameter: startDate

Type: character vector

Values: 'juliandate(2020, 1, 1, 12, 0, 0)' | valid scalar Julian date | valid Gregorian date including year, month, day, hours, minutes, seconds as 6-element vector

Default: 'juliandate(2020, 1, 1, 12, 0, 0)'

Output current date/time (UTC Julian date) — Add output port t_utc

on (default) | off

To output the current date or time, select this check box. Otherwise, clear this check box.

Programmatic Use

Block Parameter: dateOut

Type: character vector

Values: 'off' | 'on'

Default: 'off'

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

Warning (default) | Error | None

Out-of-range block behavior, specified as follows:

Action	Description
None	No action.
Warning	Warning displays in the MATLAB® Command Window. Model simulation continues.
Error (default)	MATLAB returns an exception. Model simulation stops.

Programmatic Use

Block Parameter: action

Type: character vector

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

Default: 'Warning'

Orbit

Define the initial states of the space craft.

Initial state format — Input method for initial states of orbit

Orbital elements (default) | ICRF state vector | Fixed-frame state vector

Input method for initial states of orbit, specified as Orbital elements, ICRF state vector, or Fixed-frame state vector.

Dependencies

Available options are based on Propagation method settings:

Kepler (unperturbed)	Numerical (high precision)
Orbital elements	Orbital elements
ICRF state vector	ICRF state vector
—	Fixed-frame state vector

Programmatic Use

Block Parameter stateFormatKep when propagator is set to Kepler (unperturbed), stateFormatNum when propagator is set to Numerical (high precision)

Type: character vector

Values: 'Orbital elements' | 'ICRF state vector' when propagator is set to 'Kepler (unperturbed)' | 'Orbital elements' | 'ICRF state vector' | 'Fixed-frame state' when propagator is set to 'Numerical (high precision)'

Default: 'Orbital elements'

Orbit Type — Orbit classification

Keplerian (default) | Elliptical equatorial | Circular | Circular equatorial

Orbit classification, specified as:

• Keplerian — Model elliptical orbits using six standard Keplerian orbital elements.

• Elliptical equatorial — Define an equatorial orbit, where inclination is 0 or 180 degrees and the right ascension of the ascending node is undefined.

• Circular — Define a circular orbit, where eccentricity is 0 and the argument of periapsis is undefined.

• Circular equatorial — Define a circular orbit, where eccentricity is 0 or 10 degrees. Argument of periapsis and the right ascension of the ascending node are undefined.

Dependencies

To enable this parameter, set Initial state format to Orbital elements.

Programmatic Use

Block Parameter: orbitType

Type: character vector

Values: 'Keplerian' | 'Elliptical equatorial' | 'Circular inclined' | 'Circular equatorial'

Default: 'Keplerian'

Semi-major axis — Half of major axis of ellipse

6786000 (default) | 1D array of size numSat

Half of ellipsis major axis, specified as a 1D array whose size is the number of spacecraft.

• For parabolic orbits, this block interprets this parameter as the periapsis radius (distance from periapsis to the focus point of orbit).

• For hyperbolic orbits, this block interprets this parameter as the distance from periapsis to the hyperbola center.

Dependencies

To enable this parameter, set Initial state format to Orbital elements.

Programmatic Use

Block Parameter: semiMajorAxis

Type: character vector

Values: scalar | 1D array of size m, number of spacecraft

Default: '6786000'

Eccentricity — Deviation of orbit

0.01 (default) | scalar | value between 0 and 1, or greater than 1 for Keplerian orbit type | 1D array of size numSat

Deviation of the orbit from a perfect circle, specified as a scalar or 1D array of size that is number of spacecraft.

If Orbit type is set to Keplerian, value can be:

• 0 for circular orbit

• Between 0 and 1 for elliptical orbit

• 1 for parabolic orbit

• Greater than 1 for hyperbolic orbit

Dependencies

To enable this parameter, set:

• Initial state format to Orbital elements.

• Orbit type to Keplerian or Elliptical equatorial.

Programmatic Use

Block Parameter: eccentricity

Type: character vector

Values: 0.01 | scalar | value between 0 and 1, or greater than 1 for Keplerian orbit type | 1D array of size numSat

Default: '0.01'

Inclination (deg) — Tilt angle of orbital plane

50 (default) | scalar | 1D array of size numSat | degrees between 0 and 180 | radians between 0 and pi

Vertical tilt of the ellipse with respect to the reference plane measured at the ascending node, specified as a scalar or 1D array of size numSat, in specified units. numSat is the number of spacecraft.

Dependencies

To enable this parameter, set:

• Initial state format to Orbital elements

• Orbit type to Keplerian or Circular inclined

Programmatic Use

Block Parameter: inclination

Type: character vector

Values: 50 | scalar | 1D array of size numSat | degrees between 0 and 180 | radians between 0 and pi

Default: '50'

RAAN (deg) — Angular distance in equatorial plane

95 (default) | scalar value between 0 and 360 | 1D array of size numSat

Right ascension of ascending node (RAAN), specified as a scalar value between 0 and 360 or 1D array of size numSat, in specified units. numSat is the number of spacecraft. RAAN is the angular distance along the reference plane from the ICRF x-axis to the location of the ascending node (the point at which the spacecraft crosses the reference plane from south to north).

Dependencies

To enable this parameter, set:

• Initial state format to Orbital elements.

• Orbit type to Keplerian or Circular inclined.

Programmatic Use

Block Parameter: raan

Type: character vector

Values: 95 | scalar value between 0 and 360 | 1D array of size m number of spacecraft

Default: '95'

Argument of periapsis (deg) — Angle from spacecraft ascending node to periapsis

93 (default) | degrees between 0 and 360 | radians between 0 and 2*pi | 1D array of size m, number of spacecraft

Angle from the spacecraft ascending node to periapsis (closest point of orbit to the central body), specified as a 1D array of size m that is number of spacecraft, in specified units.

Dependencies

To enable this parameter, set:

• Initial state format to Orbital elements

• Orbit type to Keplerian

Programmatic Use

Block Parameter: argPeriapsis

Type: character vector

Values: '95' | scalar value between 0 and 360 | 1D array of size numSat

Default: '93'

True anomaly — Angle between periapsis and initial position of spacecraft

203 (default) | scalar | degrees between 0 and 360 | radians between 0 and 2*pi | 1D array of size numSat

Angle between periapsis (closest point of orbit to the central body) and the initial position of spacecraft along its orbit at Start date/time, specified as a scalar or 1D array of size numSat, in specified units. numSat is the number of spacecraft.

Dependencies

To enable this parameter, set:

• Initial state format to Orbital elements.

• Orbit type to Keplerian or Elliptical inclined.

Programmatic Use

Block Parameter: trueAnomaly

Type: character vector

Values: '203' | scalar | degrees between 0 and 360 | radians between 0 and 2*pi | 1D array of size numSat

Default: '203'

Argument of latitude (deg) — Angle between ascending node and initial position of spacecraft

200 (default) | scalar | degrees between 0 and 360 | radians between 0 and 2*pi | 1D array of size numSat

Angle between the ascending node and the initial position of spacecraft along its orbit at Start date/time, specified as a scalar or 3-element vector or 1D array of size number of spacecraft, in specified units.

Dependencies

To enable this parameter, set:

• Initial state format to Orbital elements.

• Orbit Type to Circular inclined.

Programmatic Use

Block Parameter: argLat

Type: character vector

Values: '200' | scalar | degrees between 0 and 360 | radians between 0 and 2*pi | 1D array of size numSat

Default: '200'

Longitude of periapsis (deg) — Angle between ICRF x-axis and eccentricity vector

100 (default) | scalar | degrees between 0 and 360 | radians between 0 and 2*pi | 1D array of size numSat

Angle between the ICRF x-axis and the eccentricity vector, specified as a scalar or 3-element vector or 1D array of size number of spacecraft, in specified units.

Dependencies

To enable this parameter, set:

• Initial state format to Orbital elements.

• Orbit type to Elliptical equatorial.

Programmatic Use

Block Parameter: lonPeriapsis

Type: character vector

Values: 100 | scalar | degrees between 0 and 360 | radians between 0 and 2*pi | 1D array of size m, number of spacecraft

Default: '100'

True longitude (deg) — Angle between ICRF x-axis and initial position of spacecraft

150 (default) | scalar | degrees between 0 and 360 | radians between 0 and 2*pi | 1D array of size numSat

Angle between the ICRF x-axis and the initial position of spacecraft along its orbit at Start date/time, specified as a scalar or 1D array of size numSat, in specified units. numSat is the number of spacecraft.

Dependencies

To enable this parameter, set:

• Initial state format to Orbital elements.

• Orbit type to Circular equatorial.

Programmatic Use

Block Parameter: trueLon

Type: character vector

Values: '150' | scalar | degrees between 0 and 360 | radians between 0 and 2*pi | 1D array of size numSat

Default: '150'

ICRF position — Cartesian position vector of spacecraft

[3649700.0 3308200.0 -4676600.0] (default) | 3-element vector | | numSat-by-3 array

Cartesian position vector of spacecraft in ICRF coordinate system at Start date/time, specified as a 3-element vector for single spacecraft or numSat-by-3 array for multiple spacecraft. numSat is the number of spacecraft.

Dependencies

To enable this parameter, set Initial state format to ICRF state vector.

Programmatic Use

Block Parameter: inertialPosition

Type: character vector

Values: [3649700.0 3308200.0 -4676600.0] | 3-element vector for single spacecraft or 2D array of size m-by-3 array of multiple spacecraft

Default: '[3649700.0 3308200.0 -4676600.0]'

ICRF velocity — Cartesian velocity vector of spacecraft

[-2750.8 6666.4 2573.4] (default) | 3-element vector for single spacecraft or 2D array of size m-by-3 array of multiple spacecraft

Cartesian velocity vector of spacecraft in ICRF coordinate system at Start date/time, specified as a 3-element vector for single spacecraft or 2D array of size m-by-3 array of multiple spacecraft.

Dependencies

To enable this parameter, set Initial state format to ICRF state vector.

Programmatic Use

Block Parameter: inertialVelocity

Type: character vector

Values: [-2750.8 6666.4 2573.4] | 3-element vector for single spacecraft or 2D array of size m-by-3 array of multiple spacecraft

Default: '[-2750.8 6666.4 2573.4]'

Fixed-frame position — Position vector of spacecraft

[-4142689.0 -2676864.7 -4669861.6] (default) | 3-element vector for single spacecraft or 2D array of size m-by-3 array of multiple spacecraft

Cartesian position vector of spacecraft in fixed-frame coordinate system at Start date/time, specified as a 3-element vector for single spacecraft or 2D array of size m-by-3 array of multiple spacecraft.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• set Initial state format to Fixed-frame state vector.

Programmatic Use

Block Parameter: fixedPosition

Type: character vector

Values: '[-4142689.0 -2676864.7 -4669861.6]' | 3-element vector for single spacecraft or 2D array of size m-by-3 array of multiple spacecraft

Default: '[-2750.8 6666.4 2573.4]'

Fixed-frame velocity — Velocity vector of spacecraft

[1452.7 -6720.7 2568.1] (default) | 3-element vector for single spacecraft or 2D array of size m-by-3 array of multiple spacecraft

Cartesian velocity vector of spacecraft in fixed-frame coordinate system at Start date/time, specified as a 3-element vector for single spacecraft or 2D array of size m-by-3 array of multiple spacecraft.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Initial state format to Fixed-frame state vector.

Programmatic Use

Block Parameter: fixedVelocity

Type: character vector

Values: '[1452.7 -6720.7 2568.1]' | 3-element vector for single spacecraft or 2D array of size m-by-3 array of multiple spacecraft

Default: '[1452.7 -6720.7 2568.1]'

Central Body

Central body — Celestial body around which spacecraft orbits

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

Celestial body, specified as Earth, Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, or Custom, around which the spacecraft defined in the Orbit tab orbits.

Programmatic Use

Block Parameter: centralBody

Type: character vector

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

Default: 'Earth'

Gravitational potential model — Control gravity model for central body

Spherical harmonics when Central body set to Earth, Moon, Mars, or Custom, Oblate ellipsoid when Central body set to Mercury, Venus, Jupiter, Saturn, Uranus, or Neptune (default) | None | Point-mass | Oblate ellipsoid (J2)

Control the gravity model for the central body, specified as Spherical harmonics, Point-mass, or Oblate ellipsoid (J2).

Dependencies

To enable this parameter, set Propagation method to Numerical (high precision). Available options are based on Central body settings:

Earth, Moon, Mars, or Custom	Mercury, Venus, Jupiter, Saturn, Uranus, or Neptune
None	None
Spherical harmonics	Oblate ellipsoid (J2)
Point-mass	Point-mass
Oblate ellipsoid (J2)	—

Programmatic Use

Block Parameter: gravityModel when centralBody set to 'Earth', 'Moon', 'Mars', or 'Custom' | gravityModelnoSH when centralBody set to Mercury, Venus, Jupiter, Saturn, Uranus, or Neptune

Type: character vector

Values: 'Spherical harmonics' | 'None' | 'Point-mass' | 'Oblate ellipsoid (J2)' when centralBody set to 'Earth', 'Moon', 'Mars', or 'Custom'; 'Point-mass' | 'Oblate ellipsoid (J2)' when centralBody set to Mercury, Venus, Jupiter, Saturn, Uranus, or Neptune

Default: 'Spherical harmonics' when centralBody set to 'Earth', 'Moon', 'Mars', or 'Custom'; 'Oblate ellipsoid (J2)' when centralBody set to Mercury, Venus, Jupiter, Saturn, Uranus, or Neptune

Spherical harmonic model — Spherical harmonic model

EGM2008 for Central body set to Earth, LP-100K for Central body set to Moon, GMM2B for Central body set to Mars, (default) | EGM96 | EIGEN-GL04C | LP-165P

Spherical harmonic gravitational potential model, specified according to the specified Central body.

Dependencies

To enable this parameter, set Propagation method to Numerical (high precision). Available options are based on Central body settings:

Central body	Spherical Harmonic Model Option
Earth	EGM2008, EGM96, or EIGEN-GL04C
Moon	LP-100K or LP-165P
Mars	GMM2B

Programmatic Use

Block Parameter: 'earthSH' when centralBody set to 'Earth' | 'moonSH' when centralBody set to 'Moon' | 'marsSH' when centralBody set to 'Mars'

Type: character vector

Values: 'EGM2008' | 'EGM96' | 'EIGEN-GL04C' when centralBody set to 'earthSH'; 'LP-100K' | 'LP-165P' when centralBody set to 'moonSH'; 'GMM2B' when centralBody set to 'marsSH'

Default: 'Spherical harmonics'

Spherical harmonic coefficient file — Harmonic coefficient MAT-file

aerogmm2b.mat (default) | harmonic coefficient MAT-file

Harmonic coefficient MAT-file that contains definitions for a custom planetary model, specified as a character vector or string.

This file must contain:

Variable	Description
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.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Custom.

• Gravitational potential model to Spherical harmonics.

Programmatic Use

Block Parameter: shFile

Type: character vector

Values: 'aerogmm2b.mat' | harmonic coefficient MAT-file

Default: 'aerogmm2b.mat'

Degree — Degree of harmonic model

120 (default) | scalar | maximum of 2159

Degree of harmonic model, specified as a double scalar:

Planet Model	Recommended Degree	Maximum Degree
EGM2008	120	2159
EGM96	70	360
LP100K	60	100
LP165P	60	165
GMM2B	60	80
EIGENGL04C	70	360

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Earth, Moon, Mars, or Custom.

• Gravitational potential model to Spherical harmonics.

Programmatic Use

Block Parameter: shDegree

Type: character vector

Values: '80' | scalar

Default: '80'

Use Earth orientation parameters (EOPs) — Use Earth orientation parameters

on (default) | off

Select this check box to use Earth orientation parameters for the transformation between the ICRF and fixed-frame coordinate systems. Otherwise, clear this check box.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Earth.

Programmatic Use

Block Parameter: useEOPs

Type: character vector

Values: 'on' | 'off'

Default: 'on'

IERS EOP data file — Earth orientation data

aeroiersdata.mat (default) | MAT-file

Custom list of Earth orientation data, specified in a MAT-file.

Dependencies

To enable this parameter:

• Select the Use Earth orientation parameters (EOPs) to check box.

• Set Propagation method to Numerical (high precision).

• Set Central body to Earth.

Programmatic Use

Block Parameter: eopFile

Type: character vector

Values: 'aeroiersdata.mat' | MAT-file

Default: 'aeroiersdata.mat'

Input Moon libration angles — Moon libration angle rate

off (default) | on

To specify libration angles (φ θ ψ) for Moon orientation, select this check box.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Moon.

Programmatic Use

Block Parameter: useMoonLib

Type: character vector

Values: 'off' | 'on'

Default: 'off'

Output quaternion (ICRF to Fixed-frame) — Add output transformation quaternion port

off (default) | on

To add output transformation quaternion port for the quaternion transformation from the ICRF to the Fixed-frame coordinate system, select this check box.

Dependencies

To enable this check box, set Propagation method to Numerical (high precision).

Programmatic Use

Block Parameter: outputTransform

Type: character vector

Values: 'off' | 'on'

Default: 'off'

Central body spin axis source — Central body spin source

Port (default) | Dialog

Central body spin axis, specified as Port or Dialog. The block uses the spin axis to calculate the transformation from the ICRF to the fixed-frame coordinate system for the custom central body.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Custom.

Programmatic Use

Block Parameter: cbPoleSrc

Type: character vector

Values: 'Port' | 'Dialog'

Default: 'Port'

Spin axis right ascension (RA) at J2000 (deg) — Right ascension of central body spin axis at J2000

317.68143 (default) | double scalar

Right ascension of central body spin axis at J2000 (2451545.0 JD, 2000 Jan 1 12:00:00 TT), specified as a double scalar.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Custom.

• Central body spin axis source to Dialog.

Programmatic Use

Block Parameter: cbRA

Type: character vector

Values: '317.68143' | double scalar

Default: '317.68143'

Spin axis RA rate (deg/century) — Right ascension rate of central body spin axis

-0.1061 (default) | double scalar

Right ascension rate of the central body spin axis, specified as a double scalar, in specified angle units/century.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Custom.

• Central body spin axis source to Dialog.

Programmatic Use

Block Parameter: cbRARate

Type: character vector

Values: '-0.1061' | double scalar

Default: '-0.1061'

Spin axis declination (Dec) at J2000 (deg) — Declination of central body spin axis at J2000

52.88650 (default) | double scalar

Declination of the central body spin axis at J2000 (2451545.0 JD, 2000 Jan 1 12:00:00 TT), specified as a double scalar.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Custom.

• Central body spin axis source to Dialog.

Programmatic Use

Block Parameter: cbDec

Type: character vector

Values: '52.88650' | double scalar

Default: '52.88650'

Spin axis Dec rate (deg/century) — Declination rate of central body spin axis

-0.0609 (default) | double scalar

Declination rate of the central body spin axis, specified as a double scalar, in specified angle units/century.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Custom.

• Central body spin axis source to Dialog.

Programmatic Use

Block Parameter: cbDecRate

Type: character vector

Values: '-0.0609' | double scalar

Default: '-0.0609'

Initial rotation angle at J2000 (deg) — Rotation angle of central body x-axis

176.630 (default) | double scalar

Rotation angle of the central body x axis with respect to the ICRF x-axis at J2000 (2451545.0 JD, 2000 Jan 1 12:00:00 TT), specified as a double scalar, in specified angle units.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Custom.

• Central body spin axis source to Dialog.

Programmatic Use

Block Parameter: cbRotAngle

Type: character vector

Values: '176.630' | double scalar

Default: '176.630'

Rotation rate (deg/day) — Rotation rate of central body x-axis

350.89198226 (default) | double scalar

Rotation rate of the central body x axis with respect to the ICRF x-axis (2451545.0 JD, 2000 Jan 1 12:00:00 UTC), specified as a double scalar, specified angle units/day.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Custom.

• Central body spin axis source to Dialog.

Programmatic Use

Block Parameter: cbRotRate

Type: character vector

Values: '350.89198226' | double scalar

Default: '350.89198226'

Equatorial radius — Equatorial radius

3396200 (default) | double scalar

Equatorial radius for a custom central body, specified as a double scalar.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Gravitational potential model to Point-mass or Oblate ellipsoid (J2).

Programmatic Use

Block Parameter: customR

Type: character vector

Values: '3396200' | double scalar

Default: '3396200'

Flattening — Flattening ratio

0.00589 (default) | double scalar

Flattening ratio for custom central body, specified as a double scalar.

Dependencies

To enable this parameter, set:

• Central body to Custom.

• Gravitational potential model to Point-mass or Oblate ellipsoid (J2).

Programmatic Use

Block Parameter: customF

Type: character vector

Values: '0.00589' | double scalar

Default: '0.00589'

Gravitational parameter — Gravitational parameter

4.305e13 (default) | double scalar

Gravitational parameter for a custom central body, specified as a double scalar.

Dependencies

To enable this parameter, set:

• Central body to Custom.

• Gravitational potential model to Point-mass or Oblate ellipsoid (J2).

Programmatic Use

Block Parameter: customMu

Type: character vector

Values: '4.305e13' | double scalar

Default: '4.305e13'

Second degree zonal harmonic (J2) — Most significant or largest spherical harmonic term

1.0826269e-03 (default) | double scalar

Most significant or largest spherical harmonic term, which accounts for oblateness of a celestial body, specified as a double scalar.

Dependencies

To enable this parameter, set:

• Propagation method to Numerical (high precision).

• Central body to Custom.

• Gravitational potential model to Oblate ellipsoid (J2).

Programmatic Use

Block Parameter: customJ2

Type: character vector

Values: '1.0826269e-03' | double scalar

Default: '1.0826269e-03'

Units

Units — Parameter and port units

Metric (m/s) (default) | Metric (km/s) | Metric (km/h) | English (ft/s) | English (kts)

Parameter and port units, specified as:

Units	Distance Units	Velocity Units	Acceleration Units
Metric (m/s)	meters	meters/sec	meters/sec2
Metric (km/s)	kilometers	kilometers/sec	kilometers/sec2
Metric (km/h)	kilometers	kilometers/hour	kilometers/hour2
English (ft/s)	feet	feet/sec	feet/sec2
English (kts)	nautical mile	knots	knots/sec

Programmatic Use

Block Parameter: units

Type: character vector

Values: 'Metric (m/s)' | 'Metric (km/s)' | 'Metric (km/h)' | 'English (ft/s)' | 'English (kts)'

Default: 'Metric (m/s)'

Angle units — Angle units

Degrees (default) | Radians

Parameter and port units for angles, specified as Degrees or Radians.

Programmatic Use

Block Parameter: angleUnits

Type: character vector

Values: 'Degrees' | 'Radians'

Default: 'Degrees'

Time format — Time format for start date and time output

Julian date (default) | Gregorian

Time format for Start date/time (UTC Julian date) and output port t_utc, specified as Julian date or Gregorian.

Programmatic Use

Block Parameter: timeFormat

Type: character vector

Values: 'Julian date' | 'Gregorian'

Default: 'Julian date'

Model Examples

Constellation Modeling with the Orbit Propagator Block

Propagate the orbits of a constellation of satellites and compute and visualize access intervals between the individual satellites and several ground stations. It uses:

Open Live Script

Mission Analysis with the Orbit Propagator Block

Compute and visualize line-of-sight access intervals between satellite(s) and a ground station. It uses:

Open Live Script

Lunar Mission Analysis with the Orbit Propagator Block

Compute and visualize line-of-sight access intervals between the Apollo Command and Service module (CSM) and a rover on the lunar surface. The module's orbit is modeled using Reference Trajectory #2 from the NASA report Variations of the Lunar Orbital Parameters of the Apollo CSM-Module [2]. This is a lunar orbit studied by NASA for the Apollo program. The example uses:

Open Live Script

Algorithms

Coordinate Systems

The Orbit Propagator block works in the ICRF and fixed-frame coordinate systems:

• ICRF — International Celestial Reference Frame. This frame can be treated as equal to the ECI coordinate system realized at J2000 (Jan 1 2000 12:00:00 TT. For more information, see ECI Coordinates).

• Fixed-frame — Fixed-frame is a generic term for the coordinate system that is fixed to the central body (its axes rotate with the central body and are not fixed in inertial space).

  • When Propagation method is Numerical (high precision), Central Body is Earth, and the Use Earth orientation parameters (EOPs) check box is selected, the Fixed-frame for Earth is the International Terrestial Reference Frame (ITRF). This reference frame is realized by the IAU2000/2006 reduction from the ICRF coordinate system using the earth orientation parameter file provided. If the Use Earth orientation parameters (EOPs) check box is cleared, the block still uses the IAU2000/2006 reduction, but with Earth orientation parameters set to 0.

  • When Propagation method is High precision (numerical), Central Body is Moon, and the Input Moon libration angles check box is selected, the fixed-frame coordinate system for the Moon is the Mean Earth/pole axis frame (ME). This frame is realized by two transformations. First, the values in the ICRF frame are transformed into the Principal Axis system (PA), the axis defined by the libration angles provided as inputs to the block. For more information, see Moon Libration. The states are then transformed into the ME system using a fixed rotation from the "Report of the IAU/IAG Working Group on cartographic coordinates and rotational elements: 2006" [5]. If Input Moon libration angles check box is cleared, the fixed frame is defined by the directions of the poles of rotation and prime meridians defined in the "Report of the IAU/IAG Working Group on cartographic coordinates and rotational elements: 2006" [5].

  • When Propagation method is Numerical (high precision) and Central Body is Custom, the fixed-frame coordinate system is defined by the poles of rotation and prime meridian defined by the block input α, δ, W, or the spin axis properties.

In all other cases, the fixed frame for each central body is defined by the directions of the poles of rotation and prime meridians defined in the "Report of the IAU/IAG Working Group on cartographic coordinates and rotational elements: 2006" [5].

Orbit Propagation Methods

The Orbit Propagator block supports two top-level orbit propagation methods: Kepler (unperturbed) and Numerical (high precision).

Kepler (unperturbed)

This option uses universal variables and Newton-Raphson iteration to propagate satellite orbits over time. This analytical algorithm is fast, but has limitations. Propagated orbits account only for central body spherical (point-mass) gravity. This formulation includes no other perturbations.

This propagation method is always performed in the ICRF intertial coordinate system with origin at the center of the central body. Given initial intertial position r₀ and velocity v₀ at time t₀, first find orbital energy, ξ, and the reciprocal of the semi-major axis, α:

$\begin{array}{l}\xi =\frac{v_0{}^2}{2}-\frac{\mu }{r_0}\\ \alpha =\frac{-2\xi }{\mu },\end{array}$

where μ is the standard gravitation parameter of the central body. Next, determine the orbit type from the sign of α.

• α>0 => Circular or elliptical

• α<0 => Hyperbolic

• α≈0 => Parabolic

To initialize the Newton-Raphson iteration, select an initial guess for χ based on the orbit type:

• Circular or elliptical orbit

  ${\chi }_0\approx \sqrt{\mu }(\Delta t)\alpha ,$

  where Δt is the propagation step size (simulation time step). If Δt exceeds the orbital period $T=2\pi \sqrt{\frac{a^3}{\mu }}$, wrap Δt.

• Parabolic Orbit

  ${\chi }_0\approx \sqrt{p}2\cot (2w),$

  where:

  $\begin{array}{l}\overrightarrow{h}=\overrightarrow{r_0}\times \overrightarrow{v_0}\\ p=\frac{h\cdot h}{\mu }\\ \cot (2s)=3\sqrt{\frac{\mu }{p^3}}(\Delta t)\\ {\tan }^3(w)=\tan (s).\end{array}$

• Hyperbolic orbit:

  ${\chi }_0\approx \text{sign}(\Delta t)\sqrt{-\frac{1}{\alpha }}\ln (\frac{-2\mu \alpha (\Delta t)}{\overrightarrow{r_0}\cdot \overrightarrow{v_0}+\text{sign}(\Delta t)\sqrt{-\frac{\mu }{\alpha }}(1-r_0\alpha )}).$

  Perform Newton-Raphson iteration while |x_n-x_n-1| > tolerance.

  $$\begin{array}{l}{\chi }_{n+\text{1}}={\chi }_n+\frac{\sqrt{\mu }(\Delta t)-{\chi }_n{}^3{c}_3-\frac{\overrightarrow{r_0}\cdot \overrightarrow{v_0}}{\sqrt{\mu }}{\chi }_n{}^2{c}_2-r_0{\chi }_n(1-\psi c_3)}{{\chi }_n{}^2{c}_2+\frac{\overrightarrow{r_0}\cdot \overrightarrow{v_0}}{\sqrt{\mu }}{\chi }_n(1-\psi c_3)+r_0(1-\psi c_2)}\\ {\chi }_n\Leftarrow {\chi }_{n+\text{1}},\end{array}$$

  where:

  $$\psi ={\chi }_n{}^2\alpha .$$

  (if ψ>0),

  $\begin{array}{l}{c}_2=\frac{1-\cos (\sqrt{\psi })}{\psi }\\ c_3=\frac{\sqrt{\psi }-\sin (\sqrt{\psi })}{\sqrt{{\psi }^3}}.\end{array}$

  (if ψ<0),

  $\begin{array}{l}{c}_2=\frac{1-\cosh (\sqrt{-\psi })}{\psi }\\ c_3=\frac{\sinh (\sqrt{-\psi })-\sqrt{-\psi }}{\sqrt{{(-\psi )}^3}}.\end{array}$

  (if ψ≈0),

  $\begin{array}{l}{c}_2=\frac{1}{2}\\ c_3=\frac{1}{6}.\end{array}$

  Calculate universal variables $$f$$, $$\dot{f}$$, $$\text{g}$$, and $$\dot{g}$$.

  $\begin{array}{l}f=1-\frac{{\chi }_n{}^2}{r_0}{c}_2\\ \dot{f}=\frac{\sqrt{\mu }}{r{r}_0}{\chi }_n(\psi c_3-1)\\ g=(\Delta t)-\frac{{\chi }_n{}^3}{\sqrt{\mu }}{c}_3\\ \dot{g}=1-\frac{{\chi }_n{}^2}{r}{c}_2.\end{array}$

  Assemble position and velocity output vectors:

  $\begin{array}{l}\overrightarrow{r_{\text{icrf}}}=f\overrightarrow{r_0}+g\overrightarrow{v_0}\\ \overrightarrow{v_{\text{icrf}}}=\dot{f}\overrightarrow{r_0}+\dot{g}\overrightarrow{v_0}.\end{array}$

Numerical (high precision)

This option uses the Simulink^® solver to integrate position and velocity from central body gravitational acceleration at each simulation timestep (Δt). The method for computing central body acceleration depends on the current setting for parameter Gravitational potential model. You can also include custom acceleration components in to the propagation algorithm using the block A_icrf (applied acceleration) input port. For gravity models that include nonspherical acceleration terms, the block computes nonspherical gravity in a fixed-frame coordinate system (ITRF, in the case of Earth). Numerical integration, however, is always performed in the inertial ICRF coordinate system. Therefore, at each timestep, the block:

1. Transforms position and velocity states into the fixed-frame.

2. Calculates nonspherical gravity in the fixed-frame.

3. Transforms resulting acceleration into the inertial frame, where it is summed with the other acceleration terms and integrated.

$\begin{array}{l}\overrightarrow{a_{\text{icrf}}}={\overrightarrow{a}}_{\text{central}\text{body}\text{gravity}}+{\overrightarrow{a}}_{\text{applied}}\\ \overrightarrow{a_{\text{icrf}}}\underset{\text{integrate}}{\Rightarrow }\overrightarrow{r_{\text{icrf}}},\overrightarrow{v_{\text{icrf}}}\end{array}$

• Point-mass (available for all central bodies)

  This option treats the central body as a point-mass, including only the effects of spherical gravity using Newton's law of universal gravitation.

  ${\overrightarrow{a}}_{\text{centralbodygravity}}=-\frac{\mu }{r^2}\frac{\overrightarrow{r_{\text{icrf}}}}{r},$

  where μ is the standard gravitation parameter of the central body.

• Oblate ellipsoid (J2) (available for all central bodies)

  In addition to spherical gravity, this option includes the perturbing effects of the second-degree, zonal harmonic gravity coefficient J₂, accounting for the oblateness of the central body. J₂ accounts for the vast majority of the central bodies gravitational departure from a perfect sphere.

  $${\stackrel{\rightharpoonup }{a}}_{centralbodygravity}=-\frac{\mu }{r^2}\frac{\overrightarrow{r_{\text{icrf}}}}{r}+fixed2inertial({\stackrel{\rightharpoonup }{a}}_{nonspherical}),$$

  where:

  $$\begin{array}{l}{\overrightarrow{a}}_{\text{nonspherical}}=\\ \{[\frac{1}{r}\frac{\partial }{\partial r}U-\frac{r_{\text{ff}}{}_{{}_k}}{r^2\sqrt{r_{\text{ff}}{{}_{{}_i}}^2+r_{\text{ff}}{{}_{{}_j}}^2}}\frac{\partial }{\partial \varphi }U]r_{\text{ff}}{}_{{}_i}\}i\\ +\{[\frac{1}{r}\frac{\partial }{\partial r}U+\frac{r_{\text{ff}}{}_{{}_k}}{r^2\sqrt{r_{\text{ff}}{{}_{{}_i}}^2+r_{\text{ff}}{{}_{{}_j}}^2}}\frac{\partial }{\partial \varphi }U]r_{\text{ff}}{}_{{}_j}\}j\\ +\{\frac{1}{r}(\frac{\partial }{\partial r}U)r_k+\frac{\sqrt{r_{\text{ff}}{{}_{{}_i}}^2+r_{\text{ff}}{{}_{{}_j}}^2}}{r^2}\frac{\partial }{\partial \varphi }U\}k,\end{array}$$

  given the partial derivatives in spherical coordinates:

  $\begin{array}{l}\frac{\partial }{\partial r}U=\frac{3\mu }{r^2}{(}^{\frac{R_{\text{cb}}}{r}}{P}_{2,0}[\sin (\varphi )]J_2\\ \frac{\partial }{\partial \varphi }U=-\frac{\mu }{r}{(}^{\frac{R_{\text{cb}}}{r}}{P}_{2,1}[\sin (\varphi )]J_2\end{array}$

  where:

  • ϕ and λ — Satellite geocentric latitude and longitude.

  • P_2,0 and P_2,1 — Associated Legendre functions.

  • μ — Standard gravitation parameter of the central body.

  • R_cb — Central body equatorial radius.

  The transformation fixed2inertial converts fixed-frame position, velocity, and acceleration into the ICRF coordinate system with origin at the center of the central body, accounting for centrifugal and coriolis acceleration. For more information about the fixed and intertial coordinate systems used for each central body, see Coordinate Systems.

• Spherical Harmonics (available for Earth, Moon, Mars, Custom)

  This option adds increased fidelity by including higher-order perturbation effects accounting for zonal, sectoral, and tesseral harmonics. For reference, the second-degree, zeroth order zonal harmonic J₂=-C₂₀. The Spherical Harmonics model accounts for harmonics up to max degree l=l_max, which varies by central body and geopotential model.

  $${\stackrel{\rightharpoonup }{a}}_{centralbodygravity}=-\frac{\mu }{r^2}\frac{\overrightarrow{r_{\text{icrf}}}}{r}+fixed2inertial({\stackrel{\rightharpoonup }{a}}_{nonspherical}),$$

  where:

  $$\begin{array}{l}{\stackrel{\rightharpoonup }{a}}_{nonspherical}=\\ \left\{\left[\frac{1}{r}\frac{\partial }{\partial r}U-\frac{r_{\text{ff}}{}_{{}_k}}{r^2\sqrt{r_{\text{ff}}{{}_{{}_i}}^2+r_{\text{ff}}{{}_{{}_j}}^2}}\frac{\partial }{\partial \varphi }U]r_{\text{ff}}{}_{{}_i}-[\frac{1}{r_{\text{ff}}{{}_{{}_i}}^2+r_{\text{ff}}{{}_{{}_j}}^2}\frac{\partial }{\partial \lambda }U\right]r_{\text{ff}}{}_{{}_j}\right\}i\\ +\left\{\left[\frac{1}{r}\frac{\partial }{\partial r}U+\frac{r_{\text{ff}}{}_{{}_k}}{r^2\sqrt{r_{\text{ff}}{{}_{{}_i}}^2+r_{\text{ff}}{{}_{{}_j}}^2}}\frac{\partial }{\partial \varphi }U]r_{\text{ff}}{}_{{}_j}+[\frac{1}{r_{\text{ff}}{{}_{{}_i}}^2+r_{\text{ff}}{{}_{{}_j}}^2}\frac{\partial }{\partial \lambda }U\right]r_{\text{ff}}{}_{{}_i}\right\}j\\ +\left\{\frac{1}{r}(\frac{\partial }{\partial r}U)r_{\text{ff}}{}_{{}_k}+\frac{\sqrt{r_{\text{ff}}{{}_{{}_i}}^2+r_{\text{ff}}{{}_{{}_j}}^2}}{r^2}\frac{\partial }{\partial \varphi }U\right\}k,\end{array}$$

  given the following partial derivatives in spherical coordinates:

  $$\begin{array}{l}\frac{\partial }{\partial r}U=-\frac{\mu }{r^2}\underset{l=2}{\overset{l_{\max }}{{{\displaystyle \sum }}^{\text{}}}}\underset{m=0}{\overset{l}{{{\displaystyle \sum }}^{\text{}}}}{(}^{\frac{R_{\text{cb}}}{r}}(l+1)P_{l,m}[\sin (\varphi )]\{C_{l,m}\cos (m\lambda )+S_{l,m}\sin (m\lambda )\}\\ \frac{\partial }{\partial \varphi }U=\frac{\mu }{r}\underset{l=2}{\overset{l_{\max }}{{{\displaystyle \sum }}^{\text{}}}}\underset{m=0}{\overset{l}{{{\displaystyle \sum }}^{\text{}}}}{(}^{\frac{R_{\text{cb}}}{r}}\{P_{l,m+1}[\sin (\varphi )]-(m)\tan (\varphi )P_{l,m}[\sin (\varphi )]\}\{C_{l,m}\cos (m\lambda )+S_{l,m}\sin (m\lambda )\}\\ \frac{\partial }{\partial \lambda }U=\frac{\mu }{r}\underset{l=2}{\overset{l_{\max }}{{{\displaystyle \sum }}^{\text{}}}}\underset{m=0}{\overset{l}{{{\displaystyle \sum }}^{\text{}}}}{(}^{\frac{R_{\text{cb}}}{r}}(m)P_{l,m}[\sin (\varphi )]\{S_{l,m}\cos (m\lambda )-C_{l,m}\sin (m\lambda )\},\end{array}$$

  where:

  • ϕ and λ — Satellite geocentric latitude and longitude.

  • P_l,m — Associated Legendre functions.

  • μ — Standard gravitation parameter of the central body.

  • R_cb — Central body equatorial radius.

  • C_l,m and S_l,m — Nonnormalized harmonic coefficients.

  The transformation fixed2inertial converts fixed-frame position, velocity, and acceleration into the ICRF coordinate system with origin at the center of the central body, accounting for centrifugal and coriolis acceleration. For more information about the fixed and intertial coordinate systems used for each central body, see Coordinate Systems.

References

[1] Vallado, David. Fundamentals of Astrodynamics and Applications, 4th ed. Hawthorne, CA: Microcosm Press, 2013.

[2] 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, NASA Lyndon B. Johnson Space Center, Houston, Texas, February 1993.

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

[4] 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, Vol. 106, No. E10, pp 23359-23376, October 25, 2001.

[5] Seidelmann, P.K., Archinal, B.A., A’hearn, M.F. et al. "Report of the IAU/IAG Working Group on cartographic coordinates and rotational elements: 2006." Celestial Mech Dyn Astr 98, 155–180 (2007).

Extended Capabilities

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

Version History

Introduced in R2020b