satelliteScenario

Satellite scenario

Since R2021a

Description

The satelliteScenario object represents a 3-D arena consisting of satellites, ground stations, and the interactions between them. Use this object to model satellite constellations, model ground station networks, perform access analyses between the satellites and the ground stations, and visualize the results.

Creation

Syntax

sc = satelliteScenario

sc = satelliteScenario(startTime,stopTime,sampleTime)

sc = satelliteScenario(___,'AutoSimulate',false)

Description

sc = satelliteScenario creates a default satellite scenario object.

sc = satelliteScenario(startTime,stopTime,sampleTime) sets the StartTime, StopTime, and SampleTime properties to the values of startTime, stopTime, and sampleTime, respectively.

sc = satelliteScenario(___,'AutoSimulate',false) sets the AutoSimulate property to a specified value.

Properties

StartTime — Start time of satellite scenario simulation in UTC

datetime scalar

Start time of the satellite scenario simulation in UTC, specified as a datetime scalar.

The default StartTime is the current UTC time if no satellites are present in the scenario. Otherwise, it is the earliest value among

• the current UTC time.

• the epoch defined in the TLE files.

• the reference time deduced from the GPS week number defined in SEM files.

• the earliest time deduced from RINEX navigation data for GPS and Galileo.

• the initial time in the timetable and timeseries.

If the StartTime, StopTime, or SampleTime properties are explicitly specified, the StartTime property no longer updates with further additions of satellites.

When the AutoSimulate property is false, you can modify the StartTime property only when the SimulationStatus is NotStarted. You can use the restart function to reset SimulationStatus to NotStarted, but doing so erases the simulation data.

Data Types: datetime

StopTime — Stop time of satellite scenario simulation in UTC

datetime scalar

Stop time of the satellite scenario simulation in UTC, specified as a datetime scalar. The default StopTime is StartTime + longest orbital period among the satellites in the scenario. If no satellites are added to the scenario, the default StopTime is the same as the default StartTime. If the StartTime, StopTime, or SampleTime properties are explicitly specified, the StopTime property no longer updates with further additions of satellites.

When the AutoSimulate property is false, you can modify the StopTime property only when the SimulationStatus is NotStarted. You can use the restart function to reset SimulationStatus to NotStarted, but doing so erases the simulation data.

Data Types: datetime

SampleTime — Sample time of satellite scenario simulation

scalar

Sample time of the satellite scenario simulation, specified as a real-valued scalar. The default sample time is set such that there are 100 samples between StartTime and StopTime. If the default StartTime and StopTime are the same, which is the case when no satellites are added to the scenario, the default SampleTime is 60 seconds. If the StartTime, StopTime, or SampleTime properties are explicitly specified, the SampleTime property no longer updates with further additions of satellites.

When the AutoSimulate property is false, you can modify the SampleTime property only when the SimulationStatus is NotStarted. You can use the restart function to reset SimulationStatus to NotStarted, but doing so erases the simulation data.

Data Types: double

SimulationTime — Simulation time of satellite scenario in UTC

current UTC time (default) | datetime scalar

This property is read-only.

Current simulation time of the satellite scenario simulation in UTC, specified as a datetime scalar. Call the restart function to reset the time to StartTime.

Dependencies

To enable this property, set AutoSimulate to false.

Data Types: datetime

SimulationStatus — Simulation status

'NotStarted' (default) | 'InProgress' | 'Completed'

This property is read-only.

Simulation status of the satellite scenario, specified as one of the following:

• 'NotStarted' — No call to the advance function has been made

• 'InProgress' — Simulation is running

• 'Completed' — Simulation is finished

The simulation starts when the first call to the advance function is made. The simulation continues until one of the following occurs:

• The simulation reaches the StopTime.

• A new asset is added to the satellite scenario.

• Certain properties of the asset (satellites, ground stations, gimbals, conical sensors, and so on) have been modified, such as MountingLocation or MountingAngles. Refer to the properties to determine if modifying them can stop the simulation.

Call the restart function to restart the simulation, erase the simulation data, and set SimulationStatus to NotStarted.

Dependencies

To enable this property, set AutoSimulate to false.

AutoSimulate — Option to simulate satellite scenario automatically

true or 1 (default) | false or 0

Option to simulate the satellite scenario automatically, specified as one of these numeric or logical values.

• 1 (true) — Simulate the satellite scenario automatically on any call to an analysis function, such as states or accessIntervals.

• 0 (false)— Simulate the satellite scenario only by calling the advance function.

Changing the AutoSimulate value erases the previous simulation data.

Data Types: double

Satellites — Satellites in the scenario

row vector of Satellite objects

Satellites in the scenario, returned as a row vector of Satellite objects. To create a Satellite object and add it to the satellite scenario, use the satellite object function. After adding satellites to the scenario, this property is read-only.

Platforms — Platforms in the scenario

row vector of Platforms objects

Platforms in the scenario, returned as a row vector of Platform (Satellite Communications Toolbox) objects. To create a Platform (Satellite Communications Toolbox) object and add it to the satellite scenario, use the platform (Satellite Communications Toolbox) object function. After adding platforms to the scenario, this property is read-only.

GroundStations — Ground stations in scenario

row vector of GroundStation objects

Ground stations in the scenario, returned as a row vector of GroundStation objects. To create a GroundStation object and add it to the satellite scenario, use the groundStation object function. After adding ground stations to the scenario, this property is read-only.

AutoShow — Option to automatically show graphics

true or 1 (default) | false or 0

Option to automatically show graphics, specified as a logical 1 (true) or 0 (false). This property determines if entities added to the scenario are automatically shown in an open satelliteScenarioViewer window.

NumericalPropagatorOptions — Options used by the numerical orbit propagator

scalar

Options used by the numerical orbit propagator, specified as a scalar. To modify these options, use the numericalPropagator function.

Object Functions

groundStation	Add ground station to satellite scenario
satellite	Add satellites to satellite scenario
satelliteScenarioViewer	Create viewer for satellite scenario
advance	Move simulation forward by one sample time
restart	Restart simulation from beginning
play	Play satellite scenario simulation results on viewer
walkerDelta	Create Walker-Delta constellation in satellite scenario
walkerStar	Create Walker-Star constellation in satellite scenario
numericalPropagator	Add or modify satellite scenario numerical orbit propagator options

Examples

Create Satellite Scenario with Custom Start and Stop Times

Specify the start time in the current time zone as yesterday. The simulation lasts for half a day.

startTime = datetime("yesterday","TimeZone","local");
stopTime = startTime + days(0.5);

Specify the sample time as 60 seconds. Create a satellite scenario object, specifying the start time, stop time, and sample time.

sampleTime = 60;
sc = satelliteScenario(startTime,stopTime,sampleTime)

sc = 
  satelliteScenario with properties:

         StartTime: 04-Sep-2024 04:00:00
          StopTime: 04-Sep-2024 16:00:00
        SampleTime: 60
      AutoSimulate: 1
        Satellites: [1x0 matlabshared.satellitescenario.Satellite]
    GroundStations: [1x0 matlabshared.satellitescenario.GroundStation]
         Platforms: [1x0 matlabshared.satellitescenario.Platform]
           Viewers: [0x0 matlabshared.satellitescenario.Viewer]
          AutoShow: 1

Add Satellites to Scenario Using Keplerian Elements

Create a satellite scenario with a start time of 02-June-2020 8:23:00 AM UTC, and the stop time set to one day later. Set the simulation sample time to 60 seconds.

startTime = datetime(2020,6,02,8,23,0);
stopTime = startTime + days(1);
sampleTime = 60;
sc = satelliteScenario(startTime,stopTime,sampleTime);

Add two satellites to the scenario using their Keplerian elements.

semiMajorAxis = [10000000;15000000];
eccentricity = [0.01;0.02];
inclination = [0;10];
rightAscensionOfAscendingNode = [0;15];
argumentOfPeriapsis = [0;30];
trueAnomaly = [0;20];

sat = satellite(sc,semiMajorAxis,eccentricity,inclination, ...
    rightAscensionOfAscendingNode,argumentOfPeriapsis,trueAnomaly)

sat = 
  1x2 Satellite array with properties:

    Name
    ID
    ConicalSensors
    Gimbals
    Transmitters
    Receivers
    Accesses
    GroundTrack
    Orbit
    OrbitPropagator
    MarkerColor
    MarkerSize
    ShowLabel
    LabelFontColor
    LabelFontSize

View the satellites in orbit and the ground tracks over one hour.

show(sat)
groundTrack(sat,LeadTime=3600)

ans=1×2 object
  1×2 GroundTrack array with properties:

    LeadTime
    TrailTime
    LineWidth
    LeadLineColor
    TrailLineColor
    VisibilityMode

Play the scenario and set the animation speed of the simulation to 40.

play(sc,PlaybackSpeedMultiplier=40)

Manual Simulation of Satellite Scenario

Create a satellite scenario object and set the AutoSimulate property to false to enable manual simulation of the satellite scenario.

sc = satelliteScenario('AutoSimulate',false);

Add a GPS satellite constellation to the scenario.

sat = satellite(sc,"gpsAlmanac.txt");

Simulate the scenario using the advance function.

while advance(sc)
end

Obtain the satellite position histories.

p = states(sat);

AutoSimulate is false, so restart the scenario before adding a ground station.

restart(sc);

Add a ground station to the scenario.

gs = groundStation(sc);

Add access analysis between each satellite and ground station.

ac = access(sat,gs);

Simulate the scenario and determine the access intervals.

while advance(sc)
end
intvls1 = accessIntervals(ac)

intvls1=35×8 table
     Source           Target           IntervalNumber         StartTime                EndTime           Duration    StartOrbit    EndOrbit
    ________    ___________________    ______________    ____________________    ____________________    ________    __________    ________

    "PRN:1"     "Ground station 32"          1           11-Jan-2020 23:20:25    12-Jan-2020 05:15:47      21322        NaN          NaN   
    "PRN:2"     "Ground station 32"          1           12-Jan-2020 04:03:16    12-Jan-2020 07:48:06      13490        NaN          NaN   
    "PRN:3"     "Ground station 32"          1           11-Jan-2020 19:50:06    11-Jan-2020 21:38:53     6527.3        NaN          NaN   
    "PRN:3"     "Ground station 32"          2           12-Jan-2020 01:52:43    12-Jan-2020 06:42:49      17406        NaN          NaN   
    "PRN:4"     "Ground station 32"          1           11-Jan-2020 19:50:06    12-Jan-2020 00:11:11      15665        NaN          NaN   
    "PRN:4"     "Ground station 32"          2           12-Jan-2020 04:54:02    12-Jan-2020 07:48:06      10444        NaN          NaN   
    "PRN:5"     "Ground station 32"          1           12-Jan-2020 05:52:03    12-Jan-2020 07:48:06     6962.4        NaN          NaN   
    "PRN:6"     "Ground station 32"          1           12-Jan-2020 02:43:29    12-Jan-2020 07:48:06      18276        NaN          NaN   
    "PRN:7"     "Ground station 32"          1           11-Jan-2020 21:09:52    12-Jan-2020 03:27:00      22628        NaN          NaN   
    "PRN:8"     "Ground station 32"          1           11-Jan-2020 20:33:36    12-Jan-2020 03:19:45      24369        NaN          NaN   
    "PRN:9"     "Ground station 32"          1           11-Jan-2020 19:50:06    12-Jan-2020 00:47:27      17841        NaN          NaN   
    "PRN:9"     "Ground station 32"          2           12-Jan-2020 05:08:32    12-Jan-2020 07:48:06     9573.3        NaN          NaN   
    "PRN:10"    "Ground station 32"          1           12-Jan-2020 00:32:56    12-Jan-2020 01:59:58     5221.8        NaN          NaN   
    "PRN:11"    "Ground station 32"          1           11-Jan-2020 22:15:09    12-Jan-2020 04:39:32      23063        NaN          NaN   
    "PRN:12"    "Ground station 32"          1           12-Jan-2020 04:32:16    12-Jan-2020 07:48:06      11749        NaN          NaN   
    "PRN:13"    "Ground station 32"          1           12-Jan-2020 00:03:56    12-Jan-2020 02:50:44      10008        NaN          NaN   
      ⋮

Visualize the simulation results.

v = satelliteScenarioViewer(sc,'ShowDetails',false);
play(sc);

Verify that the access intervals are the same when you set the AutoSimulate property to true.

sc.AutoSimulate = true;
intvls2 = accessIntervals(ac)

intvls2=35×8 table
     Source           Target           IntervalNumber         StartTime                EndTime           Duration    StartOrbit    EndOrbit
    ________    ___________________    ______________    ____________________    ____________________    ________    __________    ________

    "PRN:1"     "Ground station 32"          1           11-Jan-2020 23:20:25    12-Jan-2020 05:15:47      21322        NaN          NaN   
    "PRN:2"     "Ground station 32"          1           12-Jan-2020 04:03:16    12-Jan-2020 07:48:06      13490        NaN          NaN   
    "PRN:3"     "Ground station 32"          1           11-Jan-2020 19:50:06    11-Jan-2020 21:38:53     6527.3        NaN          NaN   
    "PRN:3"     "Ground station 32"          2           12-Jan-2020 01:52:43    12-Jan-2020 06:42:49      17406        NaN          NaN   
    "PRN:4"     "Ground station 32"          1           11-Jan-2020 19:50:06    12-Jan-2020 00:11:11      15665        NaN          NaN   
    "PRN:4"     "Ground station 32"          2           12-Jan-2020 04:54:02    12-Jan-2020 07:48:06      10444        NaN          NaN   
    "PRN:5"     "Ground station 32"          1           12-Jan-2020 05:52:03    12-Jan-2020 07:48:06     6962.4        NaN          NaN   
    "PRN:6"     "Ground station 32"          1           12-Jan-2020 02:43:29    12-Jan-2020 07:48:06      18276        NaN          NaN   
    "PRN:7"     "Ground station 32"          1           11-Jan-2020 21:09:52    12-Jan-2020 03:27:00      22628        NaN          NaN   
    "PRN:8"     "Ground station 32"          1           11-Jan-2020 20:33:36    12-Jan-2020 03:19:45      24369        NaN          NaN   
    "PRN:9"     "Ground station 32"          1           11-Jan-2020 19:50:06    12-Jan-2020 00:47:27      17841        NaN          NaN   
    "PRN:9"     "Ground station 32"          2           12-Jan-2020 05:08:32    12-Jan-2020 07:48:06     9573.3        NaN          NaN   
    "PRN:10"    "Ground station 32"          1           12-Jan-2020 00:32:56    12-Jan-2020 01:59:58     5221.8        NaN          NaN   
    "PRN:11"    "Ground station 32"          1           11-Jan-2020 22:15:09    12-Jan-2020 04:39:32      23063        NaN          NaN   
    "PRN:12"    "Ground station 32"          1           12-Jan-2020 04:32:16    12-Jan-2020 07:48:06      11749        NaN          NaN   
    "PRN:13"    "Ground station 32"          1           12-Jan-2020 00:03:56    12-Jan-2020 02:50:44      10008        NaN          NaN   
      ⋮

Visualize the scenario.

play(sc);

Tips

• When saving the satellite scenario, either save the entire workspace containing the scenario object or save the scenario object itself.

Version History

Introduced in R2021a

R2024b: Satellite scenario: Align SGP4/SDP4 with Revisiting Spacetrack Report #3

The Aerospace Toolbox now incorporates the latest and most accurate equations from https://celestrak.org/publications/AIAA/2006-6753/ in satelliteScenario. Both the SGP4 and SDP4 orbit propagators use these equations and return identical results. The algorithms are detailed in the work of Vallado, David, et al, “Revisiting Spacetrack Report #3.”, AIAA/AAS Astrodynamics Specialist Conference and Exhibit, American Institute of Aeronautics and Astronautics, 2006, https://celestrak.org/publications/AIAA/2006-6753/.