Remove files matched by .gitignore from tracking

---

name: code_quality

description: Mandatory PEP 8, Ruff, Black, and testing rules for PyAETNA development

---

# PyAETNA Code Quality Rules

When developing, refactoring, or generating code for PyAETNA in Antigravity:

1. **Python Environment**:

   Always execute commands using `/dati/pyenvs/pyaetnaEnv/bin/python`.

2. **Formatting & Quality Compliance**:

   - Strictly follow the `pyproject.toml` configuration for `ruff` and `black`.

   - Never introduce code that violates `ruff check PyAETNA/ tests/`.

   - Ensure all unit tests pass with `/dati/pyenvs/pyaetnaEnv/bin/pytest tests/`.

3. **Pre-Commit Verification**:

   Verify that `git commit` passes the installed `.pre-commit-config.yaml` pre-commit hooks.

# PyAETNA AI Agent & Coding Guidelines

All AI agents (GitHub Copilot, VS Code Copilot, Antigravity, Claude Code, Cursor, etc.) working on the PyAETNA codebase **MUST** strictly adhere to the following environment and code quality requirements:

## 1. Python Environment

- Always use the dedicated virtual environment:

  `/dati/pyenvs/pyaetnaEnv/bin/python`

- Executable paths for tooling:

  - Python: `/dati/pyenvs/pyaetnaEnv/bin/python`

  - Ruff: `/dati/pyenvs/pyaetnaEnv/bin/ruff`

  - Black: `/dati/pyenvs/pyaetnaEnv/bin/black`

  - Pytest: `/dati/pyenvs/pyaetnaEnv/bin/pytest`

## 2. Code Quality & Formatting Enforcement

- **PEP 8 / Formatting**: All Python code edits must pass `ruff check` and `black --check`.

- **Ruff Linter**: All lint warnings configured in `pyproject.toml` must be resolved before completing a task.

- **Verification Command**: Before submitting any code changes or completing a task, always run:

  ```bash

  /dati/pyenvs/pyaetnaEnv/bin/ruff check PyAETNA/ tests/

  /dati/pyenvs/pyaetnaEnv/bin/pytest tests/

  ```

## 3. Code Standards & Rules

- Do NOT use single-character ambiguous variable names (e.g. `l`, `O`, `I`).

- Use flattened control structures (`if a and b:`) rather than nested `if` blocks.

- Prefix unused loop control variables with an underscore (e.g. `_inst_id`).

- Ensure all public functions and re-exported APIs in `__init__.py` or module roots are properly declared in `__all__`.

# PyAETNA Development & Quality Rules for AI Assistants

- **Python Environment**: `/dati/pyenvs/pyaetnaEnv/bin/python`

- **Linting & Formatting**: Follow `pyproject.toml` (`ruff check` and `black --check`).

- **Pre-commit**: Pre-commit hook is active in `.git/hooks/pre-commit`.

- **Validation**: Run `/dati/pyenvs/pyaetnaEnv/bin/ruff check PyAETNA/ tests/` and `/dati/pyenvs/pyaetnaEnv/bin/pytest tests/` before completing tasks.

Metadata-Version: 2.4

Name: PyAETNA

Version: 3.7.0

Summary: Python Astronomical Exoplanet Transit and Nuisance Analysis - JAX-accelerated exoplanet light curve modeling

Author-email: Gaetano Scandariato <gaetano.scandariato@inaf.it>

License: MIT

Project-URL: Homepage, https://github.com/gaetanoscandariato/PyAETNA

Project-URL: Documentation, https://github.com/gaetanoscandariato/PyAETNA/tree/main/docs

Project-URL: Repository, https://github.com/gaetanoscandariato/PyAETNA.git

Project-URL: Issues, https://github.com/gaetanoscandariato/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.10

Classifier: Programming Language :: Python :: 3.11

Classifier: Programming Language :: Python :: 3.12

Classifier: Programming Language :: Python :: 3.13

Requires-Python: >=3.10

Description-Content-Type: text/markdown

License-File: LICENSE

Requires-Dist: jax>=0.4.0

Requires-Dist: jaxlib>=0.4.0

Requires-Dist: jaxoplanet>=0.1.0

Requires-Dist: numpyro>=0.13.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

Provides-Extra: dev

Requires-Dist: pytest>=7.0.0; extra == "dev"

Requires-Dist: pytest-cov>=3.0.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 Astronomical Exoplanet Toolkit and Nuisance Analysis**

  A JAX-based Bayesian framework for modeling and analyzing exoplanet light curves and radial velocities with advanced systematics treatment.

**Version:** 3.7.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 flexible, configuration-driven pipeline for fitting

transit, phase‑curve light curves and radial velocities using a Bayesian

framework with high-performance JAX/NumPyro sampling.  It handles

instrument-specific systematics via polynomials, Fourier series, or

Gaussian processes, and produces high-quality diagnostic reports

with minimal user effort.

### Features

- **JAX/NumPyro Backend**: JIT-compiled, GPU-accelerated MCMC sampling

- **Flexible MCMC Sampling**:

  - NUTS (gradient-based, default)

  - AIES and ESS ensemble samplers (gradient-free)

  - Automatic multimodal detection and restart strategies

- **Named Priors & Global Tying**: tie parameters across different model components (e.g., sharing a stellar rotation period between multiple instrument and corresponding detrending schemes)

- **Comprehensive Light Curve Modeling**:

  - Primary transits, phase curves and secondary eclipses (via `jaxoplanet`)

  - **Transit Timing Variations (TTV)**: per-epoch free transit times with O−C posterior

  - Phase curves with hotspot offsets (Lambert sphere)

  - Ellipsoidal variations with tidal lag

  - Doppler beaming

- **Flexible Systematics Treatment**:

  - Polynomial detrending

  - Fourier series

  - Gaussian Processes (tinygp with O(N) and O(N³) kernels)

- **Robust Uncertainty Quantification**: 

  - White noise and red noise components

  - Correlated noise modeling

  - Confidence bands from posterior samples

## Why Use PyAETNA?

- **Single YAML, complete analysis.** Define data paths, priors,

  systematics, MCMC strategy, and post-processing physics in one

  human-readable configuration file — no boilerplate Python scripts required.

- **GPU-accelerated end-to-end.** The entire forward model, likelihood, and

  gradient computation runs inside JIT-compiled JAX, delivering order-of-

  magnitude speedups on GPU/TPU hardware without code changes.

- **Adaptive three-phase sampling.** The pipeline manages warmup and

  production automatically, with ensemble warmup (ESS or AIES) for

  exploration and NUTS for efficient local convergence. Warmup and

  production behavior is still highly configurable in the YAML file (sampler

  choice, number of chains, adaptation schedule, etc.).

- **Checkpointed, restartable runs.** MCMC state is periodically pickled so

  that long runs can survive crashes, and subsequent launches resume exactly

  where they left off — including the ensemble warmup phase.

- **Mixed-precision ephemeris firewall.** Transit mid-times are folded in

  float64 while the rest of the model evaluates in float32 for speed,

  eliminating the catastrophic cancellation that plagues naïve

  single-precision transit fits.

- **Rich systematics toolkit.** Polynomial trends, Fourier series, and

  scalable Gaussian Processes (O(N) quasiseparable or O(N³) dense kernels

  via tinygp) can be combined freely, scoped per-visit or per-instrument,

  and stacked on the same dataset.

- **Joint multi-instrument, multi-type fitting.** Photometric light curves

  and radial velocities from different instruments are modelled

  simultaneously with fully shared orbital parameters and independent

  per-instrument systematics.

- **High-quality and informative plots.** Diagnostic PDFs include phase-folded fits

  with residuals, best-fit models per visit, corner plots, trace plots,

  Lomb–Scargle periodograms, and an optional physics report with Cowan &

  Agol energy-balance, brightness temperatures, and passband-integrated

  albedos to clearly check the outcome of model exploration.

- **Physics post-processing in one step.** A dedicated `physics:` stage

  derives limb-darkening coefficients, orbital geometry, equilibrium

  temperatures, Bond albedos, and heat redistribution efficiencies —

  propagating full MCMC uncertainties via Monte Carlo resampling.

- **Model-atmosphere support.** BT-Settl and PHOENIX synthetic spectra are

  downloaded on the fly (with local caching) for passband-integrated

  brightness-temperature inversion, replacing the default blackbody

  approximation with no additional libraries to install.

## Quick Start

### Installation

```bash

# Clone the repository

git clone <repository-url>

cd PyAETNA

# Create virtual environment (recommended)

python -m venv pyaetna

source pyaetna/bin/activate  # On Windows: pyaetna\Scripts\activate

# Install dependencies

pip install "jax[cpu]" numpyro jaxoplanet numpy scipy astropy matplotlib pyyaml corner tqdm dill tinygp

# Install PyAETNA in development mode

pip install -e .

```

For detailed installation instructions including GPU support, see [Dependencies Guide](docs/dependencies.md).

### Running an Example

```bash

# Run with default configuration

python runPyAETNA.py

# Or specify a configuration file with .yaml extension

python runPyAETNA.py tests/test_rv_only.yaml

```

This will run the example using configuration from `tests/test_rv_only.yaml` and data files specified in the YAML configuration.

For detailed examples of calling PyAETNA from Python code, see the

[programmatic usage guide](docs/programmatic_usage.md).

## Documentation

Comprehensive documentation is available:

- **[Configuration Guide](docs/configuration.md)** - Complete reference for all YAML configuration fields

  - MCMC sampling strategies (NUTS, ensemble samplers AIES/ESS, multimodal detection)

  - Prior distributions (uniform, normal, truncnorm, lognormal, beta)

  - Detrending options (polynomials, Fourier, Gaussian Processes)

  - Best practices and troubleshooting

  A complete **online configurator** is available at http://pyaetna-e92eeb.pages.ict.inaf.it/.

- **[Dependencies Guide](docs/dependencies.md)** - Detailed information about software requirements

  - Installation instructions (CPU and GPU)

  - Platform-specific notes (Linux, macOS, Windows)

  - Version compatibility and troubleshooting

  - Conda and Docker alternatives

Additional resources:

- Test files in `tests/`

- Inline documentation in source code

## Repository Structure

```

PyAETNA/

├── runPyAETNA.py              # CLI entrypoint

├── pyproject.toml             # Packaging metadata and dependencies

├── requirements.txt           # Dependency pins (fallback)

├── README.md                  # This file

├── LICENSE                    # MIT licence

│

├── PyAETNA/                   # Core library package

│   ├── __init__.py            #   Package exports and __version__

│   ├── run.py                 #   Pipeline orchestrator (sampling → reports → physics)

│   ├── planet_phys.py         #   Derived physics (eclipse depths, albedo, Cowan & Agol)

│   ├── body_models.py         #   JAX planetary models (transit, eclipse, RV via jaxoplanet)

│   ├── gp.py                  #   GP kernel utilities (tinygp quasisep + dense)

│   ├── model_utils.py         #   Shared model assembly and detrending helpers

│   ├── _device_config.py      #   JAX device/platform auto-detection

│   ├── sampling/              #   Modular sampling engine and model assembly

│   │   ├── __init__.py        #     Public sampling API

│   │   ├── data.py            #     Input data structures and validation

│   │   ├── precision.py       #     JAX precision/casting helpers

│   │   ├── utils.py           #     Shared sampling math utilities

│   │   ├── model/             #     PlModel core + detrending + GP builders

│   │   ├── config/            #     Config parsing and prior handling

│   │   │   ├── priors.py      #       Prior string parsing and dist mapping

│   │   │   └── parser/        #       Scoped parser modules (star/planet/gp/...)

│   │   └── engine/            #     Sampling loop and NumPyro integration

│   │       ├── runner.py      #       runSampler_NumPyro main runner

│   │       ├── numpyro_model.py #     Model closure and log-joint helpers

│   │       ├── logging.py     #       Sampling log/summary formatters

│   │       ├── data_loader.py #       Resume-safe data loading utilities

│   │       ├── checkpoint.py  #       Checkpoint save/restore logic

│   │       ├── sampler_utils.py #     Shared runner helpers

│   │       └── utils/         #       Engine utility modules

│   ├── reporting/             #   Modular report-generation package

│   │   ├── __init__.py        #     Reporting package exports

│   │   ├── plot_models.py     #     Main plotting/report orchestration

│   │   ├── confidence_bands.py #    Posterior confidence band computations

│   │   ├── grid_builder.py    #     Grids for phase/time-domain plotting

│   │   ├── lightcurve_plots.py #    Light-curve plotting routines

│   │   ├── periodogram_plots.py #   Periodogram and PSD diagnostics

│   │   ├── phase_plots.py     #     Phase-folded visualization helpers

│   │   ├── residual_plotting.py #   Residual panels and KDE inset helpers

│   │   ├── corner_plot.py     #     Posterior corner plot generation

│   │   ├── diagnostics.py     #     MCMC and model diagnostics

│   │   ├── pdf_report.py      #     Multi-page PDF report assembly

│   │   └── ...                #     Additional plotting/support modules

│   └── scripts/               #   Auxiliary CLI scripts

│

├── docs/                      # Documentation

│   ├── configuration.md       #   Full YAML config reference

│   ├── configuration_keys.md  #   Quick-reference key table

│   ├── dependencies.md        #   Installation guide (CPU & GPU)

│   ├── programmatic_usage.md  #   Calling PyAETNA from Python

│   ├── phase_curve_physics.md #   Phase-curve theory, derivations, references

│   ├── ARCH_DECISIONS.md      #   Architecture rationale (vectorisation, precision)

│   ├── CITATIONS.md           #   Full reference list with BibTeX entries

│   └── gp_per_visit_analysis/ #   GP per-visit block-diagonal documentation

│

├── examples/                  # Example configurations and data

│   ├── reference_config.yaml  #   Annotated reference with EVERY supported key

│   ├── 501.yaml               #   CHEOPS dayside emission example

│   ├── transits.yaml          #   TESS transit-only example

│   ├── example_lc_rv_joint.yaml # Joint LC + RV example

│   └── *.dat                  #   Accompanying data files

│

├── tests/                     # Test suite

│   ├── generate_test_datasets.py # Synthetic data generator

│   ├── test_lc_only.yaml      #   LC-only test config

│   ├── test_rv_only.yaml      #   RV-only test config

│   ├── test_lc_rv_joint.yaml  #   Joint LC + RV test config

│   ├── test_lc_gp_rv.yaml    #   LC (GP) + RV test config

│   ├── test_gp_per_visit.yaml #   GP per-visit block-diagonal test

│   ├── test_phase_curve.yaml  #   Phase curve + RV test config

│   ├── test_exptime_integration.py # Exposure-time supersampling tests

│   └── *.dat                  #   Synthetic test data

│

└── localDocs/                 # Internal development notes (not shipped)

```

## Citation

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

#TODO add 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.

## TODO

- Test in pleiadi

- parse config file checking for the correctness of the priors and add logging if priors are not well defined

- check citations and include citation to PyAETNA

- improve online configurator

- remove lazy split-index fallback in planet model path and require precomputed static indices for strict end-to-end JAX/JIT compliance

- check the checkpoint_interval logic

- implement different limb darkening laws

- better arrangement of legends and text in plots

- remove double INFO messages in the log

## Contact

gaetano.scandariato [at] inaf.it

LICENSE

README.md

pyproject.toml

PyAETNA/__init__.py

PyAETNA/_device_config.py

PyAETNA/body_models.py

PyAETNA/gp.py

PyAETNA/model_utils.py

PyAETNA/planet_phys.py

PyAETNA/run.py

PyAETNA/version.py

PyAETNA.egg-info/PKG-INFO

PyAETNA.egg-info/SOURCES.txt

PyAETNA.egg-info/dependency_links.txt

PyAETNA.egg-info/requires.txt

PyAETNA.egg-info/top_level.txt

PyAETNA/kernels/factory.py

PyAETNA/oldCode/PyAETNA_JAXdistributions.py

PyAETNA/oldCode/PyAETNA_MCMCFunctions.py

PyAETNA/oldCode/PyAETNA_NormalizedGLS.py

PyAETNA/oldCode/PyAETNA_orbitModel.py

PyAETNA/oldCode/gsMCMCFunctions_v2.py

PyAETNA/oldCode/runPyAETNA.py

PyAETNA/oldCode/transitModelHANNU_v2.py

PyAETNA/reporting/__init__.py

PyAETNA/reporting/confidence_bands.py

PyAETNA/reporting/corner_plot.py

PyAETNA/reporting/data_validation.py

PyAETNA/reporting/diagnostics.py

PyAETNA/reporting/gp_plotting.py

PyAETNA/reporting/grid_builder.py

PyAETNA/reporting/grid_builder_utils.py

PyAETNA/reporting/lightcurve_plots.py

PyAETNA/reporting/logger.py

PyAETNA/reporting/map_search.py

PyAETNA/reporting/model_components.py

PyAETNA/reporting/model_math.py

PyAETNA/reporting/noise_plots.py

PyAETNA/reporting/panel_detrended.py

PyAETNA/reporting/panel_overlay.py

PyAETNA/reporting/panel_raw.py

PyAETNA/reporting/panel_residuals.py

PyAETNA/reporting/pdf_report.py

PyAETNA/reporting/periodogram_plots.py

PyAETNA/reporting/phase_plots.py

PyAETNA/reporting/plot_data_prep.py

PyAETNA/reporting/plot_models.py

PyAETNA/reporting/plot_styling.py

PyAETNA/reporting/residual_plotting.py

PyAETNA/reporting/trend_detection.py

PyAETNA/reporting/ttv_plots.py

PyAETNA/sampling/__init__.py

PyAETNA/sampling/data.py

PyAETNA/sampling/precision.py

PyAETNA/sampling/utils.py

PyAETNA/sampling/config/priors.py

PyAETNA/sampling/config/parser/__init__.py

PyAETNA/sampling/config/parser/detrending.py

PyAETNA/sampling/config/parser/gp.py

PyAETNA/sampling/config/parser/planets.py

PyAETNA/sampling/config/parser/prior_refs.py

PyAETNA/sampling/config/parser/scoping.py

PyAETNA/sampling/config/parser/star.py

PyAETNA/sampling/engine/checkpoint.py

PyAETNA/sampling/engine/data_loader.py

PyAETNA/sampling/engine/eiv.py

PyAETNA/sampling/engine/logging.py

PyAETNA/sampling/engine/numpyro_model.py

PyAETNA/sampling/engine/runner.py

PyAETNA/sampling/engine/sampler_utils.py

PyAETNA/sampling/engine/utils/logging_utils.py

PyAETNA/sampling/model/core.py

PyAETNA/sampling/model/detrending.py

PyAETNA/sampling/model/gp_models.py

PyAETNA/scripts/normalize_flux_by_visit.py

PyAETNA/scripts/plot_random_gp.py

tests/test_behavioral_ties.py

tests/test_eiv.py

tests/test_exptime_integration.py

tests/test_gp_per_visit.py

tests/test_prior_refs.py

tests/test_rm_effect.py

tests/test_spectral_mixture.py

tests/test_ttv.py

 No newline at end of file