Commit 205917ae authored by Gaetano Scandariato's avatar Gaetano Scandariato
Browse files

docs: README 'Why use PyAETNA?' lists the advantages only, with the numbers of the paper

parent ee740772
Loading
Loading
Loading
Loading
Loading
+26 −14
Changes for README.md: 26 added lines, 14 removed lines.
Original line number Diff line number Diff line
@@ -44,22 +44,34 @@ handled with polynomials, Fourier series or Gaussian processes, and a run ends w

## 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.
- **Fast, on a laptop or a server.** The forward model and its derivatives are compiled with JAX and evaluated
  on many points at once, so the same configuration runs on a CPU or, faster, on a GPU. On the benchmark problems
  PyAETNA was much faster than allesfitter and faster than pyaneti with the same MCMC.
- **Trustworthy evidence.** On problems of known evidence, its nested sampler biases the Bayesian evidence several
  times less than dynesty, and the bias cancels in the Bayes factor between models.
- **Honest about its limits.** Its nested sampler needs more likelihood evaluations than juliet's or PyORBIT's, so it
  is slower than they are on a CPU, and it keeps only one of several separate peaks, which the peak search before
  sampling warns of. The numbers, with the cases where other codes are better, are in
  **[How PyAETNA compares with other codes](docs/benchmarks.md)**.
- **Agrees with the established codes.** On shared data sets, its posteriors match those of juliet, allesfitter,
  pyaneti and PyORBIT.
- **Transparent and robust.** Numerical precision is handled automatically where it matters (transit times), runs
  resume after a crash, and results are plain `.npz` and `.json` files that open with NumPy alone.
  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