Computing the Eclipse: Astronomy in the Wolfram Language

See also:
“When Exactly Will the Eclipse Happen? A Multimillennium Tale of Computation” »

When Exactly Will the Eclipse Happen? A Multimillennium Tale of Computation

Computing the Eclipse: Astronomy in the Wolfram Language

Basic Eclipse Computation

It’s taken millennia to get to the point where it’s possible to accurately compute eclipses. But now—as a tiny part of making “everything in the world” computable—computation about eclipses is just a built-in feature of the Wolfram Language.

The core function is SolarEclipse. By default, SolarEclipse tells us the time of the next solar eclipse from now:

It can also tell us the next solar eclipse from any time more than 10,000 years in the past and future:

By default, SolarEclipse tells us about all solar eclipses, including partial ones. But we can request only total eclipses (or annular ones, etc.):

SolarEclipse immediately lets you compute nearly 100 properties of an eclipse. The most basic property is the type of eclipse; this tells us that the next eclipse from now will be total:

And here are the types of all eclipses for the rest of the decade:

This gives a timeline of these eclipses; notice that most eclipses are separated by 5 or 6 months, but there’s one pair (in 2029) that is just a month apart:

Another basic property of an eclipse is its magnitude: how much of the diameter of the disk of the Sun is covered by the Moon. The next eclipse is total, so the magnitude is greater than 1:

Looking at the sequence of eclipses for the remainder of the decade, we see which ones are total and which are not:

Here’s the path of totality for the upcoming total eclipse:

And here’s where the eclipse is partial:

This is easier to understand with a different geo projection:

There are all sorts of special points and lines associated with these regions. This gives the “point of maximum eclipse” (i.e. essentially the place where the eclipse lasts longest):

And this gives the precise time (converted to my current time zone) of the maximum eclipse:

This gives the time of maximum eclipse in the time zone of the point of maximum eclipse:

At the point of maximum eclipse, this gives the duration of the umbra (i.e. the time of totality):

And here’s a map of where on the Earth the umbra is at the time of maximum eclipse:

Zooming out to a range of 500 miles makes it easier to tell where this is:

This shows the position of the umbra every minute for the hour after the time of maximum eclipse:

Here’s a summary map of the eclipse, including for example (in red) the points of first and last contact of the penumbra:

Instead of looking at what amounts to the shadow of the Moon on the Earth, we can ask what we’d see in the sky. During a total eclipse the Moon will completely cover the Sun. But here’s what happens just 15 minutes before the time of maximum eclipse:

Patterns of Eclipses

Here’s a map of the path of totality for all the total eclipses for the next 50 years:

Over the course of 500 years there are lots of total eclipses:

Although it’s not terribly obvious there, there’s actually a lot of regularity in these paths. In particular, as we discussed previously, similar eclipses occur in “saros series”, separated by a time of about 1 saros, or roughly 18 years. Here are the paths of eclipses that appear for the 10 saroses after the next eclipse:

Each successive eclipse in the saros series is systematically about 120° to the west of the previous one, and a little south (or north, depending on the series). The series continues like this until the eclipse paths hit one of the poles, at which point the series ends:

Any given eclipse is in a saros series. The next eclipse is in series 139 (the numbering scheme for these series was set in 1955—with series 0 chosen, quite arbitrarily, to be the one that starts just after 3000 BC):

There are 71 eclipses in this saros series

running from the year 1501 to the year 2763 (a span of 1263 years):

Not all these eclipses are total, however. But if we plot the magnitudes of all the eclipses, we see that the partial ones appear only at the ends of the saros series:

If we look at the next few eclipses, we’ll see that they are part of all sorts of different saros series:

Here are dates for eclipses in a sequence of different saros series:

Right now there are 40 saros series active:

Any given eclipse could be specified by its “index number” within its saros series. But in the mid-20th century it was realized that there’s a more convenient and robust way to label eclipses, using a combination of “saros number” and what’s called “inex number”.

As we discussed previously, for an eclipse to occur, a new moon must happen at a time when the Moon is close to the plane of the ecliptic. The average time between new moons is the so-called synodic month:

Meanwhile, the average time between the Moon’s crossings of the plane of the ecliptic is half the so-called draconic month:

Given a particular eclipse, the time before an approximate “repeat eclipse” will correspond to a coincidence between an integer multiple of the synodic month, and of half the draconic month. And to figure out when these coincidences will occur is essentially a question of number theory.

Let’s compute the continued fraction expansion:

From this we can derive a sequence of rational approximations:

These approximations get progressively better:

The 8th one is 484/223—and this corresponds to the saros cycle, which reflects the close similarity of 223 synodic months and 242 draconic months:

But now let’s look at the 9th rational approximation: 777/358. This reflects the coincidence:

And now this coincidence defines another cycle—which is the inex cycle. There are lots of other cycles one can identify—but all the common ones can be expressed as linear combinations of the saros and inex cycles.

We saw above how eclipses occur in saros series. But we now see that they will also occur in inex series. And a convenient way to specify an eclipse is to say what saros series and what inex series it appears in. The saros and inex series are numbered according to when they started, with the 0th saros series by convention being the one that spans:

With this setup, the April 2024 eclipse can then be specified by its saros and inex numbers:

But how does this fit in with other eclipses? Here’s a plot of the inex and saros numbers of all eclipses between 1000 AD and 3000 AD (with the April 2024 eclipse indicated in red):

Each saros series shows up as a vertical line of eclipses, and each inex series as a horizontal line. The finite overall date range for the picture leads to the diagonal cutoffs on each side.

For each saros, inex number pair there’ll be some kind of eclipse. But most of the eclipses won’t be total. Here’s where total eclipses occur in the saros, inex plane:

And here’s a complete color-coded “panorama” of different kinds of eclipses:

(Note that—as we discussed above—the eclipses at the ends of saros series are partial.)

By the way, when we’re discussing eclipses in the future, there’s a subtlety to mention. By computing the overall motion of the Earth and Moon we can work out when there’ll be an eclipse, and where in space the cone of shadow associated with it will be. But it’s a different question where geographically that shadow will land on the Earth because that depends on the rotation of the Earth—which isn’t precisely predictable, as illustrated by the somewhat haphazard way in which leap seconds have had to be added to align “universal” UTC time with time based on the rotation of the Earth and the length of a day. Is it a large effect? Over the past 500 years the discrepancy has been about 176 seconds; over the next 500 years it could easily be as much as 1000 seconds. Meanwhile, for an eclipse on the equator each second corresponds to a change of 0.29 miles in where the eclipse will be total (the change is less farther from the equator). In what we’ve shown here we’ve made some standard assumptions about how the rotation of the Earth is slowing down—but ultimately this isn’t predictable, making the locations of eclipses 500 years from now uncertain in the east-west direction by as much as several hundred miles.

The Eclipse from First Principles

The function SolarEclipse in the Wolfram Language immediately tells us when eclipses occur. But we can also deduce this information from other “lower-level” functions. In particular, we know that an eclipse (of at least some kind) occurs if the angular separation between the Sun and the Moon in the sky is smaller than the total of their apparent radii (or about 0.5°). The angular separation depends on where you are on the Earth. Let’s pick a location from which we know an eclipse will be visible:

Now let’s plot angular separation for each hour over the course of the next year:

The minima occur once per lunar month, near the time of the new moons. Changing the plot range, we can see that these minima are different in different (lunar) months:

Let’s look at early April in more detail, now sampling every minute:

And what we see here is that the angular separation goes to zero—reflecting the fact that there’s a total eclipse. What are those little glitches? They’re a consequence of the fact that the apparent positions of the Sun and Moon change when they’re close to the horizon because of refraction in the atmosphere. Not including refraction gives a smoother curve:

We’ve been looking at the angular separation between the centers of the disks of the Sun and Moon in the sky. But what about the actual positions in the sky? Here’s the astro position of the Sun (in local horizon coordinates) at the time and place of maximum eclipse:

And here now is the almost-exactly-equal result for the Moon:

What will it actually look like in the sky? Here’s now a graphic showing the disks of the Sun and Moon 15 minutes before the time of maximum eclipse:

Here’s a sequence of images 15 minutes apart:

Analyzing Data from the 2017 Eclipse

I saw the 2017 eclipse from a rather scenic spot near Jackson, Wyoming:

Click to enlarge

Specifically (according to Wolfram|Alpha accessed through my phone) I was at geo position 43.5125°N 110.6506°W—at an elevation of 7526 ft:

Click to enlarge

As a check, here’s the expected (ground) elevation at that lat-lon—definitely within bounds, particularly considering I was holding the phone about 5 feet off the ground, etc.:

Defining my location as

the predicted arrival time of the eclipse at that location was then:

And indeed that’s exactly what our precisioneclipse.com site told me at the time:

Click to enlarge

What would happen at the “moment of totality”? Here’s where the shadow of the Moon was predicted to be (where I was standing is indicated by a red dot; the whole picture is 100 miles across):

Fifteen seconds earlier, the shadow of the Moon would have just “crossed” the row of mountains I could see:

Looking (in exaggerated 3D) at the terrain, here’s the “umbral cone” at the moment of totality for me:

And it was moving at a speed

which is effectively a vector difference of the rotation speed of the Earth

corrected for latitude

and the orbital velocity of the Moon:

Shown at 5-second intervals for 30 seconds, here’s how the edge of the umbra was moving just before it reached me:

That day, I had brought some not-very-high-tech “equipment” to record the eclipse:

Click to enlarge

The main video I captured—which was from the iPad—is now stored for posterity in the Wolfram Data Repository:

It was 11 minutes long. Sampling frames from it we get:

To get more of a sense of the eclipse, we can pick out the center column of the video, and arrange it in time:

Notice that the “band of totality” appears slightly further to the left at the top of the image—reflecting the fact that totality reaches the mountains in the distance (at the top of the image) slightly earlier than it reaches the “foreground” at the bottom of the image.

To be more quantitative, we can measure the mean intensity of the bottom part of the image as a function of time (where here we’ve aligned with the timestamp that records the start time of the video):

We see in this “light curve” a big dip during the period of totality. There’s also a little dip earlier from someone walking in front of the camera. And we also see lots of little glitches that we’ll discuss later.

But what should we expect this light curve to look like? Well, we can predict what the obscuration of the Sun around the time of totality should be—and but for the 20% effect of “limb darkening”, this should give the intensity of sunlight:

Rescaling values somewhat, we can compare the curves:

And zooming in on the minute around the beginning of totality, we see:

And, yes indeed, the observed onset of totality seems to agree basically to the second with our prediction!

But even though there’s this agreement, the overall shapes of the observed and predicted light curves definitely aren’t the same. And, yes, this is a story of experimental science. And, arguably, of a mistake I made—of using consumer electronics, optimized for consumer purposes, to make a quantitative scientific measurement. You see, as I now realize, an iPad by default always tries to “get a good picture” by maintaining the brightness of an image independent of overall light level. And while for “consumer purposes” that’s usually the right thing to do, it definitely confuses things if one’s trying to measure the light curve for an eclipse.

And indeed if we look at our “measured light curve” it’s very flat until the period of totality. In other words, the iPad succeeded in maintaining the same image brightness until there just wasn’t enough light at all, at which point the image “faded to black”. (At the end of totality, the iPad gradually realized “yes, there’s more light now”, and the measured light curve slowly climbs back up.)

But what’s with all the glitches we see? They’re already visible in our “video time collage” above. And one thought might be that they’re an actual eclipse phenomenon—perhaps associated with the “shadow bands” that I did indeed see just before this eclipse. But the characteristic shimmering associated with such shadow bands—while very difficult to capture on video, perhaps because actual images aren’t being formed—happens much faster than the glitches we’re seeing.

Looking in a bit more detail, we see that there are upward glitches in the period before totality, and downward ones after. Zooming in on a couple of minutes of the “before” period and a couple of minutes of the “after” period, we see:

And, yes, we can validate that this is an “instrumental phenomenon” by doing a simple experiment—using the very same iPad as in 2017—and continuously sliding a piece of cardboard in front of a light and then capturing video and measuring the light curve for this in-my-basement-style “model eclipse”:

We see the very same kind of glitches as from the actual eclipse video. And presumably in both cases they’re reflections of the automatic exposure control system used by the iPad. (If the individual frames of the video had EXIF metadata, we might be able to see that explicitly, but as it is, there’s only EXIF data for the whole video.) I don’t know in detail how this iPad’s exposure control system works, but what we’re seeing is a kind of overshooting-and-correction that’s very common in all sorts of control systems. If we knew in advance everything that happens in the video, then maybe we could avoid the glitches. But if we’re going to try to maintain light level on an ongoing basis during the recording of the video (perhaps by adjusting the gamma correction that determines how raw sensor values are translated to pixel values), then control theory most likely implies that glitches are inevitable.

My First Eclipse

So many years later, I still remember it well. I was 6 years old (almost 7), walking the couple of blocks to school (yes, on my own, which kids in England in those days did). It happened when I was walking under a tree (and, yes, I still remember exactly where). There were lots of dappled patches of light on the ground. And something looked strange about them. And suddenly I realized what it was—and I still have an image of it in my mind today. All the patches of light had the same bite taken out of them. And it didn’t take me long to look up at the Sun, and see that it too had a bite taken out of it.

Being already something of a science enthusiast, I’d heard of eclipses, and realized this must be one. I arrived at school a few minutes later, and regaled the other kids with my “discovery”. But despite the obviousness (at least to me) of what was going on, I wasn’t widely believed. And, yes, that was a very educational experience. But that’s a different story

So what was that eclipse? Well, it was the one in May 1966:

It was a partial eclipse—visible from England:

The geo location of my “discovery tree” was 51.7636° N 1.2558° W. So now we can compute the magnitude of the eclipse there that morning:

I believe school started at 9am, so what I saw was an eclipse with rough magnitude:

The Sun (and Moon) were about 50° above the horizon:

And the Moon was poking into the disk of the Sun:

Thirty minutes later the Moon had poked a little further into the disk of the Sun. But after a bit more than a hour, the whole Sun was back, and the eclipse was over:

And it would be 25 years before I’d see another eclipse—though this time a total one.

By the way, this is me back at the time of my first eclipse—captured in a long-before-those-were-popular “selfie”, taken with a film camera and manual focus, and, it seems, a lot of concentration (and, yes, I think I still make the same strange expression when I’m concentrating hard today):

Click to enlarge

Stephen Wolfram (2024), "Computing the Eclipse: Astronomy in the Wolfram Language," Stephen Wolfram Writings. writings.stephenwolfram.com/2024/03/computing-the-eclipse-astronomy-in-the-wolfram-language.
Stephen Wolfram (2024), "Computing the Eclipse: Astronomy in the Wolfram Language," Stephen Wolfram Writings. writings.stephenwolfram.com/2024/03/computing-the-eclipse-astronomy-in-the-wolfram-language.
Wolfram, Stephen. "Computing the Eclipse: Astronomy in the Wolfram Language." Stephen Wolfram Writings. March 29, 2024. writings.stephenwolfram.com/2024/03/computing-the-eclipse-astronomy-in-the-wolfram-language.
Wolfram, S. (2024, March 29). Computing the eclipse: Astronomy in the Wolfram Language. Stephen Wolfram Writings. writings.stephenwolfram.com/2024/03/computing-the-eclipse-astronomy-in-the-wolfram-language.

Posted in: Computational Thinking, Physics


  1. Fantástisco.

  2. wow, thanks for the amazing work.

  3. It’s amazing how concise Wolfram Language is.
    Great article!