Metadata-Version: 2.4
Name: torchsky
Version: 0.5.0
Summary: Torch-native sky data, coordinates, geometry, and mapmaking
Keywords: astronomy,pytorch,tensor,wcs,healpix,mapmaking,coadd,differentiable,machine-learning
Author-Email: Seb Fabbro <sebfabbro@gmail.com>
License-Expression: MIT
License-File: LICENSE
License-File: src/torchsky/cpp_src/third_party/pocketfft.LICENSE.md
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: C++
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Project-URL: Homepage, https://github.com/astroai/torchsky
Project-URL: Repository, https://github.com/astroai/torchsky
Project-URL: Documentation, https://astroai.github.io/torchsky/
Project-URL: Changelog, https://astroai.github.io/torchsky/project/changelog/
Project-URL: Issues, https://github.com/astroai/torchsky/issues
Requires-Python: >=3.12
Requires-Dist: torch<2.15,>=2.14
Requires-Dist: numpy>=1.20.0
Requires-Dist: torchfits>=1.3.1
Provides-Extra: docs
Requires-Dist: zensical<0.1,>=0.0.71; extra == "docs"
Requires-Dist: mkdocstrings-python<2,>=1.16; extra == "docs"
Provides-Extra: viz
Requires-Dist: fastapi>=0.110; extra == "viz"
Requires-Dist: uvicorn[standard]>=0.29; extra == "viz"
Requires-Dist: pillow>=10.0; extra == "viz"
Requires-Dist: matplotlib>=3.8; extra == "viz"
Provides-Extra: dev
Requires-Dist: pytest>=6.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0; extra == "dev"
Requires-Dist: ruff<0.16,>=0.15.5; extra == "dev"
Requires-Dist: ipykernel; extra == "dev"
Requires-Dist: pyright>=1.1.350; extra == "dev"
Provides-Extra: test
Requires-Dist: pytest>=6.0; extra == "test"
Requires-Dist: pytest-cov>=2.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0; extra == "test"
Requires-Dist: psutil>=5.0; extra == "test"
Requires-Dist: fastapi>=0.110; extra == "test"
Requires-Dist: httpx>=0.27; extra == "test"
Requires-Dist: pillow>=10.0; extra == "test"
Requires-Dist: scipy>=1.9.0; extra == "test"
Requires-Dist: requests>=2.28.0; extra == "test"
Requires-Dist: polars>=1.0; extra == "test"
Requires-Dist: pyarrow>=14.0; extra == "test"
Requires-Dist: pandas>=2.2; extra == "test"
Requires-Dist: astropy>=5.0; extra == "test"
Requires-Dist: matplotlib>=3.8; extra == "test"
Requires-Dist: pyright>=1.1.350; extra == "test"
Provides-Extra: examples
Requires-Dist: polars>=1.0; extra == "examples"
Requires-Dist: pyarrow>=14.0; extra == "examples"
Requires-Dist: pandas>=2.2; extra == "examples"
Requires-Dist: astropy>=5.0; extra == "examples"
Provides-Extra: map
Requires-Dist: astropy>=5.0; extra == "map"
Requires-Dist: astroquery>=0.4.6; extra == "map"
Provides-Extra: ephem
Requires-Dist: jplephem>=2.17; extra == "ephem"
Provides-Extra: tle
Requires-Dist: sgp4>=2.21; extra == "tle"
Provides-Extra: gwcs
Requires-Dist: gwcs>=0.18; extra == "gwcs"
Description-Content-Type: text/markdown

# torchsky

[![CI](https://github.com/astroai/torchsky/actions/workflows/ci.yml/badge.svg)](https://github.com/astroai/torchsky/actions/workflows/ci.yml)
[![Docs](https://img.shields.io/badge/docs-astroai.github.io%2Ftorchsky-brightgreen)](https://astroai.github.io/torchsky/)
[![PyPI](https://img.shields.io/pypi/v/torchsky)](https://pypi.org/project/torchsky/)
[![Python 3.12-3.14](https://img.shields.io/badge/python-3.12%E2%80%933.14-blue)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/license-MIT-green)](https://github.com/astroai/torchsky/blob/main/LICENSE)

Sky coordinates, spherical geometry, and mapmaking as PyTorch tensor operations.
They run on CPU, CUDA, and MPS, support autograd, and scale to survey-sized inputs.

torchsky covers FITS-WCS, HEALPix, spherical harmonic transforms, catalog
crossmatch, image coadds, spectral cubes, and observation operators. FITS reading
and writing is handled by [torchfits](https://github.com/astroai/torchfits), which
torchsky installs as a dependency.

## Install

Stable releases, from 0.5.0, are on PyPI: `pip install torchsky`. Release
candidates are only [GitHub pre-releases](https://github.com/astroai/torchsky/releases)
and are never uploaded to PyPI. Building from source needs a C++ compiler and
CMake for the native extension:

```bash
git clone https://github.com/astroai/torchsky.git
cd torchsky
pip install .
```

torchsky supports Python 3.12 to 3.14 with PyTorch 2.14. The
[installation guide](https://astroai.github.io/torchsky/introduction/install/) covers CUDA,
Pixi, and troubleshooting.

## Quick start

```python
import torch
import torchsky.sphere as sphere
from torchsky.map import Observation, coadd, plan
from torchsky.wcs import WCS

header = {"NAXIS": 2, "NAXIS1": 64, "NAXIS2": 64,
          "CTYPE1": "RA---TAN", "CTYPE2": "DEC--TAN", "CRPIX1": 32.5, "CRPIX2": 32.5,
          "CRVAL1": 150.0, "CRVAL2": 2.0, "CDELT1": -2.8e-4, "CDELT2": 2.8e-4}

ra, dec = WCS(header).pixel_to_world(torch.tensor([0.0, 63.0]), torch.tensor([0.0, 63.0]))
pix = sphere.ang2pix(1024, ra, dec, lonlat=True, nest=True)

obs = [Observation(data=torch.randn(64, 64), wcs={**header, "CRVAL1": c}) for c in (150.0, 150.01)]
result = coadd(obs, plan(obs, projection="TAN"), kernel="bilinear")
```

For real files, read them with torchfits and pass the header on:
`data, header = torchfits.read("image.fits", return_header=True)`.

## What's in the box

| Namespace | Contents |
|---|---|
| `torchsky.wcs` | FITS-WCS projections, SIP/TPV distortions, affine fitting |
| `torchsky.sphere` | HEALPix, MOC, sparse maps, polygons, spin SHT |
| `torchsky.coords` | Frame conversion, observed alt/az, proper motion |
| `torchsky.catalogs` | Crossmatch and spherical partitioning |
| `torchsky.map` | Coadds, spectral cubes, observation operators, solvers |
| `torchsky.spectral` and friends | Spectra, photometry, extinction, cosmology |
| `torchsky.scene`, `torchsky.field` | Forward models and continuous sky fields (experimental) |

## Performance

On 135 JWST/NIRCam exposures (566 Mpix) onto a 512 x 512 grid, torchsky's
Lanczos-3 coadd takes 14.3 s on 8 CPU threads and 5.2 s on a GPU slice, against
30.1 s for SWarp. Its drizzle matches STScI drizzle to better than 2e-6 sigma. A
280-CCD UNIONS tile coadd fell from 2292 s to 711 s on CPU. Hardware, versions,
and evidence are on the
[performance highlights](https://astroai.github.io/torchsky/performance/highlights/)
page.

## Documentation

- [Quick start](https://astroai.github.io/torchsky/introduction/quickstart/) and
  [examples](https://astroai.github.io/torchsky/examples/)
- [User guide and API reference](https://github.com/astroai/torchsky/blob/main/docs/index.md)
  (rendered at [astroai.github.io/torchsky](https://astroai.github.io/torchsky/))
- [Coming from Astropy, healpy, or reproject](https://astroai.github.io/torchsky/introduction/coming-from/)
- [Changelog](https://astroai.github.io/torchsky/project/changelog/)

## Contributing

Development uses [pixi](https://pixi.sh):

```bash
git clone https://github.com/astroai/torchsky.git && cd torchsky
pixi install --locked
pixi run dev              # build the native extension in place
pixi run preflight-push   # lint + compile check
pixi run test             # unit suite
```

Read [CONTRIBUTING.md](https://github.com/astroai/torchsky/blob/main/CONTRIBUTING.md)
before opening a PR. Issues labelled
[good first issue](https://github.com/astroai/torchsky/labels/good%20first%20issue)
are a good place to start.

## Citation

If torchsky helps your research, please cite it using
[CITATION.cff](https://github.com/astroai/torchsky/blob/main/CITATION.cff).

## License

[MIT](https://github.com/astroai/torchsky/blob/main/LICENSE)
