FlyStar

FlyStar aligns many star lists into one common frame and fits each star’s motion there, choosing per star from a set of motion models.

That one sentence is the whole package: align the stars, then describe how they move. The rest of this page unpacks it.

Astrometry of a crowded field is never taken in one frame. You have many images – different nights, different instruments, different pointings, each with its own distortion and its own arbitrary pixel coordinate system. Every one of them tells you about the same stars, but none of them agrees with the others about where those stars are.

FlyStar’s job is to make them agree. It cross-matches the stars across all those lists, solves for the coordinate transformation that carries each list into one common reference frame, and then – with every epoch on the same footing – fits each star’s motion through time. What comes out is a single table of positions, proper motions, and where wanted parallaxes, with uncertainties that mean something.

That is the whole point of the package: turn many disagreeing star lists into one self-consistent astrometric solution.

Which version is this?

Built from the dev branch, and describes that branch’s API. The motion-model framework in Motion models does not exist on main. Every page here, the API reference included, is generated from this branch’s source.

How the pieces fit

Three objects, in the order you meet them:

Stage	Object	What it holds
1. One epoch	StarList	One detection list from one image. 1D columns, one row per star: x, y, m and their uncertainties.
2. Many epochs	StarTable	The cross-matched result. 2D columns of shape (N_stars, N_lists), so t['x'][i, j] is star i in list j.
3. The solution	MosaicSelfRef / MosaicToRef	The iterative match/transform/average loop that builds the StarTable and fits each star’s motion.

In one line: StarList → StarTable → align. You assemble star lists, hand them to an aligner, and read the answer off the StarTable it produces.

Where to go next

Installation

Installing FlyStar from the repository, and the optional extras.

First alignment

A complete alignment of synthetic star lists that runs as written, and the same call on your own lists.

StarList and StarTable

The two data objects in full – what lives in a StarList versus a StarTable, and the column-naming conventions the code dispatches on.

Motion models

The per-star motion models, their equations, how FlyStar picks one per star, and how the reported uncertainties are computed. Worth reading before the aligner, whose motion_models argument only makes sense once you know what it is choosing between.

Transformations

The coordinate transformation models, which to pick for a given kind of frame difference, and how to raise the order as the fit converges.

Alignment

The aligners in depth, parameter by parameter – matching strategies, the initial guess, and how to control which stars drive the fit.