Wolfram Function Repository

Instant-use add-on functions for the Wolfram Language

Function Repository Resource:

 LunarEclipseStarChart

Source Notebook

Visualize the Earth's umbra and penumbra in the sky

Contributed by: Jeff Bryant

ResourceFunction["LunarEclipseStarChart"][]

generates a star chart showing the current position of the Earth's umbra and penumbra.

ResourceFunction["LunarEclipseStarChart"][date]

generates a star chart showing the position of the Earth's umbra and penumbra on the specified date.

Details and Options

During a lunar eclipse, the Moon passes through the Earth's shadow cast by the Sun. The umbra is the inner, dark part of the Earth's shadow. The penumbra is the outer, lighter portion of the Earth shadow and is much more difficult to notice.
The size of the umbra and penumbra are estimates, depending on atmospheric effects.
ResourceFunction["LunarEclipseStarChart"] takes the same options as AstroGraphics, with the following additions and changes:
"AdditionalElements"{}additional graphical elements to include
AstroGridLinesQuantity[1,"AngularDegrees"]coordinate grid lines to draw
AstroProjection"Stereographic"projection to use
AstroRangeQuantity[2,"AngularDegrees"]area of the sky to include
AstroReferenceFrame{"Equatorial", date}observation data (frame, date, location, …)
"PenumbraStyle"Directive[Orange,EdgeForm[Gray],Opacity[.15]]style to use for the penumbra
"ShadowEnlargementFactor"1.01shadow enlargement factor
"UmbraStyle"Directive[Red,EdgeForm[Gray],Opacity[.15]]style to use for the umbra

Examples

Basic Examples (2) 

Plot the penumbra and umbra against the current sky:

In[1]:=
ResourceFunction["LunarEclipseStarChart"][]
Out[1]=

Plot the penumbra and umbra against the sky for the lunar eclipse on March 14, 2025:

In[2]:=
ResourceFunction["LunarEclipseStarChart"][ LunarEclipse[DateObject[{2025, 3, 14}]]]
Out[2]=

Scope (4) 

Partial lunar eclipses begin when the Moon just touches the umbra:

In[3]:=
ResourceFunction["LunarEclipseStarChart"][ LunarEclipse[DateObject[{2025, 3, 14}], "PartialPhaseStartDate", TimeZone -> "GMT"]]
Out[3]=

Partial lunar eclipses end when the Moon just touches the umbra:

In[4]:=
ResourceFunction["LunarEclipseStarChart"][ LunarEclipse[DateObject[{2025, 3, 14}], "PartialPhaseEndDate", TimeZone -> "GMT"]]
Out[4]=

Lunar eclipses start the total phase when the entire Moon enters the umbra:

In[5]:=
ResourceFunction["LunarEclipseStarChart"][ LunarEclipse[DateObject[{2025, 3, 14}], "TotalPhaseStartDate", TimeZone -> "GMT"]]
Out[5]=

Lunar eclipses end the total phase when the Moon starts to exit the umbra:

In[6]:=
ResourceFunction["LunarEclipseStarChart"][ LunarEclipse[DateObject[{2025, 3, 14}], "TotalPhaseEndDate", TimeZone -> "GMT"]]
Out[6]=

Options (5) 

AdditionalElements (2) 

Add any additional graphics primitives, such as text, as additional elements to the scene:

In[7]:=
eclipse = LunarEclipse[DateObject[{2025, 3, 14}]]
Out[7]=
In[8]:=
ResourceFunction["LunarEclipseStarChart"][eclipse, "AdditionalElements" -> {Text[ Style[DateString[eclipse] <> " GMT", White, 14], ImageScaled[{.5, .9}]]}]
Out[8]=

Retrieve the dates of various phases of an eclipse:

In[9]:=
eclipsePartialStart = LunarEclipse[DateObject[{2025, 3, 14}], "PartialPhaseStartDate"];
In[10]:=
eclipseStart = LunarEclipse[DateObject[{2025, 3, 14}], "TotalPhaseStartDate"];
In[11]:=
eclipseMax = LunarEclipse[DateObject[{2025, 3, 14}], "MaximumEclipseDate"];
In[12]:=
eclipseEnd = LunarEclipse[DateObject[{2025, 3, 14}], "TotalPhaseEndDate"];
In[13]:=
eclipsePartialEnd = LunarEclipse[DateObject[{2025, 3, 14}], "PartialPhaseEndDate"];

Compute the angular radius of the Moon for the eclipse date:

In[14]:=
moonRadiusRadians = QuantityMagnitude[ Entity["PlanetaryMoon", "Moon"][ Dated["AngularRadiusFromEarth", eclipseMax]], "Radians"];

Draw white circles showing the position of the Moon at each date and time:

In[15]:=
ResourceFunction["LunarEclipseStarChart"][eclipse, AstroBackground -> AstroStyling[{"BlackSky", "ShowSolarSystemObjects" -> False}], "AdditionalElements" -> {White, Circle[AstroPosition["Moon", eclipsePartialStart], moonRadiusRadians], Circle[AstroPosition["Moon", eclipseStart], moonRadiusRadians], Circle[AstroPosition["Moon", eclipseMax], moonRadiusRadians], Circle[AstroPosition["Moon", eclipseEnd], moonRadiusRadians], Circle[AstroPosition["Moon", eclipsePartialEnd], moonRadiusRadians]}]
Out[15]=

PenumbraStyle (1) 

Change the style of the penumbra disk:

In[16]:=
ResourceFunction["LunarEclipseStarChart"][ LunarEclipse[DateObject[{2025, 3, 14}]], "PenumbraStyle" -> Directive[Black, EdgeForm[Orange], Opacity[.5]]]
Out[16]=

UmbraStyle (1) 

Change the style of the umbra disk:

In[17]:=
ResourceFunction["LunarEclipseStarChart"][ LunarEclipse[DateObject[{2025, 3, 14}]], "UmbraStyle" -> Directive[Blue, EdgeForm[Orange], Opacity[.5]]]
Out[17]=

ShadowEnlargmentFactor (1) 

Due to unpredictable atmospheric effects, a scaling factor is applied to the apparent radius of the Earth's shadow:

In[18]:=
ResourceFunction["LunarEclipseStarChart"][ LunarEclipse[DateObject[{2025, 3, 14}], "PartialPhaseStartDate", TimeZone -> "GMT"], "ShadowEnlargementFactor" -> #] & /@ {.9, .998340, 1.2}
Out[18]=

Possible Issues (2) 

LunarEclipse timings are not as precise as SolarEclipse so contact points may not be exact:

In[19]:=
ResourceFunction["LunarEclipseStarChart"][ LunarEclipse[DateObject[{2025, 3, 14}], "PartialPhaseStartDate", TimeZone -> "GMT"]]
Out[19]=

Manually putting in the expected time (as found at https://www.timeanddate.com/eclipse/lunar/2025-march-14) provides better results:

In[20]:=
ResourceFunction["LunarEclipseStarChart"][ DateObject[{2025, 3, 14, 0, 9, 40}, TimeZone -> "America/Chicago"]]
Out[20]=

Requirements

Wolfram Language 14.0 (January 2024) or above

Version History

  • 1.0.0 – 11 March 2025

License Information