`orbitforge eclipse`

Synopsis


orbitforge eclipse --constellation <PATH> [OPTIONS]

Description

Finds when each satellite is in Earth’s shadow, distinguishing full shadow (umbra) from partial shadow (penumbra), and reports what fraction of the window each spacecraft spent in sunlight.

This drives power and thermal design. A satellite in eclipse generates nothing from its solar array and must run on batteries, so the longest eclipse sets battery capacity and the number of eclipses per day sets charge-cycle life.

Options

Parameter	Type	Unit	Default	Required	Description
`--constellation`	path	n/a	—	Yes	Path to a constellation JSON file.
`--start`	string	RFC 3339 UTC	`2026-01-01T00:00:00Z`	No	Analysis start epoch.
`--duration-hours`	float	h	—	No	Analysis window length.
`--step-seconds`	float	s	`60`	No	Scan step. Interval boundaries are refined below this resolution.
`--model`	enum	n/a	`two-body`	No	Propagation model.
`--output`	path	n/a	—	No	Write per-satellite intervals as JSON.

Worked example


orbitforge eclipse \
  --constellation demo.json \
  --duration-hours 6 \
  --output ecl.json


Eclipse analysis: 60 satellites over 6.0 h at 60 s scan steps using two_body.
  demo-s0-p00-sat00: sunlit 62.3%, umbra 8057 s, penumbra 82 s, 12 intervals
  demo-s0-p00-sat01: sunlit 62.3%, umbra 8058 s, penumbra 81 s, 12 intervals
  demo-s0-p00-sat02: sunlit 64.8%, umbra 7531 s, penumbra 72 s, 11 intervals
  demo-s0-p00-sat03: sunlit 67.5%, umbra 6956 s, penumbra 72 s, 11 intervals
  demo-s0-p00-sat04: sunlit 68.6%, umbra 6697 s, penumbra 81 s, 13 intervals

Output elided; one line per satellite.

Reading the output

Figure	Example	Meaning
Sunlit	62.3 percent	Fraction of the window in full sunlight
Umbra	8057 s	Total time in full shadow
Penumbra	82 s	Total time in partial shadow
Intervals	12	Number of distinct shadow entries

Twelve intervals in six hours is consistent with roughly four orbits at 550 km: each revolution produces one eclipse entry and exit, and the scan counts umbra and penumbra phases separately.

Penumbra is brief, and that matters

Penumbra totals 72 to 82 seconds against 6700 to 8100 seconds of umbra, so the partial-shadow phase is around one percent of the shadowed time. The transition between full sun and full shadow takes well under a minute.

That is a power-system requirement, not a curiosity. The array output collapses over tens of seconds, so the power bus must handle a near-step load transfer to battery. Modeling eclipse as an instantaneous switch is a reasonable simplification for energy budgeting and a poor one for transient analysis.

Satellites in the same plane differ

sat00 at 62.3 percent and sat04 at 68.6 percent share a plane and an altitude, yet differ by six percentage points. They are at different true anomalies, so they enter and leave the shadow cylinder at different points in the window, and a six-hour window is short enough that where each satellite starts still biases its total.

For sizing, run a window long enough to average out that phase dependence, and long enough to include seasonal variation in beta angle. Six hours answers “what does the shadow geometry look like now”; it does not answer “what is the worst eclipse this spacecraft will ever see”, which is what battery sizing needs.

Umbra and penumbra

Region	Definition	Consequence
Umbra	The Sun’s disc is entirely blocked by the Earth	No solar power at all
Penumbra	The Sun’s disc is partially blocked	Reduced and rapidly changing power
Sunlit	Unobstructed	Full array output

The distinction exists because the Sun is an extended source, not a point. A point source would produce a sharp shadow boundary; a disc produces a gradient, and the penumbra is that gradient.

Model basis: Conical shadow geometry

Assumptions: Spherical Earth casting an umbral cone and a penumbral cone from an extended solar disc; solar position from the built-in ephemeris; no atmospheric refraction, which in reality bends some sunlight into the geometric umbra; no lunar eclipses.
Validity range: Earth orbits at any altitude. The refraction omission matters most for grazing geometries, where the true shadow boundary is softer and slightly smaller than the geometric one.
Accuracy: Interval boundaries resolved to better than the scan step through refinement. Neglecting refraction shifts entry and exit times by of order a second for low Earth orbit, which is immaterial for energy budgeting.
Reference: Standard conical umbra and penumbra construction from an extended solar disc; see Vallado, Fundamentals of Astrodynamics and Applications.

Using the result

Question	Figure to use
How much battery capacity?	Longest single umbra interval, plus margin
How many charge cycles over the mission?	Interval count, extrapolated over the design life
What is the energy balance?	Sunlit fraction against array output and average load
What are the thermal extremes?	Interval durations, since the spacecraft radiates without solar input throughout

The console prints totals. For per-interval start and end times, use --output and read the JSON; battery sizing needs the longest single interval, not the sum.

orbitforge eclipse