numericalPropagator

R2026b

Add or modify satellite scenario numerical orbit propagator options

Since R2024a

collapse all in page

    Syntax

    options = numericalPropagator(scenario)
    options = numericalPropagator(___,Name=Value)

    Description

    options = numericalPropagator(scenario) adds a new numerical propagator for the "Earth" central body if one does not already exist, and returns an Aero.satellitescenario.NumericalPropagatorOptions object. The object is added to the NumericalPropagatorOptions property of scenario.

    options = numericalPropagator(___,Name=Value) adds or updates a numerical orbit propagator to scenario using options specified by one or more name-value arguments. If a propagator for the specified central body exists, only the provided name-value arguments are updated. When the AutoSimulate property of scenario is set to false, you can specify the optional name-value arguments only if the SimulationStatus property is set to "NotStarted".

    example

    Examples

    collapse all

    Open Live Script

    This example simulates a translunar mission trajectory using impulsive maneuvers and analyzes access between the spacecraft and Deep Space Network (DSN) ground stations on Earth. The spacecraft departs low Earth orbit, performs a translunar injection (TLI) burn, and inserts into lunar orbit using a lunar orbit insertion (LOI) burn.

    Define the simulation time span and sample time.

    startTime  = datetime(2024,1,26);
stopTime   = datetime(2024,1,31);
sampleTime = 60;   % seconds
sc = satelliteScenario(startTime, stopTime, sampleTime);

    Use numerical propagation with point-mass gravity and enable third-body gravity from the Moon to model the translunar trajectory.

    numericalPropagator(sc, ...
    GravitationalPotentialModel = "point-mass", ...
    IncludeThirdBodyGravity     = true, ...
    ThirdBodyGravitySource      = "Moon");

    Create a spacecraft using Keplerian orbital elements and specify numerical orbit propagation.

    spacecraft = satellite(sc, ...
    6.578137e6, ...  % Semimajor axis (m)
    0, ...           % Eccentricity
    28.24, ...       % Inclination (deg)
    3.303, ...       % Right ascension of ascending node (deg)
    0, ...           % Argument of periapsis (deg)
    124.96, ...      % True anomaly (deg)
    OrbitPropagator = "numerical", ...
    Name = "Spacecraft");

    Specify a translunar injection (TLI) burn defined in the Earth-referenced VNB frame, followed by a lunar orbit insertion (LOI) burn defined in the Moon-referenced VNB frame.

    Time = [ ...
    datetime(2024,1,26,0,57,36); ...
    datetime(2024,1,30,0,57,36) ];
DeltaV = [ ...
    3142.27   0   0; ...
    -747.33    0   0 ];
CoordinateFrame = ["vnb"; "vnb"];
ReferenceCelestialBody = ["Earth"; "Moon"];
Name = ["TLI"; "LOI"];
maneuvers = timetable( ...
    Time, DeltaV, CoordinateFrame, Name, ReferenceCelestialBody);

impulsiveManeuver(spacecraft, Insert = maneuvers);

    Add DSN ground stations located in Canberra, Goldstone, and Madrid.

    dsn = [ ...
    groundStation(sc, -35.4, 148.97, Name="Canberra"); ...
    groundStation(sc,  35.3,-116.78, Name="Goldstone"); ...
    groundStation(sc,  40.4,  -4.25, Name="Madrid") ];

    Analyze access between the spacecraft and the DSN ground stations, accounting for obstruction by both Earth and Moon.

    ac = access(spacecraft, dsn, ...
    ObstructingBodies = ["Earth","Moon"]);

accessIntervals(ac);

    Launch the Satellite Scenario Viewer and animate the scenario to visualize the translunar trajectory and DSN visibility.

    v = satelliteScenarioViewer(sc, ...
    CameraReferenceFrame = "Inertial");

play(sc);
camtarget(v, spacecraft);

    Input Arguments

    collapse all

    Satellite scenario, specified as a scalar satelliteScenario object.

    Name-Value Arguments

    collapse all

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

    Since R2026b

    Central body used by the numerical orbit propagator, specified as "Earth" or "Moon".

    If the scenario already contains a numerical propagator for the specified CentralBody name-value argument, the existing object is returned.

    Data Types: string

    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:

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

    Default Value

    The default value is:

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

    Default Value

    The default value is:

    Spherical harmonic model of gravitational potential of central body, specified as one of these values:

    • For "Earth" central body, "EGM2008", "EGM96", or "EIGENGL04C"

    • For "Moon" central body, "LP100K" or "LP165P"

    Default Value

    The default value is:

    • The current value of SphericalHarmonicModel in the NumericalPropagatorOptions property of scenario when that property is nonempty and its CentralBodyOptions property equals the CentralBody name‑value argument

    • Otherwise:

      • "EGM2008" when the CentralBody name‑value argument equals "Earth"

      • "LP100K" when the CentralBody name‑value argument equals "Moon"

    Dependencies

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

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

    Default Value

    The default value is:

    Dependencies

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

    Data Types: double

    Option to indicate whether the propagator accounts for atmospheric drag for an Earth central body, specified as false (0) or true (1). When set to true, the propagator computes atmospheric drag using the NRLMSISE‑00 atmospheric density model.

    Default Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody equals "Earth". Specifying this input when CentralBody equals "Moon" returns an error.

    Data Types: logical

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

    Default Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody equals "Earth". Specifying this input when CentralBody equals "Moon" returns an error.

    Data Types: logical

    MAT file containing consolidated space weather data file, specified as a string scalar or character vector.

    Default Value

    The default value is:

    Dependencies

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

    • This input is applicable only when CentralBody equals "Earth".

    Data Types: char | string

    Method used to extrapolate F10.7 solar flux 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+b*cos(ct + d*sin(et)).

    Default Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody equals "Earth".

    Data Types: char | string

    Value used to extrapolate F10.7 solar flux outside the range of the space weather data file, specified as a nonnegative scalar.

    Default Value

    The default value is:

    Dependencies

    • This value is used only when the F107ExtrapMethod name‑value argument is set to "constant" and the scenario simulation time falls outside the data range in the space weather data file.

    • This input is applicable only when CentralBody equals "Earth".

    Data Types: scalar

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

    Default Value

    The default value is:

    Dependencies

    • This value is used when the UseSpaceWeatherDataFile name‑value argument is set to false.

    • This input is applicable only when CentralBody equals "Earth".

    Data Types: scalar

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

    Default Value

    The default value is:

    Dependencies

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

    • This input is applicable only when CentralBody equals "Earth".

    Method used to extrapolate 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 Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody equals "Earth".

    Value used to extrapolate the magnetic index outside the range of the space weather data file, specified as a nonnegative scalar.

    Default Value

    The default value is:

    Dependencies

    • This value is used only when the MagneticIndexExtrapMethod name‑value argument is set to "constant" and the scenario simulation time falls outside the data range in the space weather data file.

    • This input is applicable only when CentralBody equals "Earth".

    Magnetic index information, specified as a seven-element nonnegative row vector. This vector is constant for the entire scenario.

    The elements represent, in order:

    1. Daily magnetic index value (AP)

    2. 3‑hour AP value at the reference time

    3. 3‑hour AP value 3 hours before the reference time

    4. 3‑hour AP value 6 hours before the reference time

    5. 3‑hour AP value 9 hours before the reference time

    6. Average of eight 3‑hour AP indices from 12 to 33 hours before the reference time

    7. Average of eight 3‑hour AP indices from 36 to 57 hours before the reference time

    Default Value

    The default value is:

    Dependencies

    • This value is used only when the UseSpaceWeatherDataFile name‑value argument is set to false.

    • This input is applicable only when CentralBody equals "Earth".

    Data Types: double

    Option to include anomalous oxygen in the atmospheric mass density calculation, specified as true (1) or false (0).

    Default Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody equals "Earth".

    Data Types: logical

    Option to enable or disable 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

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

    Dependencies

    This input is applicable only when CentralBody equals "Earth".

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

    Default Value

    The default value is:

    Third body gravity source, specified as a string vector. The valid strings in the vector are "Sun", "Mercury", "Venus", "Earth", "Moon", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", and "Pluto".

    Valid values depend on the specified central body.

    • When the CentralBody name-value argument equals "Earth", the accepted values are "Sun", "Mercury", "Venus", "Moon", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", or "Pluto".

    • When the CentralBody name-value argument equals "Moon", the accepted values are "Sun", "Mercury", "Venus", "Earth", "Mars", "Jupiter", "Saturn", "Uranus", "Neptune", or "Pluto".

    Default Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody is specified.

    Data Types: string

    Option to include solar radiation pressure, specified as false (0) or true (1).

    Default Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody is specified.

    Data Types: logical

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

    Default Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody is specified.

    Data Types: double

    Eclipse model used in the solar radiation pressure computation, specified as one of these values:

    • "dual-cone" — Models the umbra, penumbra, and antumbra regions using a dual‑cone geometry

    • "cylindrical" — Models the eclipse using a cylindrical shadow approximation

    Default Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody is specified.

    Data Types: string

    Option to include lunar occultation in the solar radiation pressure calculation when performing numerical orbit propagation with Earth central body, specified as false (0) or true (1).

    Default Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody equals "Earth".

    Data Types: logical

    Since R2026b

    Option to include Earth occultation in the solar radiation pressure calculation when performing numerical orbit propagation with Moon central body, specified as false (0) or true (1).

    Default Value

    The default value is:

    Dependencies

    This input is applicable only when CentralBody equals "Moon". In addition, Moon must have been added to the scenario as a central body.

    Data Types: logical

    Output Arguments

    collapse all

    Currently used options for the numerical orbit propagator, returned as a scalar NumericalPropagatorOptions object or 1-by-2 vector of Aero.satellitescenario.NumericalPropagatorOptions objects.

    More About

    collapse all

    Version History

    Introduced in R2024a

    See Also

    Objects

    Functions

    Topics