The local circumstances of a solar eclipse: how it is seen from a place on the Earth.
The Besselian elements (see Astro.Solar.Eclipse) describe the
Moon's shadow on the fundamental plane. An observer is put in the
same frame: at a moment, with the shadow axis at declination d and
local hour angle H = μ + λ for an east longitude λ, the observer
is at
ξ = ρ cos φ′ sin H,η = ρ sin φ′ cos d − ρ cos φ′ sin d cos H, andζ = ρ sin φ′ sin d + ρ cos φ′ cos d cos H,
where ρ sin φ′ and ρ cos φ′ are the observer's geocentric
coordinates, from the geodetic latitude φ, the Earth's flattening
and the height above the ellipsoid. ζ is the observer's height
above the plane, where the shadow cones have radii
L1 = l1 − ζ tan f1 and L2 = l2 − ζ tan f2, and the observer is
m = √((x − ξ)² + (y − η)²) from the axis.
The eclipse is seen where
m < L1, inside the penumbra.Maximum eclipse is the moment of least
m, found by golden section search.The contacts are the moments the observer crosses a cone: first and last contact where
m = L1, and second and third wherem = |L2|, inside the umbra (total,L2 < 0) or the antumbra (annular,L2 > 0). Each is found by bisection.The magnitude at maximum is the fraction of the Sun's diameter covered, measured along the line through the centres of the two disks,
(L1 − m) / (L1 + L2). It exceeds 1 inside the umbra. This is the local magnitude NASA and the USNO give; the magnitude of a central eclipse in the catalogues is the ratio of the Moon's apparent diameter to the Sun's on the central line instead.The obscuration is the fraction of the Sun's area covered: the Sun and the Moon are disks of radii
(L1 + L2) / 2and(L1 − L2) / 2on the plane,mapart, and the obscuration is the area they share over the Sun's.The Sun's altitude is that of the shadow axis,
sin h = sin d sin φ + cos d cos φ cos H, which differs from the Sun's direction by a few arc seconds. It is geometric: refraction, which lifts the Sun by about 34′ at the horizon, is not applied.
The elements are geocentric, so the geometry is the same whether or not the Sun is above the horizon. An eclipse is seen from a place if at some moment between first and last contact the Sun's upper limb is above the horizon, allowing for standard refraction, which is the condition for sunrise.
Because μ is the Greenwich hour angle at the moment, the observer's
longitude is used as it is. NASA's and the USNO's elements use an
ephemeris hour angle and correct the longitude by ΔT instead; the two
agree when they use the same ΔT.
Summary
Types
How a solar eclipse is seen from a place: only the penumbra passes over it, the antumbra does, or the umbra does.
The local circumstances of a solar eclipse. The contacts and maximum
eclipse are DateTime.t/0s, nil for the contacts the eclipse
does not have there; the Sun's altitudes are geometric, in degrees,
keyed by the contact.
Functions
Returns the local circumstances at a location of the solar eclipse whose greatest eclipse is at a moment.
Types
@type eclipse_type() :: :partial | :annular | :total
How a solar eclipse is seen from a place: only the penumbra passes over it, the antumbra does, or the umbra does.
@type t() :: %Astro.Solar.Eclipse.Local{ annular_begins: DateTime.t() | nil, annular_ends: DateTime.t() | nil, magnitude: float(), maximum: DateTime.t(), obscuration: float(), partial_begins: DateTime.t(), partial_ends: DateTime.t(), sun_altitudes: %{required(atom()) => float()}, total_begins: DateTime.t() | nil, total_ends: DateTime.t() | nil, type: eclipse_type() }
The local circumstances of a solar eclipse. The contacts and maximum
eclipse are DateTime.t/0s, nil for the contacts the eclipse
does not have there; the Sun's altitudes are geometric, in degrees,
keyed by the contact.
Functions
@spec circumstances(Astro.Time.moment(), Geo.PointZ.t()) :: {:ok, map()} | {:error, :not_visible}
Returns the local circumstances at a location of the solar eclipse whose greatest eclipse is at a moment.
Arguments
greatestis theAstro.Time.moment/0of greatest eclipse, asAstro.Solar.Eclipse.eclipse_at_or_after/1returns it.locationis aGeo.PointZ.t/0, its altitude in metres above the ellipsoid.
Returns
{:ok, circumstances}, a map with the keys oft/0, the contacts and maximum as moments.{:error, :not_visible}if the location is outside the penumbra throughout, or the Sun is below the horizon from first contact to last.
Examples
Dallas saw totality on 8 April 2024:
iex> {:ok, eclipse} = Astro.Solar.Eclipse.eclipse_at_or_after(739_300.0)
iex> dallas = %Geo.PointZ{coordinates: {-96.80, 32.78, 0.0}}
iex> {:ok, local} = Astro.Solar.Eclipse.Local.circumstances(eclipse.greatest, dallas)
iex> {local.type, Float.round(local.magnitude, 3)}
{:total, 1.015}