Ephemeris
PHD2 guide log analysis for Mac, free and open source
Last night, explained.
Your stars came out egg-shaped and you don't know why. The answer is in the log PHD2 wrote while you slept. Ephemeris reads it, shows you exactly where guiding went wrong, and tells you what to check before tonight.
The whole night
Which session went wrong?
A night of imaging is a dozen guide sessions. Ephemeris lays them all out with RA, Dec and total RMS, marks the best and the worst, and lets you jump straight to either. Shift-click sessions to graph several together.
The summary: every session's RMS side by side, with the night's best and worst called out.
Shift-click sessions in the sidebar to add them to the graph, and see them as one chart with the real gaps between them kept.
The guide chart
Find the moment it fell apart.
Every frame of guiding as a line graph of RA and Dec, with a scatter plot of where the star wandered, the corrections PHD2 sent, dithers and settling, and the guide star's brightness and signal underneath. Hover any point to read it, click to pin it.
- Zoom or exclude. Drag across a stretch to zoom in, or to leave a gust or a cable snag out of the statistics.
- In your units. Switch between pixels and arcseconds, and lock the scale from ±0.5″ to ±10″.
- The numbers that matter. RMS, peak and drift for RA and Dec, and a polar alignment estimate from the drift.
Observations
It tells you what it noticed, and how it knows.
Ephemeris checks each night against 25 rules, 21 within the night and 4 across your nights. Every observation shows its evidence and says where it comes from, so you know how much weight to give it. It points you to what to check; it doesn't pretend to know the cause for certain.
Stars predicted: trailed (Dec drift)
- Dec drifted steadily one way all session
- Corrections couldn't keep up
Check polar alignment and Dec backlash.
Calibration is 34 days old
- Last calibration in the log was over a month ago
- Equipment or balance may have changed since
Try a fresh calibration near the celestial equator.
Calibration orthogonality error
- RA and Dec axes measured more than 10° from square
- PHD2's own sanity check flagged it
Check the calibration cross and recalibrate.
Dec min-move likely too low, chasing seeing
- Many tiny Dec corrections that reverse each frame
- RMS no better for the effort
Try raising Dec minimum move a little.
Settling failed on 3 of 12 attempts
- Guiding didn't settle within tolerance after dithers
- Subs after those dithers may be soft
Try a longer settle time or a smaller dither.
Guide exposure likely too long for a strain-wave mount
- Long guide exposures on a mount that needs frequent corrections
Try shorter guide exposures.
Example observations above, simplified. In the app each one shows its full evidence and links to the relevant part of the PHD2 manual.
Your mount
Is it the calibration, or the gears?
Two views get to the bottom of problems that aren't about last night's weather: the calibration PHD2 measured, and the periodic error hiding in your mount's worm gear.
A good calibration looks like a T.
See the calibration cross PHD2 recorded, with the rate and angle of each leg and how far from square the axes are. Ephemeris flags an orthogonality error of 5° as worth a look and 10° as a problem, quotes PHD2's own calibration warnings, and tells you when a calibration has gone stale.
The spike that repeats is your worm gear.
A frequency analysis of RA or Dec turns a noisy chart into peaks, so a problem that repeats every few minutes stands out. Ephemeris names the dominant period when it clearly stands out, corrects for drift first, and suggests what to try, including PHD2's Predictive PEC.
The Log Library
What has your rig been doing all season?
One bad night is noise. A slow slide over a month is a clue. Ephemeris keeps every log you open in a library, organized by rig, and charts each night against that rig's own imaging scale.
Fifty-six nights on one rig, plotted against its own imaging scale. The spike at the end of February turned out to be a bent off-axis guider. The library made that night findable.
Eighteen nights, 151 sessions and 53.8 hours on one rig. The dashed line is the rig's own imaging scale.
It knows your rigs
Logs are sorted by the equipment profile PHD2 writes into them, even after you rename one. Import a whole folder at once; duplicates are skipped.
Judged against your optics
Give a rig its focal length and pixel size, and each night is marked sub-pixel, at resolution or over resolution for your imaging scale.
Housekeeping, at a glance
Days since your last calibration, Guiding Assistant run and polar alignment. Add notes, and rate how your stars came out.
Ask your own logs
Talk to a season of guiding.
Ephemeris started with pasting log files into Claude by hand. Now you can turn on a small server that lets an AI assistant read your library's summaries and answer questions about your nights.
- Off until you turn it on. Nothing runs unless you enable it in Settings.
- Read-only, on your Mac. It listens only on your own computer, protected by a token, and can't change anything.
- Summaries, not raw logs. Your assistant sees rigs, nights, statistics and observations.
- One-click setup. For Claude Desktop and Claude Code. ChatGPT connectors work through a secure tunnel you set up yourself.
list_rigslist_nightslist_observationsget_aggregate_statsget_corpus_summarysearchfetchIllustration of a conversation, with the server's seven read-only tools.
Built for the Mac
A native rewrite of a classic.
Ephemeris is a re-imagining of Andy Galasso's phdlogview, rebuilt from scratch in Swift for today's Macs.
Share it on the forums
Build a forum post of a session's statistics in Markdown or BBCode, ready for Cloudy Nights or the PHD2 group, or export the chart as a PNG and the numbers as CSV.
Universal
Native on Apple Silicon and Intel Macs.
Swift Charts and Accelerate
Fast charts and frequency analysis, even on long logs.
Updates built in
Sparkle checks for new versions, with your permission.
Signed and sandboxed
Developer ID signed, notarized by Apple, and sandboxed.
Shortcuts
Open your most recent log or show recent trends from a shortcut.
Help, built in
A searchable Help Book that explains every chart and number.
Free, and it stays that way.
Ephemeris is open source under the GPLv3, because guiding help shouldn't sit behind a paywall and phdlogview showed what a free tool can do for the community. If it saves you a night, you can support its development.
Free, GPLv3. macOS 15 Sequoia or later. Downloaded from GitHub, not the Mac App Store.
Questions, answered.
What does total RMS tell me about my guiding?
It's the combined size of your guiding errors in RA and Dec over a session. Lower is better, but what counts as good depends on your imaging scale: an error well under the size of one camera pixel won't show in your stars.
What's a good total RMS for my setup?
Compare it with your imaging scale in arcseconds per pixel. Guiding at half your imaging scale or better is excellent; around your imaging scale is usually fine. Ephemeris marks each night against the scale you give your rig.
Is my drift polar alignment or mount tracking?
Steady drift in Dec usually points to polar alignment, and Ephemeris estimates how far off you are from it. Drift or wobble that repeats in RA is more often the mount's gears; the frequency analysis shows whether it repeats.
Why does calibration orthogonality matter?
PHD2 needs to know which way each axis moves the star. If the measured axes are far from square, corrections go partly the wrong way. Ephemeris flags 5° as worth a look and 10° as a problem.
What does the frequency analysis show that the chart doesn't?
It turns a noisy chart into peaks, so an error that repeats every few minutes, typically from a worm gear, stands out even when the chart just looks messy.
Which logs can it read?
PHD2 guide logs, from Mac or Windows, including setups with adaptive optics. PHD2 debug logs and other guiding software's logs aren't supported.
How is it different from phdlogview?
Ephemeris is a native rewrite inspired by phdlogview, and adds a library of every night, observations with their sources, rig profiles and the option to ask an AI assistant about your logs. phdlogview remains a great tool.
Does it send my logs anywhere?
No. Everything stays on your Mac. The optional assistant server is off by default and only listens on your own computer.
Why is it free and GPLv3?
Because guiding help belongs to the community, as phdlogview did. The GPLv3 keeps Ephemeris and anything built from it open.
Does supporting on Patreon get me anything extra?
No. Every feature is free for everyone. Support simply helps keep Ephemeris, and the rest of Mac Observatory's tools, going.