Coordinax Astro Specification

Coordinax Astro Specification#

This document is the normative specification for the mathematical and software design of coordinax.astro. The goals are:

  1. Correctness-first foundation: rigorous definitions of points, tangents, their transformations, etc.

  2. Ergonomic high-level API: common tasks should not expose low-level details.

  3. Extensibility via multiple dispatch: functional API for existing functions are added by registration, not by editing core logic.

  4. JAX compatibility: dispatch resolves on static Python objects; numerical kernels are pure and traceable.

Table of Contents#

The Math#

Distance Moduli#

The distance modulus \(\mu\) is a logarithmic measure of distance used in astronomy. It relates a celestial object’s apparent magnitude \(m\) and absolute magnitude \(M\):

\[ \mu \;=\; m - M. \]

Given a physical distance \(d\) (in parsecs) the distance modulus is

\[ \mu \;=\; 5\,\log_{10}\!\bigl(d/\text{pc}\bigr) - 5, \]

or equivalently

\[ \mu \;=\; 5\,\log_{10}\!\bigl(d/10\,\text{pc}\bigr). \]

Inverting the relation gives the distance in parsecs:

\[ d \;=\; 10^{\,1 + \mu/5}\;\text{pc}. \]

\(\mu\) is expressed in magnitudes (mag), a dimensionless logarithmic unit. All constructors and conversions in coordinax.astro enforce this unit constraint.

Parallaxes#

Trigonometric parallax \(p\) is the apparent angular shift of a source caused by the observer’s orbital motion. It provides a direct, geometric measurement of distance.

Let \(b\) denote the baseline length (conventionally \(b = 1\,\text{AU}\), the Earth–Sun distance). For a source at distance \(d\), the parallax angle \(p\) is defined by

\[ \tan p \;=\; \frac{b}{d}. \]

Because astronomical parallaxes are small (\(p \ll 1\)), the small-angle approximation \(\tan p \approx p\) is often used, but coordinax.astro retains the exact \(\tan\) form.

Inverting the definition:

\[ d \;=\; \frac{b}{\tan p} \;=\; \frac{1\,\text{AU}}{\tan p}. \]

The result carries length units; the implementation preserves the natural unit of the quotient (AU) and lets the caller convert.

Given a distance \(d\) in parsecs:

\[ p \;=\; \arctan\!\Bigl(\frac{1\,\text{AU}}{d}\Bigr). \]

By definition of the parsec, a source at \(d = 1\,\text{pc}\) has a parallax of \(1''\) (one arcsecond).

Combining with the distance-modulus formula:

\[ \mu \;=\; 5\,\log_{10}\!\Bigl(\frac{1\,\text{AU}}{\tan(p)\;\text{pc}}\Bigr) - 5. \]

  • \(p\) must have angular dimensions.

  • \(p\) must be non-negative (negative parallax is unphysical); this is checked at construction time by default.

  • The baseline length \(b = 1\,\text{AU}\) is a module-level constant (parallax_base_length).

Packages#

coordinax.astro#

!!! info DistanceModulus

Magnitude-space distance representation used in astronomical workflows and conversions.

!!! info Parallax

Angular distance proxy represented in angular units and linked to distance conversion flows.

coordinax.hypothesis.astro#

!!! info distance_moduli

`hypothesis` strategy for generating `coordinax.astro.DistanceModulus` instances.

!!! info parallaxes

`hypothesis` strategy for generating `coordinax.astro.Parallax` instances.