Doppler Shift
ASecurityUse when you must compute the doppler frequency shift on a spacecraft link: derive the line-of-sight range rate from the circular-orbit altitude and the ground elevation angle, convert it to the received frequency and offset on an s-band downlink carrier, and estimate the worst-case doppler near the horizon and the doppler-rate at acquisition for receiver acquisition design. Produces the range rate, received frequency, delta-f offset, maximum doppler, slant range and doppler rate that gate co...
- 2 stars
- 0 votes
- 0 copies
- 4 views
- Added September 27, 2026
Works with
Security analysis
100/100Pro scans all 3 files and shows the line behind each finding
npx -y skills add ashfordeOU/aero-agent-skills --skill doppler-shift --agent claude-codeAre you the author of Doppler Shift?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/ashfordeou-doppler-shift)---
name: doppler-shift
description: "Use when you must compute the doppler frequency shift on a spacecraft link: derive the line-of-sight range rate from the circular-orbit altitude and the ground elevation angle, convert it to the received frequency and offset on an s-band downlink carrier, and estimate the worst-case doppler near the horizon and the doppler-rate at acquisition for receiver acquisition design. Produces the range rate, received frequency, delta-f offset, maximum doppler, slant range and doppler rate that gate communication link acquisition. Trigger: doppler shift, received frequency offset, acquisition frequency offset, worst-case doppler, doppler rate, line-of-sight range rate, s-band downlink, leo overflight, spacecraft ground link."
license: Apache-2.0
compliance: STANDARDS-REF
standards:
- id: ecss
reference-only: true
gated: false
domain: space-systems
pack: subsystems
compatibility: "agentskills.io SKILL.md; any SKILL.md host (Claude Code, Hermes, OpenClaw)"
metadata:
domain: space-systems
subdomain: subsystems
tags: [doppler-shift, range-rate-frequency-offset, doppler-rate, line-of-sight-relative-velocity, acquisition-frequency-offset, worst-case-doppler]
version: 0.1.0
author: AeroSkills
---
# Doppler Shift on a Spacecraft Link (space-systems/subsystems/doppler-shift)
Use when you must compute the doppler frequency shift on a spacecraft
link: the frequency offset a ground receiver must track as a
circular-orbit satellite passes, derived from the pass geometry. This
leaf implements the straight-line overflight model (range rate
rho_dot = -v * cos(elev) from the circular speed and the ground
elevation angle) in pure Python, stdlib only, and converts the range
rate into the received carrier frequency, the delta-f acquisition
offset, the worst-case doppler at the horizon and the doppler rate at
acquisition. It pairs with communication-link-budget for the received
power and margin side of the same pass, and with satellite-coverage for
the pass access geometry that feeds the elevation angle.
## Domain quick reference
- Circular speed at altitude h (m): v = sqrt(MU / (R_EARTH + h)) with
R_EARTH = 6371.0e3 m and MU = 3.986004418e14 m^3/s^2. At 600 km,
v = 7561.73 m/s.
- Range rate at elevation elev (deg): rho_dot = -v * cos(elev),
negative while the satellite approaches (closing). Overhead (90 deg)
the range rate is zero.
- Horizontal distance and slant range: x = h / tan(elev), then
rho = sqrt(h^2 + x^2). At 600 km and 30 deg elevation,
x = 1039.2 km and rho = 1200.0 km.
- Received frequency: f_rx = f_tx * (1 - rho_dot / C) with
C = 299792458.0 m/s; delta_f = f_rx - f_tx. A closing satellite
(negative rho_dot) raises the received frequency, so delta_f is
positive while approaching and falls to zero overhead.
- Worst-case doppler: at the horizon (elev 0) the shift is
f_tx * v / C, the maximum over the pass.
- Doppler rate at acquisition: rho_dot_dot = v^2 * h^2 / rho^3, then
doppler_rate = f_tx / C * |rho_dot_dot| (Hz/s). The Hz/s scale is
carrier dependent; the module defaults to the leaf S-band reference
carrier F_TX_REF = 2.25e9 Hz, so pass f_tx for other carriers.
- Elevation domain: [0, 90] deg. The zenith point is admitted as the
degenerate overhead case; the slant geometry is singular exactly at
the horizon, so use max_doppler for the elevation-0 shift.
- Units are SI: m, m/s, Hz, Hz/s. ECSS frames the space engineering
context; the relations above are standard engineering methodology,
summary-only.
## Workflow
1. Fix the pass geometry: circular altitude h (m) and the link carrier
f_tx (Hz), for example the 2.25 GHz S-band downlink.
2. Get the orbital speed with circular_velocity(h).
3. Get the range rate at the acquisition or current elevation with
range_rate(h, elev_deg); negative while the satellite approaches.
4. Convert to the received carrier with doppler_shift(f_tx, h,
elev_deg), which returns the dict {range_rate, received_freq,
delta_f}.
5. Estimate the worst case over the pass with max_doppler(f_tx, h),
the horizon shift; it equals doppler_shift at elevation 0.
6. Size the acquisition tracking with slant_range_and_rate(h, elev_deg,
f_tx = F_TX_REF), which returns {x, rho, rho_dot, doppler_rate}.
7. Confirm the deterministic checks with the contract test
scripts/test_doppler_shift.py.
## Worked example
A 600 km LEO satellite on a 2.25 GHz S-band downlink acquired at
30 deg elevation. Real module outputs (h = 600e3 m, elev = 30 deg):
- circular_velocity(600e3) = 7561.73 m/s.
- range_rate(600e3, 30) = -6548.65 m/s (closing).
- doppler_shift(2.25e9, 600e3, 30): range_rate -6548.65 m/s, received
frequency 2250049148.9 Hz, delta_f +49148.9 Hz (+49.15 kHz).
- max_doppler(2.25e9, 600e3) = 56752.3 Hz, the horizon worst case.
- slant_range_and_rate(600e3, 30): x = 1039230.5 m, slant range
rho = 1200000.0 m (1200.0 km), rho_dot -6548.65 m/s, doppler rate
89.41 Hz/s at acquisition.
- Overhead identity: doppler_shift(2.25e9, 600e3, 90) gives delta_f 0
and the received frequency back at 2250000000.0 Hz.
- Horizon identity: doppler_shift(2.25e9, 600e3, 0) equals
max_doppler(2.25e9, 600e3) = 56752.3 Hz.
## Verification
- Confirm circular_velocity(600e3) returns 7561.73 m/s (anchor within
1 m/s) and range_rate(600e3, 30) returns -6548.65 m/s within 1 m/s,
with range_rate(600e3, 90) = 0.
- Confirm doppler_shift(2.25e9, 600e3, 30) returns received_freq
2250049148.9 Hz and delta_f +49148.9 Hz within 50 Hz of the
+49.15 kHz anchor, and that the shift is zero at 90 deg.
- Confirm max_doppler(2.25e9, 600e3) = 56752.3 Hz within 100 Hz, that
it equals the shift at elevation 0, and that a higher orbit gives a
smaller worst-case doppler.
- Confirm slant range 1200000.0 m within 1 km and doppler rate
89.41 Hz/s within 2 Hz/s of the 89.4 Hz/s anchor, with dict keys
exactly {x, rho, rho_dot, doppler_rate}.
- Confirm ValueError on h < 0, elevation below 0 or above 90 deg,
f_tx <= 0, and on the singular horizon call of
slant_range_and_rate.
- Run the contract test offline: python3
scripts/test_doppler_shift.py (34 tests, deterministic, exit 0).
## Related leaves
- space-systems/subsystems/communication-link-budget: received power,
antenna gains and margin on the same downlink; no frequency-shift
math.
- space-systems/subsystems/antenna-aperture-sizing: the antenna
aperture and beamwidth for the link that must acquire this shift.
- space-systems/subsystems/command-data-handling: the receiver and
data-handling chain downstream of acquisition.
- space-systems/orbit-mechanics/satellite-coverage: pass access
geometry and visibility windows that set the elevation profile.
- space-systems/mission-design/mission-delta-v-budget: the mission
sizing loop the satellite design feeds.
## Pitfalls
- Flipping the sign convention: the range rate is negative while the
satellite approaches, and a closing satellite RAISES the received
frequency, so delta_f is positive before the pass and crosses zero
at the zenith. Using |rho_dot| in f_rx = f_tx * (1 - rho_dot / C)
inverts the offset and mis-sets the acquisition search direction.
- Reporting the worst-case doppler at the wrong geometry: the maximum
shift occurs at the horizon (elevation 0), not overhead; the zenith
shift is zero. Use max_doppler(f_tx, h), never an elevation-90
doppler_shift call, when sizing the acquisition search range.
- Treating the doppler rate as carrier independent: doppler_rate in
Hz/s scales with f_tx / C, so the 89.41 Hz/s worked-example value is
valid only at the 2.25 GHz reference carrier. Pass f_tx explicitly
for other links or the Hz/s number is wrong.
- Calling slant_range_and_rate at the exact horizon: x = h / tan(elev)
is singular at elevation 0 and raises ValueError by design; the
elevation-0 shift belongs to max_doppler and the doppler_shift
functions, which stay finite there.
- Mixing this leaf with link-budget outputs: this leaf produces
frequency-domain quantities (range rate, offsets, doppler rate)
only; received-power and margin terms belong to
communication-link-budget, and pass-time geometry belongs to
satellite-coverage, not here.
## Behavior contract (gate 3)
Run the deterministic contract test (stdlib unittest, offline):
python3 scripts/test_doppler_shift.py
The test covers the 600 km, 2.25 GHz, 30 deg acquisition contract
(circular velocity 7561.73 m/s, range rate -6548.65 m/s, received
frequency 2250049148.9 Hz with delta_f +49148.9 Hz), the zero-shift
overhead identity, the horizon equality between max_doppler and the
elevation-0 shift, decreasing worst-case doppler with altitude, the
1200.0 km slant range and 89.41 Hz/s doppler-rate anchors, exact dict
key ordering, run-to-run determinism, the module constant values, and
ValueError rejection of negative altitude, out-of-range elevation,
non-positive carrier and the singular horizon slant call.
## Compliance
- Standards referenced, not reproduced: ECSS standards are freely
downloadable (copyright ESA); summary-only per standards-map.yaml
and brief 06.
- compliance: STANDARDS-REF, gated: false.
Files in this skill
- SKILL.md
- scripts/doppler_shift_logic.py
- scripts/test_doppler_shift.py
Attribution
Related skills
View all in ai-agents →Comments
Loading comments…
Newsletter
Get the weekly list of safe new skills, and the ones we pulled.