Metadata-Version: 2.4
Name: PyAETNA
Version: 4.0.0
Summary: Python Accelerated Exoplanet Toolkit and Noise Analysis - JAX-accelerated joint modelling of exoplanet light curves and radial velocities
Author-email: Gaetano Scandariato <gaetano.scandariato@inaf.it>
License-Expression: MIT
Project-URL: Homepage, https://www.ict.inaf.it/gitlab/gaetano.scandariato/pyaetna
Project-URL: Documentation, https://www.ict.inaf.it/gitlab/gaetano.scandariato/pyaetna/-/tree/main/docs
Project-URL: Repository, https://www.ict.inaf.it/gitlab/gaetano.scandariato/pyaetna.git
Project-URL: Issues, https://www.ict.inaf.it/gitlab/gaetano.scandariato/pyaetna/-/issues
Keywords: exoplanets,astronomy,mcmc,bayesian,jax,numpyro,transit,phase-curve
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Astronomy
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: jax<0.12,>=0.7
Requires-Dist: jaxlib<0.12,>=0.7
Requires-Dist: equinox>=0.11
Requires-Dist: jaxoplanet>=0.1.0
Requires-Dist: numpyro>=0.22.0
Requires-Dist: numpy>=2.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: astropy>=5.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: pyyaml>=5.4.0
Requires-Dist: corner>=2.2.0
Requires-Dist: tqdm>=4.62.0
Requires-Dist: dill>=0.3.0
Requires-Dist: tinygp>=0.3.0
Requires-Dist: beartype>=0.18.0
Requires-Dist: blackjax>=1.6.2
Requires-Dist: optax>=0.2.4
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=3.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: mypy>=1.10; extra == "dev"
Requires-Dist: types-PyYAML>=6.0; extra == "dev"
Requires-Dist: pre-commit>=3.0; extra == "dev"
Provides-Extra: gpu
Requires-Dist: jax[cuda12]; extra == "gpu"
Dynamic: license-file

<div align="center">
  <img src="logo.jpg" alt="PyAETNA Logo" width="400"/>
  
  <!-- # PyAETNA -->
  
  **Python Accelerated Exoplanet Toolkit and Noise Analysis**
  
  A JAX-based Bayesian framework for modeling and analyzing exoplanet light curves and radial velocities with advanced systematics treatment.

**Version:** 4.0.0

**Release note (v3.7.0):** named priors and cross-section parameter tying
implemented via a top-level `priors:` section and `@name` references.
  
  [![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  
</div>

---

## What's PyAETNA?

PyAETNA is a configuration-driven pipeline that fits transit and phase-curve light curves, radial velocities and
transit timing variations in a Bayesian framework, on a CPU or a GPU. It is built on JAX, NumPyro and BlackJAX; one
YAML file describes the whole analysis, and the same model runs unchanged on any device. Instrument systematics are
handled with polynomials, Fourier series or Gaussian processes, and a run ends with diagnostic reports ready to read.

### Features

- **Models**: transits, secondary eclipses and phase curves (with hotspot offset, ellipsoidal variation and Doppler
  beaming), the Rossiter–McLaughlin effect, Keplerian radial velocities, and free transit times (TTVs)
- **Systematics and noise**: polynomials, Fourier series, errors-in-variables detrending, Gaussian processes
  (including multi-dimensional ones shared between light curves and activity indicators), white and correlated noise
- **Joint fits**: several instruments and data types at once, with shared orbital parameters and independent
  systematics; parameters can be shared across components through named priors
- **Bayesian inference**: nested sampling, which returns the posterior and the Bayesian evidence for model
  comparison, and the NUTS and ensemble samplers for parameter estimation; you choose the sampler, and a peak search
  before sampling checks that the posterior has a single peak (or hands you one configuration per peak)
- **Reports and derived physics**: PDF reports with fits, residuals, corner and trace plots, periodograms and goodness
  of fit, and the physical quantities derived from the posterior (stellar and planetary properties, energy balance,
  albedos)
- **Reproducible and restartable**: checkpointed runs, portable result files, full provenance of every run

## Why Use PyAETNA?

> **Evidence-based model comparison and realistic noise models on a laptop.** On a consumer GPU, a joint fit of
> K2-140 with its Bayesian evidence takes under a minute (56 s), and one GPU-day holds about 1500 such fits.

- **One file, one command.** The data, priors, systematics, sampler and post-processing are set in a single readable
  configuration file, which an [online configurator](http://pyaetna-e92eeb.pages.ict.inaf.it/) can write for you; no
  scripting is needed, and a run ends with the reports ready to read.
- **Fast on a GPU, even a consumer one.** The forward model and its derivatives are compiled with JAX and evaluated
  on many points at once. On a laptop GPU, PyAETNA fits K2-140 2.1 times faster than juliet and 1.6 times faster than
  PyORBIT (each running on the CPUs of the same laptop), and 3.1 to 137 times faster than allesfitter. Sixteen pairs of
  runs of the two Pi Men models, with evidences, take 16 minutes against an estimated 35 hours for allesfitter. The
  same configuration also runs on CPUs: it is 1.7 to 50 times faster than allesfitter there, and 1.2 times faster than
  pyaneti with the same MCMC.
- **Evidences you can compare.** Its nested sampler returns the evidence together with the posterior, with a bias of
  0.1 to 0.2 nats on near-Gaussian posteriors, against 0.7 to 1.5 nats for dynesty, and within 0.5 nats of a
  reference nested sampler on the benchmark data. That makes it affordable to compute the evidence of every candidate
  model and to repeat it over seeds.
- **Realistic noise, at no extra setup.** Single, per-visit and multi-dimensional Gaussian processes, and
  errors-in-variables detrending, run inside the same compiled likelihood; the quasiseparable GP solver handles
  10⁵ points on a laptop GPU, and PLATO-length transit light curves are tractable on one.
- **Agrees with the established codes.** On the published data sets of juliet, allesfitter, pyaneti and PyORBIT,
  posterior medians agree within 0.7 sigma for almost all parameters, and injection-and-recovery tests give 68 % and
  95 % intervals that contain the true value in 69 % and 96 % of the cases.
- **Reproducible and robust.** Numerical precision is chosen automatically where it matters (transit times), runs
  resume after a crash, and results are plain `.npz` and `.json` files with their provenance, readable with NumPy
  alone.

For the cases where other codes are faster or better (CPU-only runs against juliet and PyORBIT, separate posterior
peaks) and for every number above, see **[How PyAETNA compares with other codes](docs/benchmarks.md)**.

## Quick Start

### Installation

```bash
# Clone the repository
git clone https://www.ict.inaf.it/gitlab/gaetano.scandariato/pyaetna.git
cd pyaetna

# Create a virtual environment (an isolated, disposable copy of Python for this project)
python -m venv pyaetna-env
source pyaetna-env/bin/activate  # On Windows: pyaetna-env\Scripts\activate

# Install PyAETNA — this reads pyproject.toml and pulls in every dependency it needs
pip install --upgrade pip
pip install -e .
```

Check the installation with the quickstart example, a one-planet RV fit by
nested sampling that takes about 20 s on a laptop CPU, report included:

```bash
cd examples && pyaetna quickstart.yaml   # outputs in examples/PyAETNAouts/quickstart_*
```

That's the whole install for CPU use. On a Linux machine with an NVIDIA GPU,
`pip install -e ".[gpu]"` instead also installs JAX's CUDA 12 wheels, which
bring their own CUDA libraries (no system CUDA toolkit is needed). For GPU support, platform-specific
notes (Linux/macOS/Windows), troubleshooting, and everything else about
setting up your environment, see the
**[Installation & Environment Guide](docs/dependencies.md)** — it's written
for first-time Python users and experienced developers alike.

### Running an Example

Installing PyAETNA adds a `pyaetna` command:

```bash
pyaetna examples/test_rv_only.yaml          # one configuration
pyaetna examples/test_rv_only.yaml examples/test_lc_only.yaml   # several, in turn
python -m PyAETNA examples/test_rv_only.yaml    # equivalent, if the command is not on PATH
```

This runs the example configured in `examples/test_rv_only.yaml`. The data file
(`data.working_dir` / `data.file_path` in the YAML) is looked up relative to the
configuration file, and results are written to `PyAETNAouts/` next to it.

For detailed examples of calling PyAETNA from Python code, see the
[programmatic usage guide](docs/programmatic_usage.md).

## Documentation

PyAETNA is presented in the software paper Scandariato et al. (in preparation). Additional documentation is available at the following pages:

- **[How PyAETNA compares with other codes](docs/benchmarks.md)** - Speed, evidence reliability and agreement with juliet, allesfitter, pyaneti and PyORBIT, with the cases where other codes are better

- **[Installation & Environment Guide](docs/dependencies.md)** - Everything about setting up PyAETNA
  - Installation instructions (CPU and GPU)
  - Platform-specific notes (Linux, macOS, Windows)
  - Version compatibility and troubleshooting
  - Conda and Docker alternatives

- **[Configuration Guide](docs/config/index.md)** - Complete reference for all YAML configuration fields
  - Samplers (nested sampling, NUTS, ensemble samplers), the peak search and convergence targets
  - Prior distributions (uniform, normal, truncnorm, lognormal, beta)
  - Detrending options (polynomials, Fourier, Gaussian Processes)
  - Best practices and troubleshooting

- **[Online configurator](http://pyaetna-e92eeb.pages.ict.inaf.it/)** - Write or edit a configuration file in the browser
  - The INAF Pages server does not offer HTTPS yet; if your browser or network refuses plain HTTP, open `docs/config-generator.html` from a copy of the repository (cloned, or downloaded over HTTPS from the repository page): it is a single static page and works offline

- **[Output & Diagnostics](docs/outputs/index.md)** - What a run writes and how to read it
  - The run log, the results and sample files, the peaks of the posterior and the PDF reports
  - Guides to [reading the run log](docs/outputs/run_log.md) and [the PDF reports](docs/outputs/report.md)
  - Loading the results without PyAETNA

Additional resources:
- Test files in `tests/`
- Inline documentation and docstrings in source code

## Contributing

Contributions are very welcome! Whether you are fixing a bug, adding a new physics or detrending model, improving performance, or enhancing the documentation, your help is appreciated.

Before changing the models or the samplers, read the [notes for developers](docs/developer_notes.md): the
numerical-precision constraints, the workarounds for upstream faults, and how to test a change with both samplers.

### Setting Up a Development Environment

Fork and clone the repository, then follow the
[Development Environment](docs/dependencies.md#development-environment)
section of the Installation & Environment Guide — it walks through creating
the environment, installing the `dev` extra (`pytest`, `ruff`, `black`,
`mypy`), and enabling `pre-commit`.

### Code Style & Quality Standards

PyAETNA enforces automated code formatting, linting, and static type safety:

- **Formatting (`black`)**: Code must conform to Black's standard style (line length 88). Check and format with:
  ```bash
  black PyAETNA/ tests/
  ```
- **Linting (`ruff`)**: Code must pass Ruff linter checks cleanly. Check with:
  ```bash
  ruff check PyAETNA/ tests/
  ```
- **Static Type Checking (`mypy`)**: Function signatures should include Python type hints (`from __future__ import annotations`). Verify static types with:
  ```bash
  mypy PyAETNA/
  ```
- **Runtime Type Checks (`beartype`)**: Public API and configuration entry points use `@beartype` to enforce contract safety for user inputs.
- **Unit & Integration Tests (`pytest`)**: Always verify the test suite passes before submitting a Pull Request:
  ```bash
  pytest tests/ -v
  ```

### Submitting a Pull Request

1. Create a feature branch off `main` (`git checkout -b feat/your-feature-name`).
2. Implement your changes along with corresponding unit tests in `tests/`.
3. Verify that `black`, `ruff`, `mypy`, and `pytest` all pass locally.
4. Commit your work with concise, descriptive commit messages and open a Pull Request.

## Citation

If you use PyAETNA in your research, please add the following citation in your publication:

#TODO add bibtex citation to PyAETNA

Please also cite the relevant works
listed in [docs/CITATIONS.md](docs/CITATIONS.md). For your convenience, at the end of every run the
log prints a tailored list of references based on the modules and
features activated in your analysis, together with a pointer to the
BibTeX entries.

## License

This project is licensed under the MIT License — see the [LICENSE](LICENSE) file.

## Contact

gaetano.scandariato [at] inaf.it
