eclipseStatus

Calculate status of solar occultation

Since R2023b

Syntax

status = eclipseStatus(eclipse_objects)

status = eclipseStatus(eclipse_objects, datetimeIn)

[status,datetimeOut] = eclipseStatus(___)

[status,datetimeOut,earthOccType] = eclipseStatus(___)

[status,datetimeOut,earthOccType, lunarOccType] = eclipseStatus(___)

Description

status = eclipseStatus(eclipse_objects) returns status, which represents the history of solar occultation status as observed from the parent asset of each eclipse object in the input vector eclipse_objects.

If the value of the AutoSimulate property of the satellite scenario is true, the function returns the occultation status history from StartTime to StopTime. Otherwise, the function returns the occultation status history from StartTime to SimulationTime.

status = eclipseStatus(eclipse_objects, datetimeIn) returns a column vector of solar occultation status status at the specified datetime datetimeIn.

[status,datetimeOut] = eclipseStatus(___) returns the solar occultation status status and the corresponding datetime datetimeOut in UTC.

[status,datetimeOut,earthOccType] = eclipseStatus(___) returns the solar occultation status status, the corresponding datetime datetimeOut in UTC, and the solar occultation type caused by the Earth (earthOccType).

[status,datetimeOut,earthOccType, lunarOccType] = eclipseStatus(___) returns the solar occultation status status, the corresponding datetime datetimeOut in UTC, the solar occultation type caused by the Earth (earthOccType), and the solar occultation type caused by the Moon (lunarOccType).

Examples

Calculate Status of Solar Occultation

Add an eclipse analysis object to a satellite, sc, and calculate the status when solar occultation occurs, eclStatus.

Create a satellite scenario object, sat.

startTime = datetime(2023,4,20);
stopTime = startTime + days(1);
sampleTime = 10; % seconds
sc = satelliteScenario(startTime,stopTime,sampleTime);

Add a satellite, sat, to the scenario sc. Set the orbit propagator as a two-body-keplerian.

sat = satellite(sc, ...
    10000000, ... % semimajor axis, meters
    0, ...        % eccentricity
    0, ...        % inclination, degrees
    0, ...        % right ascension of ascending node, degrees
    0, ...        % argument of periapsis, degrees
    0, ...        % true anomaly, degrees
    OrbitPropagator="two-body-keplerian");

Add the eclipse analysis object to the satellite, sat. Include the lunar eclipse in the analysis. By default, the eclipse model is for a dual-cone.

eclSat = eclipse(sat,IncludeLunarEclipse=true)

eclSat = 
  Eclipse with properties:

           EclipseModel: "dual-cone"
    IncludeLunarEclipse: 1

Calculate the status for the eclipse object, eclSat.

status = eclipseStatus(eclSat)

status = 1×8641

     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1     1

Calculate Status and Sample Time of Solar Occultation

Add an eclipse analysis object to a satellite, sc, and ground station, gs, and calculate the status and sample time when solar occultation occurs, [eclStatus eclTime].

Create a satellite scenario object, sat.

startTime = datetime(2023,4,20);
stopTime = startTime + days(1);
sampleTime = 10; % seconds
sc = satelliteScenario(startTime,stopTime,sampleTime);

Add a ground station, gs, to the scenario, sc.

gs1 = groundStation(sc, ...
    1.038102, ... % latitude, degrees
    135.980085);  % longitude, degrees

Add a satellite, sat, to the scenario sc. Set the orbit propagator as a two-body-keplerian.

sat = satellite(sc, ...
    10000000, ... % semimajor axis, meters
    0, ...        % eccentricity
    0, ...        % inclination, degrees
    0, ...        % right ascension of ascending node, degrees
    0, ...        % argument of periapsis, degrees
    0, ...        % true anomaly, degrees
    OrbitPropagator="two-body-keplerian");

Add the eclipse analysis object to the ground station gs. Include the lunar eclipse in the analysis. By default, the eclipse model is for a dual-cone.

eclGs = eclipse(gs1,IncludeLunarEclipse=true)

eclGs = 
  Eclipse with properties:

           EclipseModel: "dual-cone"
    IncludeLunarEclipse: 1

Add the eclipse analysis object to the satellite sat. Include the lunar eclipse in the analysis. By default, the eclipse model is for a dual-cone.

eclSat = eclipse(sat,IncludeLunarEclipse=true)

eclSat = 
  Eclipse with properties:

           EclipseModel: "dual-cone"
    IncludeLunarEclipse: 1

Calculate the status and sample time for the eclipse objects eclSat and eclGs.

[status,datetimeOut]= eclipseStatus([eclSat eclGs],(datetime(2023,4,20)))

status = 2×1

     1
     1

datetimeOut = datetime
   20-Apr-2023

Input Arguments

eclipse_objects — Vector of eclipse objects

vector

Vector of eclipse objects, specified as a vector of Eclipse objects.

Example: eclSat, where eclSat is a vector eclipse objects added to satellites.

datetimeIn — Time at which to calculate status

datetime scalar

Time at which to calculate status, specified as a datetime scalar. If no time zone is specified in datetimeIn, the function assumes that the time zone is UTC.

Example: datetime(2023,4,20)

Output Arguments

status — Status of solar occultation

matrix

Status of solar occultation for each eclipse object, returned as a matrix. The rows of the output matrix correspond to the eclipse objects in eclipse_objects. The columns correspond to the time sample.

A status value of 1 represents no occultation. A value of 0 represents full occultation.

Data Types: double

datetimeOut — Sample time at which status is returned

scalar | row vector

Sample time at which status is returned as a scalar or row vector. Each time sample corresponds to each eclipse object in eclipse_objects.

If the solar occultation status history is returned, datetimeOut is a row vector.

earthOccType — Solar occultation type caused by Earth

scalar | row vector

Solar occultation type caused by Earth, returned as a scalar or row vector of Aero.satellitescenario.EclipseType enumeration object with one of these values:

earthOccType Value	EclipseModel
Umbra	dual-cone and cylindrical
SunLight	dual-cone and cylindrical
Penumbra	dual-cone
Antumbra	dual-cone

These types correspond to integer (int32) values 0, 1, 2 and 3 respectively.

If the solar occultation status history is returned, earthOccType is a row vector.

lunarOccType — Solar occultation type caused by Moon

scalar | row vector

Lunar occultation type caused by the Moon, returned as a scalar or row vector of Aero.satellitescenario.EclipseType enumeration object with one of these values:

lunarOccType Value	EclipseModel
Umbra	dual-cone and cylindrical
SunLight	dual-cone and cylindrical
Penumbra	dual-cone
Antumbra	dual-cone

These types correspond to integer (int32) values 0, 1, 2 and 3 respectively.

If the lunar occultation status history is returned, lunarOccType is a row vector.

Version History

Introduced in R2023b