Eclipse Calculator for your mobile phone

Introduction

Ever find yourself in a strange country, in the path of the moon's shadow, wondering if it's 2 minutes or 5 before the shadow reaches you? Afraid to bring that brand spanking new multi-gigahertz laptop you bought to this strange country even though it could give you the answer to that question?

This is the scenario I've found myself in three times now, and so I've come up with a solution - an eclipse calculator for your (java-enabled) mobile phone! It turns out that many mobile phones these days are programmable, and many of them have more computing horsepower than the first home computers.

This project started with an eclipse calculator for the Psion palmtop computer (that worked very well) in 1999. Unforutnately, my Psion died after the 2001 eclipse. In 2002, I was lucky enough to know the precise location of our observing site months before the eclipse, so I was able to do the calculation at home before I left. As it turned out, that precise location was clouded out!

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Putting the legalese to one side, it means that you may download and use the program, though I make no guarantee that the program will work as advertised (if it doesn't, though, please let me know). If you want to do anything other than that with the program, then you should read the license.

The source code for the program is here.

Installing the calculator on your phone

The installation procedure for installing the calculator on your phone is quite phone-specific. In general, however, if your phone is Internet-enabled (or WAP-enabled), and if it complies with the relevant standards (the Sharp GX-series, for instance, do not quite adhere to the standards - I will try and add support for those phones soon), and if it's Java-enabled (of course!), then all you should have to do is open up your phone's browser and point it to http://www.ecliptomaniacs.com/jad/eclipse.jad

On my Nokia 7250i, what I have to do is open up the menu, select Services, select Go to address and type in http://www.ecliptomaniacs.com/jad/eclipse.jad - the phone connects to the Internet and then asks me if it's OK to install the application. Your phone may need a different sequence of events.

If you have a way of connecting your phone to your computer (eg by cable, by infra-red or by bluetooth), and if you have software for your computer that allows you to install applications on your phone using the link, then you will probably find that your computer needs one or two files before it will install the application. You will definitely need the file http://www.ecliptomaniacs.com/jad/eclipse.jar, and you may also need the eclipse.jad file mentioned above. So, right-click on these links to the eclipse.jar and eclipse.jad files, choose "Save target as..." and try to use the software on your computer to install the application on your phone.

If you have a Palm device, you will probably first of all need to install the Java software for it (see http://java.sun.com/products/midp4palm/), then you should be able to install the file http://www.ecliptomaniacs.com/jad/eclipse.prc - let me know how you get on.

Upgrading from a previous version

There should be something on your phone which says something along the lines of "download latest version". On my Nokia 7250i, I go into the menu, and select Applications, Select Application, Eclipse, Update version. If that does not work, or if you cannot see how to do it on your phone, then delete the eclipse application and then follow the procedure above.

Using the calculator on your phone

The instructions for using the calculator on your phone are quite phone-specific. But the first thing that you have to do is to launch the program. On my Nokia 7250i, what I have to do is to select the menu, select Applications, Select application, Eclipse, and choose Open from the Options menu.

This brings you into the Setup screen. How you enter information into the program is also quite phone-specific. However, you should probably see some sort of menu attached to the soft keys on your phone. The menu will contain some or all of the following options -

Setup
Choose
C1
C2
Mid
C3
C4
Current
Time
Clocks
Next
Exit

All of the above options (except Exit) select a particular screen in the program. There may be other options there as well - on my Nokia 7250i, for instance, in the Setup screen, an entry called "Edit" can appear. This entry appears when I've selected a box into which I can enter information (eg latitude, longitude) for the program to use.

To close the calculator, you should choose the Exit option. On some phones (including my Nokia 7250i), pressing the "End Call" button also exits from the calculator.

The setup screen

The setup screen may look something like this on your phone. It contains boxes into which you can put information.

North (ddmmmmm) - this is the box that you use to enter your latitude. The number you enter is positive in the northern hemisphere (hence the title North), and you use degrees and decimal minutes as the format. For instance, if your latitude is 22° 27.942' S, you should enter -2227942 into this box. If your latitude is 18° 15' 45" S, you should enter -1815750 into this box (as 15' 45" = 15.750')
East (dddmmmmm) - this is the box that you use to enter your longitude. The number you enter is positive in the eastern hemisphere (hence the title East), and you use degrees and decimal minutes as the format. For instance, if your longitude is 30° 28.538' E, you should enter 3028538 into this box. If your longitude is 108° 25' 15" W, you should enter -10825250 into this box (as 25' 15" = 25.250')
Alt (m) - this is the box into which you should enter your altitude above sea level (in metres). If you are used to using feet, then multiply by 3 and divide by 10 to get metres. (Actually, technically speaking, you should enter your altitude above the ellipsoid - though this may change in a future version of the calculator.)
TZ (HHMM) - this is the box into which you should enter your time zone (including any correction for daylight savings time). You should enter a negative number for time zones that are behind Greenwich.
TZ Aware - most mobile phones do not know anything about time zones - most mobile phones assume you are constantly in GMT. If your mobile phone is an exception, then you need to choose "yes" here. How do you find out if it's an exception? Well, set up your time zone in the box above and go to the Time screen - if the time shown is incorrect by an amount equal to your time zone offset, then you may need to choose "yes" in this box.
Clock Delta - the clock on your mobile phone will probably not contain the exact time. In this box, you can apply a correction to that clock. To set a correction of -3m24.2s to your phone's clock, enter -3242 into this box.

The choose screen

The screen for choosing the eclipse you want to work with may look something like this on your phone. Note that this screen is only available from the setup screen. In this screen, you should simply choose whatever eclipse you are interested in. At present, the calculator supports eclipses from 1999 Feb 16 to 2024 Oct 02.

The event screen (C1, C2, Mid, C3, C4)

The event screen may look something like this on your phone.

Mid - this is the name of the event, and it gives the time (in the local time zone) of the event. The names of the events are -
- C1 - first contact (the start of the partial eclipse)
- C2 - second contact (the start of the total/annular eclipse)
- Mid - the middle of the eclipse
- C3 - third contact (the end of the total/annular eclipse)
- C4 - fourth contact (the end of the partial eclipse)
If the event does not exist (eg if there is no eclipse at the selected location), then "NO EVENT" will appear here
Clock - this is a countdown clock to the event (assuming that today is eclipse day)
Alt - this is the altitude of the sun above the horizon (in degrees) at the event. Note that the calculator will still display information about events that happen below the horizon, even though they are invisible.
Azi - this is the azimuth of the sun at the event (0 = due north, 90 = due east, 180 = due south, 270 = due west)
P - this is the position angle of the event measured eastward from the north point on the sun's disk
V - this is the apparent position angle of the event, measured anti-clockwise from the "top" of the sun's disk
Mag - this is the magnitude of the eclipse, and is only displayed on the Mid screen. The magnitude is the fraction of the sun's diameter covered by the moon at mid-eclipse
Cvg - this is the fraction of the area of the sun's disk covered by the moon at mid eclipse, and is only displayed on the Mid screen
M/S - this is the ratio of the apparent size of the moon's disk to that of the sun, and is only displayed on the Mid screen.
Umb - this is the fraction of the way from the limit of the total/annular eclipse to the centre line that the location is, and is only displayed if the location is in the zone of totality/annularity and only on the Mid screen.
LC (0.1s) - the lunar limb correction (see below), in tenths of a second, should be entered into this box. Note that this box will only appear on the C2 and C3 screens.

On Nokia and on MIDP2.0 compatible phones, the phone should beep at 60, 30, 15, 10, 5, 4, 3, 2 and 1 seconds before the event, and at the event itself.

The current situation screen

The current situation screen may look something like this on your phone.

Alt - this is the current altitude of the sun above the horizon (in degrees).
Azi - this is the current azimuth of the sun (0 = due north, 90 = due east, 180 = due south, 270 = due west)
P - this is the current position angle of the moon measured eastward from the north point on the sun's disk
V - this is the current apparent position angle of the moon, measured anti-clockwise from the "top" of the sun's disk
Mag - this is the current magnitude of the eclipse - the magnitude is the fraction of the sun's diameter covered by the moon
Cvg - this is the current fraction of the area of the sun's disk covered by the moon.
M/S - this is the current apparent ratio of the size of the moon's disk to that of the sun.

Note that the calculator always assumes that today is eclipse day. Also, on Nokia phones, the backlight should turn on when this screen is displayed and the coverage is greater than 99.5%

The time screen

The time screen may look something like this on your phone.

UTC - this is the current UTC (commonly known as GMT) that the program is using
Local - this is the time in your local time zone

The clocks screen

The clocks screen may look something like this on your phone. It contains countdown clocks to the events at your location (assuming that today is actually eclipse day). The events are

C1 - first contact (the start of the partial eclipse)
C2 - second contact (the start of the total/annular eclipse)
Mid - mid eclipse
C3 - third contact (the end of the total/annular eclipse)
C4 - fourth contact (the end of the partial eclipse)

The next screen

The next screen may look something like this on your phone. It contains a large countdown clock to the next event at your location (assuming that today is actually eclipse day). The events are

C1 - first contact (the start of the partial eclipse)
C2 - second contact (the start of the total/annular eclipse)
Mid - mid eclipse
C3 - third contact (the end of the total/annular eclipse)
C4 - fourth contact (the end of the partial eclipse)

On Nokia and on MIDP2.0 compatible phones, the phone should beep at 60, 30, 15, 10, 5, 4, 3, 2 and 1 seconds before the event, and at the event itself. Also, on Nokia phones, the backlight should turn on around mid eclipse if the eclipse is total (or near-total) when this screen is displayed.

Lunar Limb corrections

If you are within the track of totality/annularity, then the "C2" and "C3" screens will contain an option for entering the lunar limb correction.

The best source of such corrections are Fred Espenak's eclipse bulletins, available via the Sun-Earth connection eclipse homepage. For example, the bulletin for the eclipse of 2006 March 29 (NASA/TP-2004-212762) has the lunar limb corrections on page 67 - figure 20.

To use the diagram, go to the C2 or C3 screen, and find the contact angle P. Then, read off the limb correction to apply from the diagram, and enter it into the limb correction box on the screen. For example, suppose you are observing the eclipse of 2006 March 29 from near Jalu in Libya at the coordinates 29°02.548'N, 21°31.654'E, alt 38m. Enter 2902548 into the "North" box on the "Setup" screen, enter 2131654 into the "East" box on the "Setup" screen, and enter 38 into the "Alt" box. Then, choose the "C2" screen. The angle "P" for second contact is 6°. Reading the lunar limb correction diagram indicates that the correction is -0.8s. So, enter -8 into the "LC" box on the "C2" screen. Similarly, for "C3", the angle "P" is 264°. From the diagram, the correction is -4.8s. So, -48 should be entered into the "LC" box on the "C3" screen.

Credits

This program uses the dfp library by William Rossi, and it uses some polynomial approximations of trig functions from the Cephes Math Library by Stephen L. Moshier.

Future plans

I'm open to suggestions as to more screens to add to the program - for instance, I could have a screen with summary information about the eclipse, though most of that information (with the notable exception of the duration of totality/annularity) is on the Mid screen.

To increase the accuracy of the information displayed on the phone, I intend to

(Attempt to) correct for refraction
Add a facility where the phone gets a time check of the internet (where available - and you would be surprised where it is available!)
Correct for the difference between the Geoid and the Ellipsoid (using an approximation!)

Contacting the author

I can be contacted via the contact us page or via email c h r i s <at> o b y r n e <dot> c o m - please send me your criticisms and bug reports, or even just a note to say "Hi, it works on my phone!".