Skip to main content

so_pointjax

Differentiable telescope pointing in JAX. A pure-Python, GPU-ready reimplementation of the ERFA/qpoint/so3g pointing stack, fully compatible with jax.jit, jax.grad, and jax.vmap.

Architecture

so_pointjax
├── erfa     Low-level ERFA routines (time, precession, nutation, astrometry, ...)
├── qpoint   Mid-level pointing pipeline (az/el → RA/Dec, HEALPix, IERS)
└── proj     High-level API (Quat, CelestialSightLine, FocalPlane, Assembly)

Each layer builds on the one below. Use proj for most telescope work; reach into qpoint or erfa when you need finer control.

Installation

pip install so-pointjax          # from PyPI (when published)
pip install -e .                 # editable install from source

Dependencies: jax >= 0.4.0, jaxlib >= 0.4.0. Tests additionally need pytest >= 7.0 and pyerfa >= 2.0.

Quick start

import jax
import jax.numpy as jnp
from so_pointjax.proj import Quat, CelestialSightLine, FocalPlane

# Build a pointing sightline from az/el + timestamps
t  = jnp.array([1700000000.0, 1700000001.0])
az = jnp.array([1.0, 1.01])
el = jnp.array([0.8, 0.8])

csl = CelestialSightLine.az_el(t, az, el, site='act', weather='toco')

# Extract sky coordinates: (N, 4) → [lon, lat, cos2psi, sin2psi]
coords = csl.coords()

# With a focal plane of detectors
fp = FocalPlane.from_xieta(
    jnp.array([0.0, 0.01, -0.01]),
    jnp.array([0.0, 0.01,  0.01]),
)
det_coords = csl.coords(fplane=fp)   # (n_det, N, 4)

End-to-end differentiable pointing

The entire pipeline is differentiable. Compute gradients of sky coordinates with respect to any input:

def sky_lon(az, el):
    csl = CelestialSightLine.naive_az_el(
        jnp.array([1700000000.0]),
        jnp.array([az]),
        jnp.array([el]),
        site='act',
    )
    return csl.coords()[0, 0]   # RA of first sample

dra_daz, dra_del = jax.grad(sky_lon, argnums=(0, 1))(1.0, 0.8)

Quaternion algebra

The Quat class wraps JAX arrays with quaternion arithmetic, broadcasting, and operator overloading:

from so_pointjax.proj import Quat

q1 = Quat.from_lonlat(1.0, 0.5)
q2 = Quat.from_euler(2, 0.1)
q  = q1 * q2          # quaternion product
q_inv = ~q             # conjugate/inverse

# Batch operations with automatic broadcasting
q_arr = Quat.from_euler(2, jnp.linspace(0, 1, 1000))
rotated = q1 * q_arr   # (4,) x (1000, 4) -> (1000, 4)

Quat is a JAX pytree and works transparently with jit, grad, and vmap.

Submodule guides

Each submodule has its own detailed README:

  • so_pointjax.erfa -- Differentiable ERFA: time scales, precession-nutation, astrometry, ephemerides, coordinate frames, geodetic transforms, and more (~200 functions).

  • so_pointjax.qpoint -- Pointing pipeline: quaternion algebra, atmospheric/aberration corrections, az/el to RA/Dec conversion, HEALPix pixelization, IERS Bulletin A support.

  • so_pointjax.proj -- High-level API: Quat class with operator overloading, CelestialSightLine, FocalPlane, Assembly, observatory sites, and weather models.

Precision

Validated against the original C/Fortran implementations to sub-milliarcsecond accuracy:

Layer Agreement
ERFA functions Matches pyerfa
Quaternion functions Bit-identical to so3g
naive_az_el ~1e-12 (quat diff)
az_el (all weather/sites) 0.0004--0.0005 arcsec
Detector projection ~1e-12

Running tests

# All tests
python -m pytest so_pointjax/ -v

# By submodule
python -m pytest so_pointjax/erfa/tests/ -v
python -m pytest so_pointjax/qpoint/tests/ -v
python -m pytest so_pointjax/proj/tests/ -v

# Cross-validation against so3g (requires so3g)
python -m pytest so_pointjax/proj/tests/test_cross_validation.py -v -s

Performance

Key results (CPU, JIT-compiled):

  • Quaternion ops: 1.3--7x faster than so3g at N >= 100K
  • Pointing pipeline: 3--8x faster across all sizes
  • Bore x det composition: 2--3x faster for realistic focal planes
  • Gradients: ~1 us/sample (unique capability vs so3g)
python -m so_pointjax.proj.benchmarks.bench_so3g [--quick]
python -m so_pointjax.proj.benchmarks.bench_quat_array [--quick]
python -m so_pointjax.qpoint.benchmarks.bench_pointing [--quick]

Acknowledgments

This package is a JAX reimplementation of algorithms from:

  • ERFA (NumFOCUS Foundation), derived from the IAU's SOFA library
  • qpoint (Alexandra Rahlin)
  • so3g (Simons Observatory)
  • HEALPix (Gorski et al.)

See NOTICE for full license texts of the upstream libraries.

License

BSD-3-Clause. See LICENSE.

Metadata

Release files for so-pointjax 0.1.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for so-pointjax 0.1.0
File Size Uploaded Provenance Actions
so_pointjax-0.1.0.tar.gz 200.3 kB Without provenance Details for so_pointjax-0.1.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for so-pointjax 0.1.0
File Interpreter ABI Platform Actions
so_pointjax-0.1.0-py3-none-any.whl Python 3 none any Details for so_pointjax-0.1.0-py3-none-any.whl

Total release size: 432.2 kB

Release files / so_pointjax-0.1.0.tar.gz

Download URL so_pointjax-0.1.0.tar.gz
Size 200.3 kB
Tags Source
SHA-256 checksum
How to use checksums
57476a941859d3504f5caa007c9ec9d4cdd1c12a4a865f22f8c7c002d303d887
BLAKE2b-256 checksum
How to use checksums
ce1d8501a159d6655c89e8616edc3a3a97a628298050d8460f3e69baf94cab04
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.8

Release files / so_pointjax-0.1.0-py3-none-any.whl

Download URL so_pointjax-0.1.0-py3-none-any.whl
Size 231.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
62233cdd8219e4e19c4fe488907ddc872a1f32fc665485b87a181f792f4ef8dc
BLAKE2b-256 checksum
How to use checksums
c61b10f357515dedda5e6f059a11fecc7c46f2478dea95ae401d2845e083cd15
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/6.2.0 CPython/3.12.8

Security for so-pointjax 0.1.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page