dopplershift

R2026b

Determine Doppler shift at target asset in satellite scenario

Since R2023a

Syntax

shift = dopplershift(source,target)

[shift,timeOut] = dopplershift(source,target)

[shift,timeOut,info] = dopplershift(source,target)

[___] = dopplershift(___,timeIn)

[___] = dopplershift(___,Frequency=freq)

Description

shift = dopplershift(source,target) determines the history of Doppler shifts at the target asset that correspond to the source asset. Both source and target must belong to the same satelliteScenario object. If the value of AutoSimulate property of the satelliteScenario object is true, the dopplershift function returns the Doppler shift history from the value of StartTime to the value of StopTime. Otherwise, the function returns the Doppler shift history from the value of StartTime to the value of SimulationTime.

[shift,timeOut] = dopplershift(source,target) returns the sample time history timeOut.

[shift,timeOut,info] = dopplershift(source,target) returns a structure, info, containing the Doppler rate and relative velocity information.

[___] = dopplershift(___,timeIn) determines Doppler shift at the specified datetime timeIn. When using this syntax, dopplershift sets the second dimension of shift, timeOut, and the fields of info to 1. In this case, the DopplerRate field of info is empty.

[___] = dopplershift(___,Frequency=freq) additionally specifies one or more carrier frequencies at which to calculate Doppler shift.

Note

The dopplershift function uses the International Celestial Reference Frame (ICRF) coordinate system to perform all calculations.

Note

When Moon is added to the satellite scenario, Doppler shift calculations account for Moon line-of-sight obstruction. The function returns NaN when the Moon obstructs the line of sight between the source and target assets.

Examples

Determine Doppler Shift, Doppler Rate, Relative Velocity, and Time History

Determine the Doppler shift, the Doppler rate, the relative velocity, and the corresponding time history at a ground station. The source is a satellite that transmits on a carrier frequency of 14 GHz.

Specify the start time and the stop time of the satellite scenario.

startTime = datetime(2021,4,25);                      % April 25, 2021, 12:00 AM UTC
stopTime = datetime(2021,4,26);                       % April 26, 2021, 12:00 AM UTC

Set the sample time in seconds.

sampleTime = 60; 

Create a satelliteScenario object.

sc = satelliteScenario(startTime,stopTime,sampleTime);

Add a satellite to the scenario.

semiMajorAxis = 10000000;             % In meters
eccentricity = 0;
inclination = 0;                      % In degrees 
rightAscensionOfAscendingNode = 0;    % In degrees
argumentOfPeriapsis = 0;              % In degrees
trueAnomaly = 0;                      % In degrees
sat = satellite(sc,semiMajorAxis,eccentricity,inclination, ...
        rightAscensionOfAscendingNode,argumentOfPeriapsis,trueAnomaly);

Add a default ground station to the scenario.

gs = groundStation(sc);

Determine the Doppler shift, the Doppler rate, and the relative velocity, as well as the corresponding time history.

carrierFrequency=14e9;
[frequencyShift,timeOut,dopplerInfo] = dopplershift(sat,gs,Frequency=carrierFrequency);
frequencyRate = dopplerInfo.DopplerRate;
relativeVelocity = dopplerInfo.RelativeVelocity;

Plot the Doppler shift at the ground station.

plot(timeOut,frequencyShift(1,:)/1e3)       % Doppler shift in kilohertz (kHz)
xlim([timeOut(1) timeOut(end)])
title("Doppler Shift vs. Time")
xlabel("Simulation Time")
ylabel("Doppler Shift (kHz)")
grid on

Input Arguments

source — Source asset from scenario

Satellite object | GroundStation object | Transmitter object | Platform object | array of Satellite objects | array of GroundStation objects | array of Transmitter objects | array of Platform objects

Source asset from scenario, specified as a Satellite , GroundStation , Transmitter , Platform object or an array of Satellite , GroundStation, Transmitter, Platform objects.

target — Target asset from scenario

Satellite object | GroundStation object | Receiver object | Platform object | array of Satellite objects | array of GroundStation objects | array of Receiver objects | array of Platform objects

Target asset from scenario, specified as a Satellite, GroundStation, Receiver, Platform object, or an array of Satellite, GroundStation, Receiver, Platform objects.

timeIn — Time at which function calculates Doppler shift

datetime scalar

Time at which the function calculates the Doppler shift, specified as a datetime scalar. If timeIn does not specify a time zone, the function uses Coordinated Universal Time (UTC).

Data Types: datetime

freq — Carrier frequency

-1 (default) | scalar | vector

Carrier frequency at which to calculate Doppler shift, specified as a scalar or vector of nonnegative real numbers, in hertz or -1. Specify -1 to use the default carrier frequency value for each source asset.

If the freq value is -1 and source is a Satellite, GroundStation, or Platform, the carrier frequency is 14 gigahertz (GHz). If the freq value is -1 and source is a Transmitter, the carrier frequency is the Frequency property value of the Transmitter object.

Data Types: double

Output Arguments

shift — History of Doppler shift

scalar | vector | matrix | 3-D array

History of Doppler shift, in hertz, returned as a scalar, vector, matrix, or 3-D array. When the source and target cannot access each other, the corresponding shift value is NaN. These tables show how this output changes based on the different input argument sizes and combinations.

• timeIn not specified

  source	target	shift	Description
  scalar	scalar	row vector	Doppler shift history, in which each element represents the Doppler shift between source and target at a specific time sample.
  scalar	vector	matrix	Each row represents the Doppler shift history between source and an asset in target. The row corresponds to the position of the asset in target.
  vector	scalar	matrix	Each row represents the Doppler shift history between target and an asset in source. The row corresponds to the position of the asset in source.
  vector	vector	matrix	Each row represents the Doppler shift history between a pair of source and target assets. The row corresponds to the position of the assets in source and target.

• timeIn specified

  source	target	shift	Description
  scalar	scalar	scalar	Doppler shift at the specified datetime timeIn.
  scalar	vector	column vector	Each element represents the Doppler shift between source and the corresponding asset in target at the specified datetime timeIn.
  vector	scalar	column vector	Each element represents the Doppler shift from the corresponding asset in source to target at the specified datetime timeIn.
  vector	vector	column vector	Each element represents the Doppler shift between the corresponding pair of source and target assets at the specified datetime timeIn.

  If you specify freq as a vector, shift has a third dimension in which each page is the output of the corresponding combination of source, target, and timeIn from the previous tables for the corresponding carrier frequency in freq.

Data Types: double

timeOut — Time samples between start and stop time of scenario

datetime vector | datetime scalar

Time samples between the start and stop time of the scenario, returned as a scalar or vector.

If timeIn does not specify a time zone and the AutoSimulate property the satelliteScenario object is true, the dopplershift function returns the time sample history from StartTime to StopTime. Otherwise, the function returns the time sample history from the value of StartTime to the value of SimulationTime.

Data Types: datetime

info — History of Doppler rate and relative velocity

structure

History of Doppler rate and relative velocity, returned as a structure that contains these fields.

• DopplerRate — The Doppler rate history, returned as a vector, matrix, or 3-D array. The format of DopplerRate is similar to shift except that the number of columns equals the number of time samples minus 1.

  DopplerRate value is returned as:

  • NaN — When source and target cannot see each other.

  • Empty — When timein is specified as a scalar, since a datetime scalar is insufficient to calculate the Doppler rate. This applies regardless of visibility between the source and target.

  Follow these steps as a workaround to calculate the Doppler rate at a specific datetime:

  Approximate the Doppler rate at your desired time using numerical differentiation. This involves evaluating the Doppler shift at two closely spaced times around your point of interest and calculating the finite difference. For example:

  dt = seconds(1);     % Small time interval
  t1 = timeIn - dt/2;
  t2 = timeIn + dt/2;
  
  shift1 = dopplershift(sat,gs,t1,Frequency=carrierFrequency);
  shift2 = dopplershift(sat,gs,t2,Frequency=carrierFrequency);
  
  dopplerRateAtTimeIn = (shift2 - shift1)/seconds(dt);

• RelativeVelocity — The history of relative velocity of source and target in the direction from source to target, returned as a scalar, vector, or matrix. The number of rows in the matrix is the greater number between the source and target assets. When source and target cannot access each other, the RelativeVelocity value is NaN.

Data Types: struct

More About

Doppler Shift

If you know the position of the source ($$\overline{P_S}$$) , the position of the target ($$\overline{P_T}$$), the velocity of the source ($$\overline{V_{\text{S}}}$$), the velocity of the target ($$\overline{V_{\text{T}}}$$), and the carrier frequency ($$f_c$$), use these equations to calculate Doppler shift.

1. The unit vector from the source to the target is $$\widehat{dir}=\frac{\overline{P_{\text{T}}}-\overline{P_{\text{S}}}}{\Vert \overline{P_{\text{T}}}-\overline{P_{\text{S}}}\Vert }$$, where $$\Vert \Vert$$ indicates the Euclidean norm.

2. The velocity of the source in the unit direction is

   $$V_{\text{S,dir}}=\overline{V_{\text{S}}}\cdot \widehat{dir}.$$

   If the angle between $$\overline{V_{\text{S}}}$$ and $$\widehat{dir}$$, in degrees, is in the range [0, 90], $$V_{\text{S,dir}}$$ is positive. A positive value of $$V_{\text{S,dir}}$$ indicates the source is moving toward the target. A negative value of $$V_{\text{S,dir}}$$ indicates the source is moving away from the target.

3. The velocity of the target in the unit direction is

   $$V_{\text{T,dir}}=\overline{V_{\text{T}}}\cdot \widehat{dir.}$$

   If the angle between $$\overline{V_{\text{T}}}$$ and $$\widehat{dir}$$, in degrees, is in the range [0, 90], $$V_{\text{T,dir}}$$ is positive. A positive value of $$V_{\text{T,dir}}$$indicates the target is moving away from the source. A negative value of $$V_{\text{T,dir}}$$ indicates the target is moving toward the source.

4. The relative velocity of source and target in the direction from the source to the target is

   $$V_{\text{rel}}=V_{\text{S,dir}}-V_{\text{T,dir}}.$$

5. The Doppler frequency observed at the target is

   $$f_{\text{d}}=\left(\frac{c-V_{\text{T,dir}}}{c-V_{\text{S,dir}}}\right)f_{\text{c}}.$$

   In this equation, c is the speed of light in meters per second.

6. The Doppler shift at the target is

   $$f_{\text{shift}}=f_{\text{d}}-f_{\text{c}}=\left(\frac{V_{\text{rel}}}{c-V_{\text{S,dir}}}\right)f_{\text{c}}.$$

Note

All position and velocity vectors are in the ICRF coordinate frame.

Version History

Introduced in R2023a

R2026b: Lunar workflow support

The dopplershift function now supports assets with CentralBody set to "Moon", including satellites in lunar orbit and ground stations on the Moon. When the Moon is added to the satellite scenario, the function accounts for Moon line-of-sight obstruction and returns NaN when the Moon blocks the line of sight between source and target.