numericalPropagator

Add or modify satellite scenario numerical orbit propagator options

Since R2024a

Syntax

options = numericalPropagator(scenario)

options = numericalPropagator(___,Name=Value)

Description

options = numericalPropagator(scenario) adds a numericalPropagator object scenario and returns the options used by the numerical orbit propagator in scenario. If the scenario already contains a numerical orbit propagator, it returns the currently used options.

options = numericalPropagator(___,Name=Value) adds a numerical orbit propagator to scenario using options specified by one or more name-value arguments. If the scenario already contains a numerical orbit propagator, it updates the currently used options specified by the name-value arguments. The options corresponding to the unspecified name-value arguments remain unchanged. When AutoSimulate of scenario is false, you can specify the optional name-value arguments only if SimulationStatus is set to NotStarted.

Input Arguments

scenario — Satellite scenario

satelliteScenario object

Satellite scenario, specified as a scalar satelliteScenario object.

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.

Example: ODESolver = 'ode78' sets the ODE solver to 'ode78'.

ODESolver — ODE solver used by propagator

'ode23' | 'ode78' | 'ode89' | 'ode113' | 'ode15s' | 'ode23s' | 'ode23t' | or 'ode23tb'

Ordinary differential equation (ODE) solver used by the numerical orbit propagator, specified as 'ode45', 'ode23', 'ode78', 'ode89', 'ode113', 'ode15s', 'ode23s','ode23t', or 'ode23tb'.

Default Value

The default value is the current value of ODESolver of NumericalPropagatorOptions property of scenario if property is nonempty, and 'ode45' otherwise.

ODESet — ODE solver options

current value of ODESet in NumericalPropagatorOptions if property is nonempty, and structure returned by odeset(RelTol=1e-8,AbsTol=1e-8) otherwise

ODE solver options, specified as the structure returned by odeset(RelTol=1e-8, AbsTol=1e-8).

GravitationalPotentialModel — Gravitational potential model of Earth

'spherical-harmonics' | 'point-mass' | 'oblate-ellipsoid'

Gravitational potential model of Earth, specified 'spherical-harmonics', 'point-mass', or 'oblate-ellipsoid'. For information on these models, see Gravitational Potential Models.

Default Value

The default value is the current value of GravitationalPotentialModel in NumericalPropagatorOptions property of scenario if property is nonempty, and 'spherical-harmonics'otherwise.

SphericalHarmonicModel — Spherical harmonic model of gravitational potential of Earth

'EGM96' | 'EIGENGL04C'

Spherical harmonic model of gravitational potential of Earth, specified as 'EGM2008', 'EGM96', or 'EIGENGL04C'.

Default Value

The default value is the current value of SphericalHarmonicModel in NumericalPropagatorOptions property of scenario if property is nonempty, and 'EGM2008'otherwise.

Dependencies

To use this input, GravitationalPotentialModel must be set to 'spherical-harmonics'.

SphericalHarmonicDegree — Spherical harmonic degree of gravitational potential of Earth

scalar

Spherical harmonic degree of gravitational potential of Earth, specified as a scalar.

Default Value

The default value is the current value of SphericalHarmonicDegree in NumericalPropagatorOptions property of scenario if property is nonempty, and 120 otherwise.

Dependencies

To use this input, GravitationalPotentialModel must be set to 'spherical-harmonics'.

Data Types: double

IncludeAtmosDrag — Option to indicate whether propagator must account for atmospheric drag

false or 0 | true or 1

Option to indicate whether the propagator must account for atmospheric drag, specified as false (0) or true (1). When set to true, the propagator calculates atmospheric drag based on the NRLMSISE-00 model for atmospheric density.

Default Value

The default value is the current value of IncludeAtmosDrag in NumericalPropagatorOptions property of scenario.

UseSpaceWeatherDataFile — Option to use MAT file containing consolidated space weather data file in atmospheric density calculation

false or 0 | true or 1

Option to use MAT file containing consolidated space weather data file in atmospheric density calculation, specified as false (0) or true (1). See aeroReadSpaceWeatherData for more information on how to generate this MAT file.

Default Value

The default value is the current value of UseSpaceWeatherDataFile in NumericalPropagatorOptions property of scenario.

Dependencies

To use this input GravitationalPotentialModel is set to 'spherical-harmonics'.

SpaceWeatherDataFile — MAT file containing consolidated space weather data file in atmospheric density calculation

character vector | string

MAT file containing consolidated space weather data file in atmospheric density calculation, specified as a character vector or string.

Default Value

The default value is the current value of SpaceWeatherDataFile in NumericalPropagatorOptions property of scenario if property is nonempty, and "aeroSpaceWeatherData.mat" otherwise.

Dependencies

To use this input, IncludeAtmosDrag and UseSpaceWeatherDataFile must be set to true.

F107ExtrapMethod — Method used for extrapolating F10.7 solar flux for times outside range of space weather data file

'constant' | 'least-squares-fit'

Method used for extrapolating F10.7 solar flux for times outside the range of the space weather data file, specified as one of these values:

• 'none-clip' — F10.7 value is set to the nearest data point available in the space weather data file.

• 'constant' — F10.7 value is set to a constant value specified by the F107ExtrapValue name-value argument.

• 'least-squares-fit' — F10.7 value is approximated using a least-squares fit of the space weather data from October 1, 1957, to December 1, 2040, using the trigonometric function a+bcos(ct + dsin(et)).

Default Value

The default value is the current value of F107ExtrapMethod in NumericalPropagatorOptions property of scenario if property is nonempty, and 'none-clip' otherwise.

Dependencies

To use this input IncludeAtmosDrag and UseSpaceWeatherDataFile are set to true.

F107ExtrapValue — Extrapolation value for F10.7 solar flux

nonnegative scalar

Extrapolation value for the F10.7 solar flux, specified as a nonnegative scalar.

Default Value

The default value is the current value of F107ExtrapValue in NumericalPropagatorOptions property of scenario if property is nonempty, and 150 otherwise.

Dependencies

To use this input, IncludeAtmosDrag, UseSpaceWeatherDataFile, and F107ExtrapMethod must be set to 'constant'.

F107Average — Centered 81-day average value of F10.7 solar flux

nonnegative scalar

Centered 81-day average value of the F10.7 solar flux, specified as a nonnegative scalar.

Default Value

The default value is the current value of F107Average in NumericalPropagatorOptions property of scenario if property is nonempty, and 150 otherwise.

Dependencies

To use this input IncludeAtmosDrag and UseSpaceWeatherDataFile are set to false.

F107Daily — Daily value of F10.7 solar flux

current value of F107Daily in NumericalPropagatorOptions property of scenario if property is nonempty, and 150 otherwise (default) | nonnegative scalar

Daily value of F10.7 solar flux from the previous day, specified as a nonnegative scalar.

Default Value

The default value is the current value of F107Daily in NumericalPropagatorOptions property of scenario if property is nonempty, and 150 otherwise.

Dependencies

To use this input, UseSpaceWeatherDataFile must be set to false.

MagneticIndexExtrapMethod — Method used for extrapolating magnetic index for times outside range of space weather data file

'constant' | 'least-squares-fit'

Method used for extrapolating magnetic index for times outside the range of the space weather data file, specified as one of these values:

• 'none-clip' — Magnetic index is set to the nearest data point available in the space weather data file.

• 'constant' — Magnetic index is set to a constant value specified by MagneticIndexExtrapValue.

• 'igrf' — Magnetic index is calculated using International Geomagnetic Reference Field. Because this model is defined for times between January 1, 1900, 12:00 AM UTC and January 1, 2025, 12:00 AM UTC, the predictions for times outside this range are clipped to values at these time limits.

Default Values

The default value is the current value of SpaceWeatherDataFile in F107ExtrapMethod property of scenario if property is nonempty, and 'none-clip' otherwise.

Dependencies

To use this input IncludeAtmosDrag and UseSpaceWeatherDataFile must be set to false.

MagneticIndexExtrapValue — Extrapolation value for magnetic index

nonnegative scalar

Extrapolation value for the magnetic index, specified as a nonnegative scalar.

Default Value

The default value is the current value of MagneticIndexExtrapValue in F107ExtrapMethod property of scenario if property is nonempty, and 4 otherwise.

Dependencies

To use this input:

• IncludeAtmosDrag and UseSpaceWeatherDataFile must be set to true.

• MagneticIndexExtrapMethod must be set to 'constant'.

MagneticIndex — Magnetic index information

seven-element nonnegative row vector

Magnetic index information, specified as a seven-element row vector. This value consists of magnetic index representing a daily value (AP), three hour AP for a reference time, three hour AP for three hours before the reference time, three hour AP for six hours before the reference time, three hour AP for nine hours before the reference time, average of eight three hour AP indices from 12 to 33 hours prior to the reference time, and average of eight three hour AP indices from 36 to 57 hours prior to the reference time. This vector is constant for the entire scenario.

Default Value

The default value is the current value of MagneticIndex in F107ExtrapMethod property of scenario if property is nonempty, and [4 4 4 4 4 4 4] otherwise.

Dependencies

To use this input:

• IncludeAtmosDrag must be set to true.

• UseSpaceWeatherDataFile must be set to false.

IncludeAnomalousOxygen — Option to specify whether anomalous oxygen must be included in atmospheric mass density calculation

false or 0 | true or 1

Option to specify whether anomalous oxygen must be included in the atmospheric mass density calculation, specified as false (0) or true (1).

Default Value

The default value is the current value of IncludeAnomalousOxygen in NumericalPropagatorOptions property of scenario if property is nonempty, and true or 1 otherwise.

Dependencies

To use this input, IncludeAtmosDrag must be set to true.

AtmosFlags — Option to activate or deactivate particular variations in atmospheric mass density calculation

vector of 23 double elements

Option to activate or deactivate particular variations in atmospheric mass density calculation, specified as a vector of 23 double elements. The elements are defined in the order shown in the table:

AtmosFlags elements

Element	Value
1	F10.7 effect on mean
2	Independent of time
3	Symmetrical annual
4	Symmetrical semiannual
5	Asymmetrical annual
6	Asymmetrical semiannual
7	Diurnal
8	Semidiurnal
9	Daily AP. If you set this value to -1, the atmospheric mass density computation uses the entire magnetic index information that includes the three-hour averages, as opposed to just the daily value.
10	All UT seconds, longitudinal effects
11	Longitudinal
12	UT seconds and mixed UT seconds, longitudinal
13	Mixed AP, UT seconds, longitudinal
14	Terdiurnal
15	Departures from diffusive equilibrium
16	All exospheric temperature variations
17	All variations from 120,000 meter temperature (TLB)
18	All lower thermosphere (TN1) temperature variations
19	All 120,000 meter gradient (S) variations
20	All upper stratosphere (TN2) temperature variations
21	All variations from 120,000 meter values (ZLB)
22	All lower mesosphere temperature (TN3) variations
23	Turbopause scale height variations

With the exception of element 9 (daily AP), the elements are specified as 0 or 1. Element 9 is specified as -1, 0 or 1.

Default Value

The default value is the current value of AtmosFlags in NumericalPropagatorOptions property of scenario if property is nonempty, or ones(1,23) otherwise.

Dependencies

To use this input, IncludeAtmosDrag must be set to true.

IncludeThirdBodyGravity — Option to specify whether third body gravity should be included

false or 0 | true or 1

Option to specify whether third body gravity should be included, specified as false (0) or true (1).The third body gravity sources are assumed to be point masses.

Default Value

The default value is the current value of IncludeThirdBodyGravity in NumericalPropagatorOptions property of scenario.

ThirdBodyGravitySource — Third body gravity source

'sun' | 'moon' | 'mercury' | 'venus' | 'mars' | 'jupiter' | 'saturn' | 'uranus' | 'neptune' | 'pluto'

Third body gravity source, specified as one of 'sun', 'moon', 'mercury', 'venus', 'mars', 'jupiter', 'saturn', 'uranus', 'neptune', or 'pluto'.

Default Values

The default value is the current value of ThirdBodyGravitySource in NumericalPropagatorOptions property of scenario if property is nonempty, and ["Sun" "Moon"] otherwise.

Dependencies

To use this input, IncludeThirdBodyGravity must be set to true.

IncludeSRP — Option to indicate whether solar radiation pressure should be included

false or 0 | true or 1

Option to indicate whether solar radiation pressure should be included, specified as false (0) or true (1).

Default Value

The default value is the current value of IncludeSRP in NumericalPropagatorOptions property of scenario.

SolarFluxPressure — Solar flux pressure acting at 1 Astronomical Unit (AU) from Sun

nonnegative scalar

Solar flux pressure acting at 1 Astronomical Unit (AU) from Sun, specified as a nonnegative scalar in W*s/m³.

Default Value

The default value is the current value of SolarFluxPressure in NumericalPropagatorOptions property of scenario if property is nonempty, and 4.5344321e-6 otherwise.

Data Types: double

EclipseModel — Eclipse model used in solar radiation pressure computation

'cylindrical'

Eclipse model used in the solar radiation pressure computation, specified as one of 'dual-cone' or 'cylindrical'.

Default Values

The default value is the current value of EclipseModel in NumericalPropagatorOptions property of scenario if property is nonempty, and 'dual-cone' otherwise.

Dependencies

To use this input, IncludeSRP must be set to true

Data Types: string

IncludeLunarEclipse — Option to indicate whether lunar occultation must be included in solar radiation pressure calculation

true or 1

Option to indicate whether lunar occultation must be included in solar radiation pressure calculation, specified as false (0) or true (1).

Default Values

The default value is the current value of IncludeLunarEclipse in NumericalPropagatorOptions property of scenario if property is nonempty, and false otherwise.

Dependencies

To use this input, IncludeSRP must be set to true

Data Types: logical

PlanetaryEphemerisModel — Celestial body ephemeris model used in the computation of third body gravity and solar radiation pressure

'de421' | 'de423' | 'de430' | 'de432t'

Celestial body ephemeris model used in the computation of third body gravity and solar radiation pressure, specified as one of:

• 'de405' — Released in 1998. This ephemerides takes into account the Julian date range 2305424.50 (December 9, 1599) to 2525008.50 (February 20, 2201).

• 'de421' — Released in 2008. This ephemerides takes into account the Julian date range 2414992.5 (December 4, 1899) to 2469808.5 (January 2, 2050).

• 'de423' — Released in 2010. This ephemerides takes into account the Julian date range 2378480.5 (December 16, 1799) to 2524624.5 (February 1, 2200).

• 'de430' — Released in 2013. This ephemerides takes into account the Julian date range 2287184.5 (December 21, 1549) to 2688976.5 (January 25, 2650).

• 'de432t' — Released in April 2014. This ephemerides takes into account the Julian date range 2287184.5, (December 21, 1549 ) to 2688976.5, (January 25, 2650).

Default Values

The default value is the current value of EphemerisModel of the NumericalPropagatorOptions property of scenario if property is nonempty, and 'de405' otherwise.

Dependencies

To use this input, IncludeSRP and IncludeThirdBodyGravity must be set to true.

Data Types: string

Output Arguments

options — Currently used options for the numerical orbit propagator

NumericalPropagatorOptions object

Currently used options for the numerical orbit propagator, returned as a scalar NumericalPropagatorOptions object.

More About

Gravitational Potential Models

Gravitational potential models are used to describe the gravitational field of celestial bodies like planets. The Aerospace Toolbox offers these two models:

Point-Mass Model

In the Point-Mass Model, a celestial body is treated as a point mass. This model assumes that the mass is concentrated at a single point at the center of the body. Mathematically, this model is defined as:

$$V(r)=-\frac{GM}{r}$$

where V(r) is the gravitational potential, G is the gravitational constant, M is the mass of the body, and r is the distance from the center of the body.

Oblate-Ellipsoid Model

The Oblate-Ellipsoid Model accounts for the fact that many celestial bodies, like Earth, are not perfect spheres but rather oblate due to their rotation. This model involves an expansion of the gravitational potential in terms of spherical harmonics, which better represents the body's shape. The first few terms in this expansion are crucial for understanding perturbations:

• J2: Represents the quadrupole moment, accounting for the flattening at the poles and bulging at the equator. It is the most significant term after the point-mass term and leads to perturbations in satellite orbits, such as precession.

• J4: Represents the hexadecapole moment, a smaller correction that further refines the model by considering more subtle deviations from spherical symmetry.

In the oblate-ellipsoid model, the gravitational potential is expressed as:

$$V(r)=-\frac{GM}{r}\left[1-{\displaystyle \sum _{n=2}^{\infty }{\left(\frac{R}{r}\right)}^n{J}_n{P}_n(\cos \theta )}\right]$$

where

• R is the mean radius of the body.

• θ is the colatitude, which describes the position of a point on a celestial body. It is defined as the angular distance from the point to the North Pole of the sphere. Colatitude is calculated by subtracting the latitude from 90 degrees.

• J_n are the zonal harmonics coefficients (with J₂ and J₄ being the most significant).

• P_n are the Legendre polynomials.

Version History

Introduced in R2024a