PyAETNA 4.0.0__tar.gz

pyaetna-4.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gaetano Scandariato
+
+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.

pyaetna-4.0.0/PKG-INFO

@@ -0,0 +1,269 @@
+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

pyaetna-4.0.0/README.md

@@ -0,0 +1,218 @@
+<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

pyaetna-4.0.0/VERSION

@@ -0,0 +1 @@
+4.0.0