PyAETNA 4.0.0

---

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 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.

Quick Start

Installation

# 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:

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 — it's written for first-time Python users and experienced developers alike.

Running an Example

Installing PyAETNA adds a pyaetna command:

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.

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 - Speed, evidence reliability and agreement with juliet, allesfitter, pyaneti and PyORBIT, with the cases where other codes are better

• Installation & Environment Guide - 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 - 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 - 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 - 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 and the PDF reports
  • 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: 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 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:

  black PyAETNA/ tests/
  

• Linting (ruff): Code must pass Ruff linter checks cleanly. Check with:

  ruff check PyAETNA/ tests/
  

• Static Type Checking (mypy): Function signatures should include Python type hints (from __future__ import annotations). Verify static types with:

  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:

  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. 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 file.

Contact

gaetano.scandariato [at] inaf.it