torchsky

Pre-release: 0.4.0 is the current development line and is not yet on PyPI. It ships when the correctness, performance, API, documentation, and harness goals in the roadmap are met.

torchsky is a high-performance, torch-native astronomy stack for survey-scale coordinates, spherical geometry, catalog indexing, mapmaking, observation operators, and joint modelling of sky observations.

FITS image and table I/O is provided by the focused torchfits package. The boundary is intentional: torchfits loads tensors and metadata; torchsky performs sky-domain computation without embedding a second FITS/CFITSIO engine. The supported integration baseline is torchfits 1.0.0 or newer. Torchsky does not expose alias namespaces for torchfits I/O, tables, caches, or datasets; import those directly from torchfits.

---

Table of Contents

1. Key Features
2. Performance Highlights
3. Installation
4. Quick Start
5. Contributor Setup
6. Documentation Directory
7. License

---

Key Features

• 🌌 Torch-Native WCS: FITS-WCS transforms (TAN, SIN, ARC, AIT, etc.) and polynomial distortions (SIP, TPV, TNX, ZPX) running directly on CPU, CUDA, and MPS.
• 🌐 Spherical Geometry & HEALPix: Vectorized HEALPix primitives, Spherical Polygons, Multi-Order Coverage (MOC) maps, and high-performance Spherical Harmonic Transforms (SHT).
• 🗺️ Scalable Mapmaking: Area-aware coadds, spectral-cube stacking, matrix-free observation operator bundles, and bounded-memory execution.
• 🔭 Survey-Scale Catalog Geometry: Tensor-native crossmatch and spherical indexing primitives designed for candidate pruning and chunked execution.
• 🧠 Continuous Field Models: Experimental continuous spectral neural fields ((F_\theta(\mathrm{RA}, \mathrm{Dec}, \lambda))) for implicit forward modeling.
• 🔌 Explicit I/O Boundary: Tensor/header/table-batch interchange with torchfits and other readers.

---

Performance Highlights

Scientific performance claims, upstream parity campaigns, real-data evaluation, and scorecards are maintained in the sibling torchsky-harness repository. Torchsky retains bounded package tests and performance smoke checks for its own runtime paths. FITS image/table throughput belongs to torchfits. See the scientific evaluation guide for the ownership boundary.

Current release-candidate evidence (same-machine, reference comparisons):

• WCS: 38 cases against astropy (30 projections plus reference-latitude-offset cases). Angular parity max 4.13e-5 asec (the AIR formula floor; every other case <=1.5e-8 asec), pole/seam-excluded round trip 4.13e-5 asec, pixel round trip 1.27e-6 px; forward 0.46–3.81x and inverse 0.97–6.01x astropy throughput.
• HEALPix: 12 operations against healpy at nside 512, zero index/angle mismatches (max 1.14e-13 deg), throughput 1.02–2.19x.
• Sphere and spin SHT: parity gates pass against healpy; throughput ratios are recorded, not gated.
• Catalogs: crossmatch against astropy SkyCoord, max separation difference 1.13e-10 asec.
• GPU: 17 WCS cases on CUDA (including the reference-offset cases) all OK at max 8.2e-3 asec angular parity.

---

Installation

torchsky is not yet published on PyPI; install the release wheel or build from source in the meantime:

# Wheel built from this repository (see docs/release.md)
pip install "torchsky @ file:///path/to/torchsky-0.4.0-cp*-*.whl"

Package metadata supports Python >=3.12, PyTorch >=2.13, and torchfits >=1.0.0 without upper caps. Native wheels fail closed on a mismatched compiled PyTorch ABI; build from source against a newer supported runtime when needed. Install torchfits alongside torchsky when a workflow reads or writes FITS files:

pip install torchfits

The integration baseline is torchfits 1.0.0 or newer. Dataset and DataLoader classes are provided by torchfits.data; torchsky does not alias them.

Optional Extras

• viz: Browser sky viewer

  pip install "torchsky[viz]"
  

• map: Extended mapmaking tools (e.g. SVO filter profiles)

  pip install "torchsky[map]"
  

---

Quick Start

1. Load Data With torchfits, Compute With torchsky

import torchfits
from torchsky.wcs import WCS

# File I/O belongs to torchfits.
data, header = torchfits.read(
    "science.fits",
    hdu="auto",
    device="cuda",
    return_header=True,
)

# Sky-coordinate computation belongs to torchsky.
wcs = WCS(header)
ra, dec = wcs.pixel_to_world(x, y)

2. Stream Catalog Batches

# torchfits owns FITS table projection and predicate pushdown.
for batch in torchfits.table.scan(
    "catalog.fits",
    hdu=1,
    columns=["RA", "DEC", "MAG_G"],
    where="MAG_G < 20",
    batch_size=100_000,
):
    process_catalog_batch(batch)

3. HEALPix Operations

import torch
import torchsky.sphere as sphere

lon = torch.tensor([10.0, 42.0])
lat = torch.tensor([-1.0, 5.0])

# Coordinate to HEALPix pixel mapping
pix = sphere.ang2pix(1024, lon, lat, lonlat=True, nest=True)
lon2, lat2 = sphere.pix2ang(1024, pix, lonlat=True, nest=True)

---

Contributor Setup

Contributors should use pixi for environment management:

git clone https://github.com/astroai/torchsky.git
cd torchsky
pixi install
pixi run dev            # Rebuild native extensions
pixi run verify         # Verify torchsky import smoke

Common Developer Commands

• Run test suite: pixi run test
• Fast syntax/lint check (git pre-push hook): pixi run preflight-push
• Typecheck: pixi run typecheck
• Optional local copy of GitHub build-test: pixi run ci-local

For more information, see the Contributing Guide.

---

Documentation Directory

Getting Started & Installation

• Documentation — Entry point for guides, API reference, and examples.
• Quick Start — From a FITS file to science products in a few minutes.
• Getting Started Guide — 10-minute introduction to the stack.
• Installation Guide — torchfits integration and native build configuration.
• Examples — Runnable scripts, gated by pixi run examples.

API Reference

• API Router — Map of goals to namespaces and reference pages.
• WCS, Sphere/HEALPix, Map, Field, Catalogs, Spectral, Scene, Runtime.

Core Modules

• I/O Boundary Guide — torchfits integration and tensor/metadata contracts.
• Table Boundary Guide — torchfits.table and torchsky catalog batches.
• WCS Guide — Coordinate projections and distortions.
• Sphere & HEALPix Guide — Spherical geometry and SHT.
• Mapmaking Guide — Image-plane coadds and product targets.
• Scene Facade Guide — High-level observation and rendering facade.

Advanced Modeling & Research

• Continuous Fields Guide — Neural fields and spectral mapping.
• Implicit Forward Modeling Guide — Loss formulations and kinematic states.
• Catalogs Guide — Sky crossmatching and partition streaming.
• Spectral Data Guide — IFU cube handling and 1D spectrum containers.
• ML & Runtime Guide — Dataset, DataLoader, and cache tuning.
• Encoders Guide — Feature encoders for spatial-spectral modeling.

Platform & Tooling

• CLI Guide — Command-line query, print, and viz tools.
• Visualization Guide — Browser sky/HiPS server.
• Ecosystem Compatibility Matrix — AST, astropy, healpy interop boundaries.
• Benchmarks Guide — Command lines, runs, and correctness gates.
• Contributing Guidelines — PR policy and code rules.
• Release Checklist — Step-by-step maintainer runbook.
• Agent & Maintainer Operating Guide — Engineering guidelines for agents.
• Changelog — Release versions history.

---

License

torchsky is licensed under the MIT License.