POSEIDON's documentation
====================================

POSEIDON is a Python package designed to rapidly retrieve atmospheric properties 
from exoplanet spectra. POSEIDON includes modelling capabilities to 
generate 1D, 2D, or 3D exoplanet transmission spectra (`TRIDENT 
<https://ui.adsabs.harvard.edu/abs/2021arXiv211105862M/abstract>`_) alongside emission 
and/or reflection spectra for substellar atmospheres. For fitting observed spectra 
('atmospheric retrieval'), POSEIDON uses a nested sampling retrieval 
framework, via the sampling algorithm `PyMultiNest <https://johannesbuchner.github.io/PyMultiNest/>`_,
to explore the range of allowed atmospheric properties.

POSEIDON's official features currently include:

* Transmission spectra modelling and retrievals for 1D, 2D, and 3D exoplanet atmospheres.
* Emission and reflection spectra, including scattering, for modelling and retrievals.
* Rapid atmospheric retrievals that can run on your laptop.
* Model planets ranging from ultra-hot Jupiters to temperate terrestrials.
* Parametric prescriptions for stellar contamination, multidimensional clouds, and more.
* High-resolution line-by-line models (:math:`R \sim 10^6`) for cross correlation analyses.
* Modelling and retrievals for brown dwarfs and directly imaged exoplanets.
* High-resolution cross correlation retrievals for ground-based exoplanet datasets.
* NEW: surface thermal emission and reflection retrievals for rocky planets.


POSEIDON contains an extensive range of tutorials covering forward models and 
retrievals for a wide variety of different applications.


New in POSEIDON v1.4:
------------------------------------

* Inclusion of surfaces with wavelength-dependent albedos for thermal emission and reflection spectra.
* An extensive database of lab-measured surface albedos with detailed documentation. 
* New tutorials illustrating rocky planet thermal emission and reflection spectra for JWST and HWO.
* New tutorial illustrating stellar contamination in transmission.

For a comprehensive list of new features, see the POSEIDON `Release Notes 
<https://github.com/MartianColonist/POSEIDON/releases>`_ on GitHub.

To use the new surface reflection features, you will need to re-download the POSEIDON input data.
Please see the installation instructions.

New in POSEIDON v1.3:
------------------------------------

* High-resolution cross correlation retrievals for transmission and emission spectra.
* New tutorials illustrating applications of cross correlations and high-resolution retrievals to WASP-121b and WASP-77 Ab.

New in POSEIDON v1.2:
------------------------------------

* Mie scattering aerosols for exoplanet forward models and retrievals.
* An extensive database of pre-computed aerosol optical properties covering the full range of substellar atmospheres.
* New `opacity database <content/opacity_database.html>`_ with state-of-the-art molecular line lists.
* Emission and reflection spectra, including scattering, for modelling and retrievals.
* Many new tutorials.

New in POSEIDON v1.1:
------------------------------------

* Chemical equilibrium models and retrievals, demonstrated in two new tutorials.
* JWST proposal tutorial (PandExo + retrieving simulated JWST data).  
* Bayesian model comparison demonstration in first retrieval tutorial.
* Improved stellar contamination retrieval capabilities (e.g. spots + faculae).


Contributor Hall of Fame:
------------------------------------

* Ryan MacDonald (Lead Developer) --- Ryan.MacDonald@st-andrews.ac.uk
* Elijah Mullens (Aerosols, emission with scattering, and reflection spectra)
* Ruizhe Wang (High-resolution cross correlation retrievals and equilibrium chemistry)
* Charlotte Fairman (Contributor)
* John Kappelmeier (Contributor)
* Aiden Zelakiewicz (HWO reflection tutorial)


.. toctree::
   :maxdepth: 1
   :caption: Installation:

   content/installation

.. toctree::
   :maxdepth: 2
   :caption: Guide:

   content/forward_model_tutorials
   content/retrieval_tutorials
   content/opacity_database

.. toctree::
   :maxdepth: 2
   :caption: Code Documentation:

   content/citations
   content/contributing
   content/poseidon_papers
   autoapi/index


License:
------------------------------------

POSEIDON is available under the BSD 3-Clause License. If you use POSEIDON,
please cite `MacDonald & Madhusudhan (2017) 
<https://ui.adsabs.harvard.edu/abs/2017MNRAS.469.1979M/abstract>`_ and 
`MacDonald (2023) <https://ui.adsabs.harvard.edu/abs/2023JOSS....8.4873M/abstract>`_. 
Guidance on specific papers to cite for individual features included within 
POSEIDON is provided on the page `"What to Cite" <content/citations.html>`_.