hwoutils 1.0.0__tar.gz

hwoutils-1.0.0/.gitignore

@@ -0,0 +1,213 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Auto-generated version file (hatch-vcs)
+*_version.py
+.DS_Store
+input/
+output/

hwoutils-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,20 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: "v6.0.0"
+    hooks:
+      - id: trailing-whitespace
+      - id: name-tests-test
+      - id: end-of-file-fixer
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.10
+    hooks:
+      # Run the linter.
+      - id: ruff
+      # Run the formatter.
+      - id: ruff-format
+  - repo: https://github.com/compilerla/conventional-pre-commit
+    rev: v4.3.0
+    hooks:
+      - id: conventional-pre-commit
+        stages: [commit-msg]
+        args: []

hwoutils-1.0.0/.readthedocs.yaml

@@ -0,0 +1,20 @@
+# Required
+version: 2
+
+# Set the OS, Python version and other tools you might need
+build:
+  os: ubuntu-22.04
+  tools:
+    python: "3.12"
+
+python:
+  install:
+    - method: pip
+      path: .
+      extra_requirements:
+        # Install with the [docs] flag for sphinx docs specific extensions
+        - docs
+
+# Build documentation in the "docs/" directory with Sphinx
+sphinx:
+  configuration: docs/conf.py

hwoutils-1.0.0/CHANGELOG.md

@@ -0,0 +1,19 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## 1.0.0 (2026-02-21)
+
+
+### Features
+
+* Initial migration of repeated code ([9150db9](https://github.com/CoreySpohn/hwoutils/commit/9150db9bac1368570d4177504377862668e5c164))
+
+## [Unreleased]
+
+### Added
+
+- `constants` module with consolidated physical constants from orbix and coronagraphoto
+- `conversions` module with JAX-native unit conversion functions
+- `map_coordinates` module with cubic spline interpolation (from JAX PR #14218)
+- `transforms` module with `resample_flux`, `ccw_rotation_matrix`, and `shift_image`

hwoutils-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Corey Spohn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

hwoutils-1.0.0/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.4
+Name: hwoutils
+Version: 1.0.0
+Summary: Shared JAX-based utilities for the HWO direct imaging simulation suite — constants, conversions, and image transforms.
+Project-URL: Homepage, https://github.com/CoreySpohn/hwoutils
+Project-URL: Issues, https://github.com/CoreySpohn/hwoutils/issues
+Author-email: Corey Spohn <corey.a.spohn@nasa.gov>
+License: MIT License
+        
+        Copyright (c) 2026 Corey Spohn
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Requires-Python: >=3.10
+Requires-Dist: jax
+Requires-Dist: jaxlib
+Provides-Extra: dev
+Requires-Dist: pre-commit; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: ipython; extra == 'docs'
+Requires-Dist: matplotlib; extra == 'docs'
+Requires-Dist: myst-nb; extra == 'docs'
+Requires-Dist: sphinx; extra == 'docs'
+Requires-Dist: sphinx-autoapi; extra == 'docs'
+Requires-Dist: sphinx-autodoc-typehints; extra == 'docs'
+Requires-Dist: sphinx-book-theme; extra == 'docs'
+Provides-Extra: test
+Requires-Dist: hypothesis; extra == 'test'
+Requires-Dist: nox; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="https://pypi.org/project/hwoutils/"><img src="https://img.shields.io/pypi/v/hwoutils.svg?style=flat-square&logo=pypi" alt="PyPI"/></a>
+  <a href="https://hwoutils.readthedocs.io"><img src="https://readthedocs.org/projects/hwoutils/badge/?version=latest&style=flat-square" alt="Documentation Status"/></a>
+  <a href="https://github.com/CoreySpohn/hwoutils/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/CoreySpohn/hwoutils/tests.yml?branch=main&style=flat-square&logo=github&label=tests" alt="Tests"/></a>
+  <a href="https://github.com/CoreySpohn/hwoutils/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License"></a>
+  <a href="https://github.com/CoreySpohn/hwoutils"><img src="https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-blue.svg?style=flat-square&logo=python" alt="Python Versions"></a>
+</p>
+
+---
+
+# hwoutils
+
+**hwoutils** is the shared utility foundation for the HWO direct imaging simulation suite. It provides JAX-native physical constants, unit conversions, and flux-conserving image transforms used across:
+
+- **[yippy](https://github.com/CoreySpohn/yippy)** — Coronagraph performance modeling
+- **[orbix](https://github.com/CoreySpohn/orbix)** — Orbital dynamics and target scheduling
+- **[coronagraphoto](https://github.com/CoreySpohn/coronagraphoto)** — Image simulation for coronagraphic observations
+- **[coronalyze](https://github.com/CoreySpohn/coronalyze)** — Post-processing and SNR analysis
+- **[hwosim](https://github.com/CoreySpohn/hwosim)** — End-to-end mission simulations
+
+## Key Features
+
+- **Physical Constants** — Single source of truth for SI constants, conversion factors, and astronomical quantities
+- **Unit Conversions** — Pure JAX conversion functions (angular, flux, distance, time) with zero astropy overhead
+- **Image Transforms** — Flux-conserving resampling, sub-pixel shifts, and cubic spline interpolation
+- **JAX-Native** — All operations are JIT-compilable, differentiable, and GPU-accelerated
+
+## Installation
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv pip install hwoutils
+```
+
+Or with pip:
+
+```bash
+pip install hwoutils
+```
+
+## Quick Start
+
+```python
+from hwoutils import constants as const
+from hwoutils import conversions as conv
+from hwoutils.transforms import resample_flux
+
+# Convert 5 arcsec to lambda/D for a 6m telescope at 550nm
+sep_lod = conv.arcsec_to_lambda_d(5.0, 550.0, 6.0)
+
+# Flux-conserving PSF resampling
+resampled = resample_flux(psf, pixscale_src=0.01, pixscale_tgt=0.1, shape_tgt=(64, 64))
+```
+
+## Documentation
+
+Full documentation is available at [hwoutils.readthedocs.io](https://hwoutils.readthedocs.io).

hwoutils-1.0.0/README.md

@@ -0,0 +1,58 @@
+<p align="center">
+  <a href="https://pypi.org/project/hwoutils/"><img src="https://img.shields.io/pypi/v/hwoutils.svg?style=flat-square&logo=pypi" alt="PyPI"/></a>
+  <a href="https://hwoutils.readthedocs.io"><img src="https://readthedocs.org/projects/hwoutils/badge/?version=latest&style=flat-square" alt="Documentation Status"/></a>
+  <a href="https://github.com/CoreySpohn/hwoutils/actions/workflows/tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/CoreySpohn/hwoutils/tests.yml?branch=main&style=flat-square&logo=github&label=tests" alt="Tests"/></a>
+  <a href="https://github.com/CoreySpohn/hwoutils/blob/main/LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square" alt="License"></a>
+  <a href="https://github.com/CoreySpohn/hwoutils"><img src="https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12-blue.svg?style=flat-square&logo=python" alt="Python Versions"></a>
+</p>
+
+---
+
+# hwoutils
+
+**hwoutils** is the shared utility foundation for the HWO direct imaging simulation suite. It provides JAX-native physical constants, unit conversions, and flux-conserving image transforms used across:
+
+- **[yippy](https://github.com/CoreySpohn/yippy)** — Coronagraph performance modeling
+- **[orbix](https://github.com/CoreySpohn/orbix)** — Orbital dynamics and target scheduling
+- **[coronagraphoto](https://github.com/CoreySpohn/coronagraphoto)** — Image simulation for coronagraphic observations
+- **[coronalyze](https://github.com/CoreySpohn/coronalyze)** — Post-processing and SNR analysis
+- **[hwosim](https://github.com/CoreySpohn/hwosim)** — End-to-end mission simulations
+
+## Key Features
+
+- **Physical Constants** — Single source of truth for SI constants, conversion factors, and astronomical quantities
+- **Unit Conversions** — Pure JAX conversion functions (angular, flux, distance, time) with zero astropy overhead
+- **Image Transforms** — Flux-conserving resampling, sub-pixel shifts, and cubic spline interpolation
+- **JAX-Native** — All operations are JIT-compilable, differentiable, and GPU-accelerated
+
+## Installation
+
+With [uv](https://docs.astral.sh/uv/) (recommended):
+
+```bash
+uv pip install hwoutils
+```
+
+Or with pip:
+
+```bash
+pip install hwoutils
+```
+
+## Quick Start
+
+```python
+from hwoutils import constants as const
+from hwoutils import conversions as conv
+from hwoutils.transforms import resample_flux
+
+# Convert 5 arcsec to lambda/D for a 6m telescope at 550nm
+sep_lod = conv.arcsec_to_lambda_d(5.0, 550.0, 6.0)
+
+# Flux-conserving PSF resampling
+resampled = resample_flux(psf, pixscale_src=0.01, pixscale_tgt=0.1, shape_tgt=(64, 64))
+```
+
+## Documentation
+
+Full documentation is available at [hwoutils.readthedocs.io](https://hwoutils.readthedocs.io).

hwoutils-1.0.0/pyproject.toml

@@ -0,0 +1,62 @@
+[build-system]
+requires = ['hatchling', "hatch-fancy-pypi-readme", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[project]
+name = "hwoutils"
+description = "Shared JAX-based utilities for the HWO direct imaging simulation suite — constants, conversions, and image transforms."
+authors = [{ name = "Corey Spohn", email = "corey.a.spohn@nasa.gov" }]
+dynamic = ['readme', 'version']
+requires-python = ">=3.10"
+license = { file = "LICENSE" }
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Intended Audience :: Science/Research",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Scientific/Engineering :: Astronomy",
+]
+dependencies = [
+  "jax",
+  "jaxlib",
+]
+[project.optional-dependencies]
+dev = ["ruff", "pre-commit"]
+docs = [
+  "sphinx",
+  "myst-nb",
+  "sphinx-book-theme",
+  "sphinx-autoapi",
+  "sphinx_autodoc_typehints",
+  "ipython",
+  "matplotlib",
+]
+test = ["nox", "pytest", "hypothesis", "pytest-cov"]
+
+[project.urls]
+Homepage = "https://github.com/CoreySpohn/hwoutils"
+Issues = "https://github.com/CoreySpohn/hwoutils/issues"
+
+[tool.hatch.version]
+source = "vcs"
+
+[tool.hatch.build.hooks.vcs]
+version-file = "src/hwoutils/_version.py"
+
+[tool.hatch.metadata.hooks.fancy-pypi-readme]
+content-type = "text/markdown"
+
+[[tool.hatch.metadata.hooks.fancy-pypi-readme.fragments]]
+path = "README.md"
+
+[tool.ruff.lint]
+select = ["D", "I"]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/hwoutils"]
+
+[tool.hatch.build.targets.sdist]
+exclude = ["/scripts", "/docs", "/tests", "/.github"]

hwoutils-1.0.0/src/hwoutils/__init__.py

@@ -0,0 +1,6 @@
+"""hwoutils — Shared JAX-based utilities for the HWO simulation suite."""
+
+try:
+    from hwoutils._version import version as __version__
+except ModuleNotFoundError:
+    __version__ = "unknown"

hwoutils-1.0.0/src/hwoutils/_version.py

@@ -0,0 +1,34 @@
+# file generated by setuptools-scm
+# don't change, don't track in version control
+
+__all__ = [
+    "__version__",
+    "__version_tuple__",
+    "version",
+    "version_tuple",
+    "__commit_id__",
+    "commit_id",
+]
+
+TYPE_CHECKING = False
+if TYPE_CHECKING:
+    from typing import Tuple
+    from typing import Union
+
+    VERSION_TUPLE = Tuple[Union[int, str], ...]
+    COMMIT_ID = Union[str, None]
+else:
+    VERSION_TUPLE = object
+    COMMIT_ID = object
+
+version: str
+__version__: str
+__version_tuple__: VERSION_TUPLE
+version_tuple: VERSION_TUPLE
+commit_id: COMMIT_ID
+__commit_id__: COMMIT_ID
+
+__version__ = version = '1.0.0'
+__version_tuple__ = version_tuple = (1, 0, 0)
+
+__commit_id__ = commit_id = None

hwoutils-1.0.0/src/hwoutils/constants.py

@@ -0,0 +1,81 @@
+"""Physical constants and unit conversion factors.
+
+Single source of truth for all constants used across the HWO simulation suite
+(yippy, orbix, coronagraphoto, coronalyze, hwosim). All values are plain floats
+or JAX arrays — no astropy.units dependency.
+"""
+
+import jax.numpy as jnp
+
+# ---------------------------------------------------------------------------
+# Mathematical constants
+# ---------------------------------------------------------------------------
+two_pi = 2 * jnp.pi
+pi_over_2 = jnp.pi / 2
+eps = jnp.finfo(jnp.float32).eps
+
+# ---------------------------------------------------------------------------
+# Fundamental physical constants (SI)
+# ---------------------------------------------------------------------------
+h = 6.62607015e-34  # Planck constant [J·s]
+c = 299792458.0  # Speed of light [m/s]
+k_B = 1.380649e-23  # Boltzmann constant [J/K]
+sigma_SB = 5.670374419e-8  # Stefan-Boltzmann constant [W·m⁻²·K⁻⁴]
+
+# ---------------------------------------------------------------------------
+# Gravitational constant
+# ---------------------------------------------------------------------------
+G_si = 6.67430e-11  # [m³·kg⁻¹·s⁻²]
+G = 1.488185170234519e-34  # [AU³·kg⁻¹·d⁻²] — for orbital dynamics
+
+# ---------------------------------------------------------------------------
+# Flux conversion
+# ---------------------------------------------------------------------------
+Jy = 1e-26  # 1 Jansky [W·m⁻²·Hz⁻¹]
+
+# ---------------------------------------------------------------------------
+# Length conversions
+# ---------------------------------------------------------------------------
+nm2m = 1e-9
+m2nm = 1e9
+um2m = 1e-6
+m2um = 1e6
+nm2um = 1e-3
+um2nm = 1e3
+
+# ---------------------------------------------------------------------------
+# Distance conversions
+# ---------------------------------------------------------------------------
+AU2m = 1.495978707e11
+m2AU = 6.684587122268445e-12
+pc2m = 3.0857e16
+m2pc = 1.0 / pc2m
+pc2AU = 2.062648062470964e05
+Rearth2m = 6.371e6
+Rearth2AU = 4.263496512454037e-05
+
+# ---------------------------------------------------------------------------
+# Mass conversions
+# ---------------------------------------------------------------------------
+Msun2kg = 1.988409870698051e30
+Mearth2kg = 5.972167867791379e24
+Mjup2kg = 1.898124571735094e27
+
+# ---------------------------------------------------------------------------
+# Angular conversions
+# ---------------------------------------------------------------------------
+rad2arcsec = 206264.80624709636
+arcsec2rad = 4.84813681109536e-06
+mas2arcsec = 1e-3
+arcsec2mas = 1e3
+deg2rad = jnp.pi / 180.0
+rad2deg = 180.0 / jnp.pi
+
+# ---------------------------------------------------------------------------
+# Time conversions
+# ---------------------------------------------------------------------------
+yr2s = 365.25 * 86400.0
+s2yr = 1.0 / yr2s
+d2s = 86400.0
+s2d = 1.157407407407407e-05
+J2000_JD = 2451545.0

hwoutils-1.0.0/src/hwoutils/conversions.py

@@ -0,0 +1,302 @@
+"""Unit conversion functions using centralized constants.
+
+Pure JAX implementations — no astropy dependency. Functions are intentionally
+NOT JIT-compiled so JAX can fuse them into larger computation graphs.
+"""
+
+import jax.numpy as jnp
+
+from hwoutils import constants as const
+
+# ---------------------------------------------------------------------------
+# Flux conversions
+# ---------------------------------------------------------------------------
+
+
+def jy_to_photons_per_nm_per_m2(flux_jy, wavelength_nm):
+    """Convert flux density from Janskys to photons/s/nm/m².
+
+    Args:
+        flux_jy: Flux density in Janskys.
+        wavelength_nm: Wavelength in nanometers.
+
+    Returns:
+        Flux density in photons/s/nm/m².
+    """
+    return flux_jy * const.Jy / (wavelength_nm * const.h)
+
+
+def photons_per_nm_per_m2_to_jy(flux_phot, wavelength_nm):
+    """Convert flux density from photons/s/nm/m² to Janskys.
+
+    Args:
+        flux_phot: Flux density in photons/s/nm/m².
+        wavelength_nm: Wavelength in nanometers.
+
+    Returns:
+        Flux density in Janskys.
+    """
+    return flux_phot * (wavelength_nm * const.h) / const.Jy
+
+
+def mag_per_arcsec2_to_jy_per_arcsec2(mag_per_arcsec2):
+    """Convert surface brightness from mag/arcsec² to Jy/arcsec² (AB).
+
+    Args:
+        mag_per_arcsec2: Surface brightness in magnitudes per arcsec².
+
+    Returns:
+        Surface brightness in Jy/arcsec².
+    """
+    f0_jy = 3631.0  # AB magnitude zero point
+    return f0_jy * 10 ** (-0.4 * mag_per_arcsec2)
+
+
+# ---------------------------------------------------------------------------
+# Length conversions
+# ---------------------------------------------------------------------------
+
+
+def nm_to_um(length_nm):
+    """Convert nanometers to micrometers."""
+    return length_nm * const.nm2um
+
+
+def um_to_nm(length_um):
+    """Convert micrometers to nanometers."""
+    return length_um * const.um2nm
+
+
+def au_to_m(length_au):
+    """Convert AU to meters."""
+    return length_au * const.AU2m
+
+
+def m_to_au(length_m):
+    """Convert meters to AU."""
+    return length_m * const.m2AU
+
+
+def Rearth_to_m(length_Rearth):
+    """Convert Earth radii to meters."""
+    return length_Rearth * const.Rearth2m
+
+
+# ---------------------------------------------------------------------------
+# Velocity conversions
+# ---------------------------------------------------------------------------
+
+
+def au_per_yr_to_m_per_s(velocity_au_per_yr):
+    """Convert AU/yr to m/s."""
+    return velocity_au_per_yr * const.AU2m / const.yr2s
+
+
+# ---------------------------------------------------------------------------
+# Angular conversions
+# ---------------------------------------------------------------------------
+
+
+def arcsec_to_rad(angle_arcsec):
+    """Convert arcseconds to radians."""
+    return angle_arcsec * const.arcsec2rad
+
+
+def rad_to_arcsec(angle_rad):
+    """Convert radians to arcseconds."""
+    return angle_rad * const.rad2arcsec
+
+
+def mas_to_arcsec(angle_mas):
+    """Convert milliarcseconds to arcseconds."""
+    return angle_mas * const.mas2arcsec
+
+
+def arcsec_to_mas(angle_arcsec):
+    """Convert arcseconds to milliarcseconds."""
+    return angle_arcsec * const.arcsec2mas
+
+
+def arcsec_to_lambda_d(angle_arcsec, wavelength_nm, diameter_m):
+    """Convert angular separation to lambda/D units.
+
+    Args:
+        angle_arcsec: Angular separation in arcseconds.
+        wavelength_nm: Wavelength in nanometers.
+        diameter_m: Telescope diameter in meters.
+
+    Returns:
+        Angular separation in lambda/D.
+    """
+    angle_rad = angle_arcsec * const.arcsec2rad
+    wavelength_m = wavelength_nm * const.nm2m
+    lambda_d_rad = wavelength_m / diameter_m
+    return angle_rad / lambda_d_rad
+
+
+def lambda_d_to_arcsec(angle_lambda_d, wavelength_nm, diameter_m):
+    """Convert lambda/D units to angular separation in arcseconds.
+
+    Args:
+        angle_lambda_d: Angular separation in lambda/D.
+        wavelength_nm: Wavelength in nanometers.
+        diameter_m: Telescope diameter in meters.
+
+    Returns:
+        Angular separation in arcseconds.
+    """
+    wavelength_m = wavelength_nm * const.nm2m
+    lambda_d_rad = wavelength_m / diameter_m
+    angle_rad = angle_lambda_d * lambda_d_rad
+    return angle_rad * const.rad2arcsec
+
+
+# ---------------------------------------------------------------------------
+# Mass conversions
+# ---------------------------------------------------------------------------
+
+
+def Msun_to_kg(mass_solar):
+    """Convert solar masses to kilograms."""
+    return mass_solar * const.Msun2kg
+
+
+def Mearth_to_kg(mass_earth):
+    """Convert Earth masses to kilograms."""
+    return mass_earth * const.Mearth2kg
+
+
+# ---------------------------------------------------------------------------
+# Distance conversions
+# ---------------------------------------------------------------------------
+
+
+def au_to_arcsec(distance_au, distance_pc):
+    """Convert physical distance in AU to angular separation.
+
+    Args:
+        distance_au: Physical distance in AU.
+        distance_pc: Distance to system in parsecs.
+
+    Returns:
+        Angular separation in arcseconds.
+    """
+    return distance_au / distance_pc
+
+
+def arcsec_to_au(angle_arcsec, distance_pc):
+    """Convert angular separation to physical distance.
+
+    Args:
+        angle_arcsec: Angular separation in arcseconds.
+        distance_pc: Distance to system in parsecs.
+
+    Returns:
+        Physical distance in AU.
+    """
+    return angle_arcsec * distance_pc
+
+
+# ---------------------------------------------------------------------------
+# Time conversions
+# ---------------------------------------------------------------------------
+
+
+def years_to_days(time_years):
+    """Convert years to days."""
+    return time_years * 365.25
+
+
+def days_to_years(time_days):
+    """Convert days to years."""
+    return time_days / 365.25
+
+
+def is_leap_year(year):
+    """Determine if a year is a leap year.
+
+    Args:
+        year: The year to check.
+
+    Returns:
+        True if the year is a leap year.
+    """
+    return (year % 4 == 0) & ((year % 100 != 0) | (year % 400 == 0))
+
+
+def days_in_year(year):
+    """Return the number of days in a year (365 or 366).
+
+    Args:
+        year: The year to check.
+
+    Returns:
+        Number of days.
+    """
+    return 365 + is_leap_year(year)
+
+
+def gregorian_to_jd(year, month, day):
+    """Convert a Gregorian date to a Julian day.
+
+    Args:
+        year: The year.
+        month: The month.
+        day: The day.
+
+    Returns:
+        The Julian day.
+    """
+    a = jnp.floor((14 - month) / 12)
+    y = year + 4800 - a
+    m = month + 12 * a - 3
+    jdn = (
+        day
+        + jnp.floor((153 * m + 2) / 5)
+        + 365 * y
+        + jnp.floor(y / 4)
+        - jnp.floor(y / 100)
+        + jnp.floor(y / 400)
+        - 32045
+    )
+    return jdn - 0.5
+
+
+def jd_to_decimal_year(jd):
+    """Convert a Julian day to a decimal year.
+
+    Args:
+        jd: The Julian day.
+
+    Returns:
+        The decimal year.
+    """
+    year_approx = 1970.0 + (jd - 2440587.5) / 365.2425
+    year = jnp.floor(year_approx)
+
+    jd_start = gregorian_to_jd(year, 1, 1)
+    jd_end = gregorian_to_jd(year + 1, 1, 1)
+
+    year = jnp.where(jd < jd_start, year - 1, year)
+    jd_start = gregorian_to_jd(year, 1, 1)
+    jd_end = gregorian_to_jd(year + 1, 1, 1)
+
+    return year + (jd - jd_start) / (jd_end - jd_start)
+
+
+def decimal_year_to_jd(decimal_year):
+    """Convert a decimal year to a Julian day.
+
+    Args:
+        decimal_year: The decimal year.
+
+    Returns:
+        The Julian day.
+    """
+    year = jnp.floor(decimal_year)
+    year_fraction = decimal_year - year
+
+    jd_start = gregorian_to_jd(year, 1, 1)
+    jd_end = gregorian_to_jd(year + 1, 1, 1)
+
+    return jd_start + year_fraction * (jd_end - jd_start)

hwoutils-1.0.0/src/hwoutils/map_coordinates.py

@@ -0,0 +1,243 @@
+"""Cubic spline interpolation for JAX.
+
+This module contains an implementation of ``map_coordinates`` with cubic spline
+interpolation. It is adapted from the JAX project (PR #14218 by Louis Desdoigts)
+and is licensed under the Apache 2.0 license.
+
+Original JAX source:
+    https://github.com/google/jax/blob/main/jax/_src/scipy/ndimage.py
+"""
+
+from collections.abc import Callable, Sequence
+from typing import Dict
+
+import jax
+import jax.numpy as jnp
+from jax import lax, vmap
+from jax._src import api, util
+from jax._src.numpy.linalg import inv
+from jax._src.typing import Array, ArrayLike
+from jax._src.util import safe_zip as zip
+
+
+def _nonempty_prod(arrs: Sequence[Array]) -> Array:
+    return arrs[0] if len(arrs) == 1 else lax.reduce(arrs, lax.mul)
+
+
+def _nonempty_sum(arrs: Sequence[Array]) -> Array:
+    return arrs[0] if len(arrs) == 1 else lax.reduce(arrs, lax.add)
+
+
+def _mirror_index_fixer(index: Array, size: int) -> Array:
+    s = size - 1
+    return jnp.abs((index + s) % (2 * s) - s)
+
+
+def _reflect_index_fixer(index: Array, size: int) -> Array:
+    return jnp.floor_divide(_mirror_index_fixer(2 * index + 1, 2 * size + 1) - 1, 2)
+
+
+_INDEX_FIXERS: Dict[str, Callable[[Array, int], Array]] = {
+    "constant": lambda index, size: index,
+    "nearest": lambda index, size: jnp.clip(index, 0, size - 1),
+    "wrap": lambda index, size: index % size,
+    "mirror": _mirror_index_fixer,
+    "reflect": _reflect_index_fixer,
+}
+
+
+def _round_half_away_from_zero(a: Array) -> Array:
+    return a if jnp.issubdtype(a.dtype, jnp.integer) else lax.round(a)
+
+
+def _nearest_indices_and_weights(coordinate: Array) -> list[tuple[Array, Array]]:
+    index = _round_half_away_from_zero(coordinate).astype(jnp.int32)
+    weight = coordinate.dtype.type(1)
+    return [(index, weight)]
+
+
+def _linear_indices_and_weights(coordinate: Array) -> list[tuple[Array, Array]]:
+    lower = jnp.floor(coordinate)
+    upper_weight = coordinate - lower
+    lower_weight = coordinate.dtype.type(1) - upper_weight
+    index = lower.astype(jnp.int32)
+    return [(index, lower_weight), (index + 1, upper_weight)]
+
+
+def _cubic_indices_and_weights(coordinate: Array) -> list[tuple[Array, Array]]:
+    return _spline_point(None, coordinate)
+
+
+def _build_matrix(n: int, diag: float = 4) -> Array:
+    M = jnp.zeros((n, n))
+    idx = jnp.arange(n)
+    M = M.at[idx, idx].set(diag)
+    M = M.at[idx[:-1], idx[:-1] + 1].set(1)
+    M = M.at[idx[:-1] + 1, idx[:-1]].set(1)
+    return M
+
+
+def _construct_vector(data: Array, c2: Array, cnp2: Array) -> Array:
+    n = data.shape[0]
+    d = jnp.zeros(n)
+    d = d.at[0].set(6 * data[0] - c2)
+    d = d.at[-1].set(6 * data[-1] - cnp2)
+    d = d.at[1:-1].set(6 * data[1:-1])
+    return d
+
+
+def _solve_coefficients(data: Array, A_inv: Array, h=1) -> Array:
+    n = data.shape[0]
+    finite_diff = jnp.diff(data, axis=0) / h
+    c2 = 0.0
+    cnp2 = 0.0
+    d = vmap(_construct_vector, in_axes=(1, None, None))(finite_diff, c2, cnp2)
+    c = vmap(jnp.dot, in_axes=(None, 0))(A_inv, d).T
+    c = jnp.concatenate(
+        [jnp.zeros((1, c.shape[1])), c, jnp.zeros((1, c.shape[1]))], axis=0
+    )
+    return c
+
+
+def _spline_coefficients(data: Array) -> Array:
+    n = data.shape[0]
+    A = _build_matrix(n - 2)
+    A_inv = inv(A)
+    coefficients = _solve_coefficients(data, A_inv)
+    return coefficients
+
+
+def _spline_basis(t: Array) -> Array:
+    abs_t = jnp.abs(t)
+    return jnp.where(
+        abs_t <= 1,
+        2 / 3 - abs_t**2 + abs_t**3 / 2,
+        jnp.where(abs_t <= 2, (2 - abs_t) ** 3 / 6, 0.0),
+    )
+
+
+def _spline_value(coefficients: Array, coordinate: Array, indexes: Array) -> Array:
+    t = coordinate - indexes
+    weights = _spline_basis(t)
+    return jnp.sum(coefficients * weights, axis=0)
+
+
+def _spline_point(coefficients: Array, coordinate: Array) -> Array:
+    idx = jnp.floor(coordinate).astype(jnp.int32)
+    indexes = jnp.array([idx - 1, idx, idx + 1, idx + 2])
+    t = coordinate - indexes
+    weights = _spline_basis(t)
+    return [(i, w) for i, w in zip(indexes, weights)]
+
+
+def _cubic_spline(input: Array, coordinates: Array) -> Array:
+    coefficients = _spline_coefficients(input)
+    indexes = jnp.arange(input.shape[0])
+    return vmap(_spline_value, in_axes=(None, 0, None))(
+        coefficients, coordinates, indexes
+    )
+
+
+def _map_coordinates(
+    input: ArrayLike,
+    coordinates: Sequence[ArrayLike],
+    order: int,
+    mode: str,
+    cval: ArrayLike,
+) -> Array:
+    input_arr = jnp.asarray(input)
+    coordinates_arr = [jnp.asarray(c, dtype=input_arr.dtype) for c in coordinates]
+    cval = jnp.asarray(cval, input_arr.dtype)
+
+    if len(coordinates_arr) != input_arr.ndim:
+        raise ValueError(
+            f"coordinates must be a sequence of length input.ndim = {input_arr.ndim}, "
+            f"got {len(coordinates_arr)}"
+        )
+
+    index_fixer = _INDEX_FIXERS.get(mode)
+    if index_fixer is None:
+        raise NotImplementedError(
+            f"jax.scipy.ndimage.map_coordinates does not support mode {mode!r}"
+        )
+
+    if mode == "constant":
+        is_valid = lambda index, size: (index >= 0) & (index < size)
+    else:
+        is_valid = lambda index, size: True
+
+    if order == 0:
+        interp_fun = _nearest_indices_and_weights
+    elif order == 1:
+        interp_fun = _linear_indices_and_weights
+    elif order == 3:
+        interp_fun = _cubic_indices_and_weights
+    else:
+        raise NotImplementedError(
+            f"jax.scipy.ndimage.map_coordinates only supports order 0, 1, or 3, got {order}"
+        )
+
+    valid_1d_interpolations = []
+    for coordinate, size in zip(coordinates_arr, input_arr.shape):
+        interp_nodes = interp_fun(coordinate)
+        valid_interp = []
+        for index, weight in interp_nodes:
+            fixed_index = index_fixer(index, size)
+            valid = is_valid(index, size)
+            valid_interp.append((fixed_index, weight, valid))
+        valid_1d_interpolations.append(valid_interp)
+
+    outputs = []
+    for items in (
+        util.safe_zip(*valid_1d_interpolations)
+        if input_arr.ndim > 1
+        else [valid_1d_interpolations[0]]
+    ):
+        if input_arr.ndim == 1:
+            items = [items]
+
+        indices = []
+        validities = []
+        weights = []
+        for index, weight, valid in items:
+            indices.append(index)
+            weights.append(weight)
+            validities.append(valid)
+
+        if all(googles is True for googles in validities):
+            contribution = input_arr[tuple(indices)]
+        else:
+            all_valid = _nonempty_prod(validities) if validities else True
+            contribution = jnp.where(all_valid, input_arr[tuple(indices)], cval)
+
+        outputs.append(_nonempty_prod(weights) * contribution)
+
+    result = _nonempty_sum(outputs)
+    if jnp.issubdtype(input_arr.dtype, jnp.integer):
+        result = _round_half_away_from_zero(result)
+    return result
+
+
+def map_coordinates(
+    input: ArrayLike,
+    coordinates: Sequence[ArrayLike],
+    order: int,
+    mode: str = "constant",
+    cval: ArrayLike = 0.0,
+) -> Array:
+    """Map coordinates using cubic spline interpolation.
+
+    Args:
+        input: The input array.
+        coordinates: Sequence of coordinate arrays for each dimension.
+        order: Interpolation order (0=nearest, 1=linear, 3=cubic spline).
+        mode: Boundary handling ('constant', 'nearest', 'wrap', 'mirror',
+            'reflect').
+        cval: Value for 'constant' mode outside boundaries.
+
+    Returns:
+        Interpolated values at the given coordinates.
+    """
+    return api.jit(_map_coordinates, static_argnums=(2, 3))(
+        input, coordinates, order, mode, cval
+    )

hwoutils-1.0.0/src/hwoutils/transforms.py

@@ -0,0 +1,119 @@
+"""Image transformation utilities.
+
+Flux-conserving resampling and sub-pixel image operations. All functions
+are JIT-compilable and differentiable.
+"""
+
+import functools
+
+import jax
+import jax.numpy as jnp
+
+from hwoutils.map_coordinates import map_coordinates
+
+
+def ccw_rotation_matrix(rotation_deg: float) -> jax.Array:
+    """Return the counter-clockwise rotation matrix for a given angle.
+
+    Args:
+        rotation_deg: Rotation angle in degrees. Positive = counter-clockwise.
+
+    Returns:
+        2x2 rotation matrix as a JAX array.
+    """
+    theta = jnp.deg2rad(rotation_deg)
+    cos_theta = jnp.cos(theta)
+    sin_theta = jnp.sin(theta)
+    return jnp.array(
+        [
+            [cos_theta, -sin_theta],
+            [sin_theta, cos_theta],
+        ]
+    )
+
+
+@functools.partial(jax.jit, static_argnames=["order", "mode"])
+def shift_image(
+    image: jax.Array,
+    shift_y: float,
+    shift_x: float,
+    order: int = 3,
+    mode: str = "constant",
+    cval: float = 0.0,
+) -> jax.Array:
+    """Shift an image with sub-pixel precision using cubic splines.
+
+    Uses inverse mapping: to shift content by (+dy, +dx), sample from
+    (y-dy, x-dx).
+
+    Args:
+        image: 2D input image.
+        shift_y: Shift in Y direction (pixels). Positive = Down.
+        shift_x: Shift in X direction (pixels). Positive = Right.
+        order: Interpolation order (3 = cubic splines).
+        mode: Boundary handling mode.
+        cval: Value for 'constant' mode outside boundaries.
+
+    Returns:
+        Shifted image with same shape as input.
+    """
+    ny, nx = image.shape
+    y_grid, x_grid = jnp.mgrid[:ny, :nx]
+    coords = [y_grid - shift_y, x_grid - shift_x]
+    return map_coordinates(image, coords, order=order, mode=mode, cval=cval)
+
+
+@functools.partial(jax.jit, static_argnames=["shape_tgt"])
+def resample_flux(
+    f_src: jax.Array,
+    pixscale_src: float,
+    pixscale_tgt: float,
+    shape_tgt: tuple[int, int],
+    rotation_deg: float = 0.0,
+) -> jax.Array:
+    """Resample an image onto a new grid while conserving total flux.
+
+    Performs an affine transformation (rotation and scaling) to map
+    the source image onto a target grid. Converts to surface brightness,
+    interpolates, then converts back to integrated flux per pixel.
+
+    Args:
+        f_src: Source image (2D) with integrated flux per pixel.
+        pixscale_src: Pixel scale of source image.
+        pixscale_tgt: Pixel scale of target image (same units as src).
+        shape_tgt: Target shape (ny_tgt, nx_tgt).
+        rotation_deg: CCW rotation angle in degrees.
+
+    Returns:
+        Resampled image with total flux conserved. Shape: (ny_tgt, nx_tgt).
+    """
+    ny_src, nx_src = f_src.shape
+    ny_tgt, nx_tgt = shape_tgt
+
+    # Surface brightness (flux per unit area)
+    s_src = f_src / (pixscale_src**2)
+
+    # Affine matrix (TARGET pixel centres -> SOURCE coordinates)
+    scale = pixscale_tgt / pixscale_src
+    a_mat = ccw_rotation_matrix(rotation_deg) * scale
+
+    c_src = jnp.array([(ny_src - 1) / 2.0, (nx_src - 1) / 2.0])
+    c_tgt = jnp.array([(ny_tgt - 1) / 2.0, (nx_tgt - 1) / 2.0])
+    offset = c_src - a_mat @ c_tgt
+
+    # Grid of TARGET pixel centres
+    y_coords = jnp.arange(ny_tgt)
+    x_coords = jnp.arange(nx_tgt)
+    y_tgt, x_tgt = jnp.meshgrid(y_coords, x_coords, indexing="ij")
+
+    # (2, ny_tgt, nx_tgt)
+    coords = jnp.stack([y_tgt, x_tgt], axis=0)
+    coords_src = (a_mat @ coords.reshape(2, -1) + offset[:, None]).reshape(coords.shape)
+
+    # Interpolate surface brightness
+    s_tgt = map_coordinates(
+        s_src, [coords_src[0], coords_src[1]], order=3, mode="constant", cval=0.0
+    )
+
+    # Back to integrated flux per target pixel
+    return s_tgt * (pixscale_tgt**2)