Metadata-Version: 2.4
Name: zodi
Version: 0.1.0
Summary: Zodiacal and exozodiacal light brightness conventions with a single-source numpy/JAX core
Project-URL: Repository, https://github.com/CoreySpohn/zodi
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.11
Requires-Dist: array-api-compat>=1.9
Requires-Dist: numpy
Provides-Extra: dev
Requires-Dist: pre-commit; extra == 'dev'
Provides-Extra: docs
Requires-Dist: myst-nb; extra == 'docs'
Requires-Dist: sphinx-autoapi; extra == 'docs'
Requires-Dist: sphinx-book-theme; extra == 'docs'
Provides-Extra: jax
Requires-Dist: jax>=0.4.32; extra == 'jax'
Requires-Dist: jaxlib>=0.4.32; extra == 'jax'
Provides-Extra: test
Requires-Dist: hypothesis; extra == 'test'
Requires-Dist: pytest; extra == 'test'
Description-Content-Type: text/markdown

# zodi

Zodiacal and exozodiacal light brightness conventions for exoplanet imaging,
from a single source that runs on numpy and JAX.

Status: v0.1 core (pre-PyPI). The LBTI HOSTS population distributions land
next.

## What it owns

- Local zodiacal light surface brightness: the Leinert et al. (1998)
  Table 17 position dependence and Table 19 wavelength dependence, with the
  interpolation, anchoring, and near-Sun conventions of the production
  codes stated explicitly (`zodi.specific_intensity`, `zodi.zodi_flux_ratio`).
- The exozodi chain of Stark et al. (2014) as implemented by EXOSIMS
  (`zodi.exozodi_flux_ratio_v`, `zodi.jez0`, `zodi.scale_jez`), the three
  published latitudinal models (`zodi.latitudinal_factor`), and the
  grey-scatterer band correction in both production flavors: the
  stellar-color scaling used by pyEDITH (`zodi.exozodi_flux_ratio_band`)
  and the scattered-plus-thermal spectrum model used by EXOSIMS, with its
  calibration as a closed-form least-squares fit
  (`zodi.fit_grey_scatter_constants`).
- Unit conversions between the dialects in common use: magnitudes per
  square arcsecond, flux ratio per square arcsecond, spectral radiance,
  photon rates, and MJy per steradian (`zodi.units`).

Coming next: the LBTI HOSTS survey n-zodi population distributions as
quantile functions (callers supply their own uniform draws).

## Documentation and validation

`docs/conventions.md` states every model, constant, and known cross-code
difference with sources and measured deltas; `docs/validation.md` maps
each claim to an executable check. Cross-validation scripts against
EXOSIMS, skyscapes, and zodipy live in `scripts/` and are runnable by
anyone with those packages installed. Current results: exact agreement
with the EXOSIMS closed-form models and magnitude chain, float64
round-off agreement with skyscapes, and 0.95-1.23 brightness ratios
against the independent Kelsall model at 1.25 um.

## Design

One implementation serves both backends through the array API standard.
Functions compute in the namespace of their array inputs (via
`array-api-compat`), so numpy callers get numpy in and numpy out with no JAX
anywhere in their dependency tree, while JAX callers get functions that jit,
vmap, and differentiate natively. Hard dependencies are `numpy` and
`array-api-compat` only; the `[jax]` extra exists so the test suite can run
the JAX side. JAX users should enable float64:

```python
jax.config.update("jax_enable_x64", True)
```

Random sampling is deliberately absent from the library: distributions ship
as quantile functions (inverse CDFs), and callers bring uniforms from their
own generator, whether that is `numpy.random` or `jax.random`.

## Not this library

Structured circumstellar disks (rings, gaps, offsets) and scene rendering
belong to scene simulators; solar-system ephemerides belong to the caller.
For thermal-infrared zodiacal emission modeling, see
[zodipy](https://github.com/Cosmoglobe/zodipy); this library covers the
reflected-light brightness conventions used in exoplanet direct imaging.

## Install

PyPI release pending; for now:

```
pip install git+https://github.com/CoreySpohn/zodi.git
```
