Ephemeris - PHD2 Log Viewer

ih-FEM-uh-riss: read last night's PHD2 guide log, then see what your rig has done all season

Ephemeris is a Mac-native viewer for PHD2 guide logs, the text files PHD2 writes during every autoguiding session. The name comes from astronomy: an ephemeris, from the Greek for "daily," is a table of celestial positions recorded over time. That's what a single guide log is, frame by frame, all night. It's also what a season of them becomes.

Open one log and Ephemeris charts RA and Dec error, plots your calibration cross, and runs FFT analysis to find periodic error. Import a folder of them and it builds a library, organized per rig, with trends that only exist across nights. It reads that history against your actual imaging scale and tells you what it notices, and it always says whether an observation comes from PHD2's own documentation or from Ephemeris itself.

Free, GPLv3, written in Swift and SwiftUI, and a Mac-native re-implementation of Andy Galasso's phdlogview, the canonical PHD2 log viewer, written and maintained by the same engineer who maintains PHD2 itself. I built it because Rosetta is going away and the Mac side of this hobby is thin. A good native tool felt like a worthwhile thing to contribute. The larger goal was always v2: give the app enough understanding of your rig to point at what your guiding is actually doing and suggest what to try next, so guiding stops feeling like a black box you poke at between clear nights.

If you image for more than an hour or two, you don't have one guide log per night — you have fifteen. Meridian flips, dither pauses, settling resets, the time PHD2 lost the star and you didn't notice for ten minutes. Ephemeris reads the whole file at once and gives you every guiding and calibration section in chronological order, with RMS RA, RMS Dec, total RMS, and a quality bar that tells you instantly which sessions held up and which fell apart. The night's best session gets a green ★ chip. The worst gets an orange ⚠︎. Click into either to see exactly why.

Drag horizontally on the chart to zoom into a spike. Switch the toolbar mode and drag to exclude a range instead — frames you know were bad (clouds, dew, a stray cable tug) drop out of the stats and the numbers recompute live. Settling bands appear as faint orange when settling failed and neutral grey when it succeeded — useful for telling apart "PHD2 lost the star and recovered" from "the dither went sideways and the next 30 frames were trash." Star mass and SNR are graphed beneath the main chart, both synced to the same hover position so you can answer the most common diagnostic question — was the star getting fainter, or was the seeing falling apart? — at a glance. Toggle pixels vs arc-seconds. Toggle RA/Dec vs raw dx/dy. The Y-axis snaps to ±0.5″, ±1″, ±2″, ±5″, ±10″, or auto.

A clean calibration cross looks like a T. West and East run along one axis in red, North and South run perpendicular in blue, and Backlash steps trail off in orange before the Dec leg starts. Ephemeris draws yours with a 1:1 aspect ratio, dashed concentric reference rings, and tells you the orthogonality error in degrees — the angular distance between the West and North legs minus 90°. Anything past 5° gets flagged in orange. Below 1° is what you want on a well-aligned mount with measured (not assumed) orthogonal axes. The header strip pulls out the RA rate, Dec rate, exposure, calibration step, calibration distance, declination, hour angle, and pier side — every value PHD2 used to build the calibration, surfaced in one row instead of buried in the log header.

The FFT periodogram is the answer to "what's that periodic spike in my guiding?" Open the modal with ⌘F, pick RA or Dec, and Ephemeris runs a Hann-windowed real FFT on the included frames using Apple's Accelerate framework — the math runs in milliseconds even on a 30,000-frame combined session. The dominant period gets called out at the bottom. On a typical EQ-class mount that period is almost always the worm gear: an SkyWatcher EQ6 lands around 478 seconds, an HEQ5 around 638 seconds, a CGEM around 1436 seconds. On a high-end direct-drive or absolute-encoder mount, the dominant period is much harder to find because there isn't a worm. Drift correction is on by default (otherwise low-frequency drift swamps everything). Toggle it off to see what the raw signal looks like.

One night tells you about one night. The interesting questions are the ones a single log can't answer: is this getting better, was that a bad night or a bad setup, has anything changed since I re-tightened the OAG.

Point Ephemeris at a folder and it imports the lot, deduplicating as it goes, so re-importing the same directory next month adds the new nights and skips the ones it already has. Everything lands under a rig profile: focal length, pixel size, binning, reducer, mount class. The rig is what makes the numbers mean something. At 2800mm with a 0.7x reducer onto 3.76 micron pixels, the imaging scale is 0.40 arcseconds per pixel, and a 0.6″ night reads very differently at that scale than it does at 3″/px.

From there you get the things that only exist across nights: median, p75 and p90 RMS rather than a single number, total integration, and target clusters built by grouping sessions that point at the same patch of sky, so you can compare how the same object guided in February and April.

Ephemeris runs 23 analysis rules over your library, 19 within a single night and 4 across nights, and writes what it notices in plain language. Each one is labelled with where the claim comes from, and this is the part that matters most.

Observations point at PHD2's own tools by name, because those tools are where the fix happens: the Calibration Assistant for orthogonality and Dec backlash, the Guiding Assistant for min-move and backlash measurement, Drift Align for polar alignment. Ephemeris reads logs after the fact. PHD2 is the thing holding the star.

What it deliberately won't do is claim causation. A pier-side RMS ratio of 2.2x is a fact about your night. "Your east side calibration is stale" is a hypothesis, and it gets written as one. I guided for weeks through a bent off-axis guider before I worked out what it was, and no log analysis would have found that, because the logs looked like bad seeing. A tool that told me confidently what was wrong would have told me the wrong thing.

I'd have a night that went sideways, no idea why, and I'd copy chunks of the guide log into a chat window and argue about it. It worked better than it had any right to. So I built the app a way to hand over structured data instead of me pasting text.

Turn on the MCP server in Settings and Claude Desktop, running on the same Mac, can query your library directly: rigs, nights, sessions, targets, observations, Guiding Assistant results, aggregate statistics. You ask questions in English. It reads real numbers rather than guessing.