Merging all changes in the GPU branch (for some reason I couldn't get automatic merging working)

Author: ideasrule

README.md

@@ -5,8 +5,7 @@
 [![arXiv](http://img.shields.io/badge/arXiv-2004.09513-orange.svg)](https://arxiv.org/abs/2004.09513) 
 [![arXiv](http://img.shields.io/badge/arXiv-1811.11761-orange.svg)](https://arxiv.org/abs/1811.11761)
 
-**April 18, 2020: PLATON v5.1 corresponds most closely to the version described
-in our second PLATON paper (https://arxiv.org/abs/2004.09513).**
+**Oct 30, 2024: PLATON v6.2 is out, with major updates!  This corresponds most closely to the version described in Zhang et al 2024.  Major changes include GPU support, free retrievals, surface emission, higher-resolution (R=20k) and more up-to-date opacities, leave-one-out cross-validation, pymultinest, and much better plotting tools.**
 
 **February 2, 2020: PLEASE re-clone your repository if you cloned it before this
 date!  On this date, all data files were deleted from the repository, including

docs/conf.py

@@ -68,7 +68,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.

docs/eclipse_depths.rst

@@ -25,10 +25,13 @@ Then, call the eclipse depth calculator::
 
   from platon.eclipse_depth_calculator import EclipseDepthCalculator
   calc = EclipseDepthCalculator(method="xsec") #"ktables" for correlated k
-  wavelengths, depths = calc.compute_depths(p, Rs, Mp, Rp, Tstar)
+  wavelengths, depths, _ = calc.compute_depths(p, Rs, Mp, Rp, Tstar)
   
 Most of the same parameters accepted by the transit depth calculator are also
-accepted by the eclipse depth calculator.
+accepted by the eclipse depth calculator.  Surface emission can be included by
+passing surface_temp.  Only blackbody emission is supported at the moment, but
+non-blackbody emissivities (from new, state of the art lab data!) will be
+included in the next release (Paragas et al. 2024, in prep).
 
 It is also possible to retrieve on combined transit and eclipse depths::
 
@@ -41,7 +44,7 @@ It is also possible to retrieve on combined transit and eclipse depths::
   fit_info.add_uniform_fit_param(...)
   fit_info.add_uniform_fit_param(...)
 
-  result = retriever.run_multinest(transit_bins, transit_depths, transit_errors,
+  result = retriever.run_dynesty(transit_bins, transit_depths, transit_errors,
                                    eclipse_bins, eclipse_depths, eclipse_errors,
 				   fit_info,
 				   rad_method="xsec") #"ktables" for corr-k
@@ -50,4 +53,3 @@ Here, T_limb is the temperature at the planetary limb (used for transit depths),
 while the T-P profile parameters are for the dayside (used for eclipse depths).
 
 To do an eclipse-only retrieval, set transit_bins, transit_depths, and transit_errors to None, and likewise to do a transit-only retrieval.
-

docs/index.rst

@@ -5,6 +5,8 @@
 
 Welcome to PLATON's documentation!
 ==================================
+**Oct 30, 2024: PLATON v6.2 is out, with major updates!  This corresponds most closely to the version described in Zhang et al 2024.  Major changes include GPU support, free retrievals, surface emission, higher-resolution (R=20k) and more up-to-date opacities, leave-one-out cross-validation, pymultinest, and much better plotting tools.**
+
 **April 18, 2020: PLATON v5.1 corresponds most closely to the version described
 in our second PLATON paper.**
 
@@ -21,6 +23,7 @@ in our second PLATON paper.**
    quickstart
    mie_scattering
    eclipse_depths
+   surface_emission
    visualizer
    questions_and_answers
    source/modules

docs/install.rst

@@ -1,47 +1,29 @@
 Install
 *******
-
-Before installing PLATON, it is highly recommended to have a fast linear
-algebra library (BLAS) and verify that numpy is linked to it.  This is because
-the heart of the radiative transfer code is a matrix multiplication operation
-conducted through numpy.dot, which in turn calls a BLAS library if it can find
-one.  If it can't find one, your code will be many times slower.
-
-We recommend using Anaconda, which automatically installs BLAS libraries.
-If you don't want to use Anaconda, a good BLAS library to install on Linux is
-OpenBLAS.  You can install it on Ubuntu with::
+We highly recommend installing PLATON in a conda environment, which typically comes with optimized BLAS libraries.  Once in the conda environment::
   
-  sudo apt install libopenblas-dev
-
-On OS X, a good choice is Accelerate/vecLib, which should already be installed
-by default.
-
-To check if your numpy is linked to BLAS, do::
-
-  numpy.__config__.show()
+  git clone https://github.com/ideasrule/platon.git
+  cd platon/
+  pip install -e .
 
-If blas_opt_info mentions OpenBLAS or vecLib, that's a good sign.  If it says
-"NOT AVAILABLE", that's a bad sign.
+Doing "pip install -e ." instead of "pip install ." installs PLATON in-place instead of copying the source files somewhere else.  This way, you can modify the source code and have the changes reflected instantly.
 
-Once you have a BLAS installed and linked to numpy, download PLATON,
-install the requirements, and install PLATON itself.  Although it is possible
-to install PLATON using pip (pip install platon), the recommended method is to
-clone the GitHub repository and install from there.  This is because the
-repository includes examples, which you don't get when pip installing.
+PLATON 6.2 uses the GPU by default, and falls back on the CPU if it can't find one.  If you have a Nvidia GPU, we highly recommend that you install CUDA and cupy, which will speed up PLATON many-fold::
+  
+  conda install -c conda-forge cupy
 
-To install from GitHub::
+PLATON will automatically detect the existence of cupy and use the GPU.  You can force it to use the CPU by setting FORCE_CPU = True in _cupy_numpy.py.
 
-  git clone https://github.com/ideasrule/platon.git
-  cd platon/
-  python setup.py install
+PLATON supports both dynesty and pymultinest for nested sampling.  dynesty is installed by default.  To install pymultinest::
+  
+  conda install -c conda-forge mpi4py pymultinest
 
-You can run unit tests to make sure everything works::
+After installing PLATON, you can run unit tests to make sure everything works::
   
   nosetests -v 
 
 The unit tests should also give you a good idea of how fast the code will be.
 On a decent Ubuntu machine with OpenBLAS, it takes 3 minutes.
 
-The default data files (in platon/data) have a wavelength resolution of R=1000,
-but if you want higher resolution, you can download R=10,000 and
-R=375,000 data from `this webpage <http://astro.caltech.edu/~mz/absorption.html>`_
+The default data files (in platon/data) have a wavelength resolution of R=20k.
+If you want higher resolution, you can download higher-resolution opacities from the `DACE opacity database <https://dace.unige.ch/opacityDatabase>`_ and interpolate to PLATON's temperature and pressure grid.

docs/intro.rst

@@ -1,43 +1,28 @@
 Introduction
 ************
 
-PLATON (PLanetary Atmospheric Transmission for Observer Noobs) is a
+PLATON (PLanetary Atmospheric Tool for Observer Noobs) is a
 fast and easy to use forward modelling and retrieval tool for
-exoplanet atmospheres.  It is based on ExoTransmit by Eliza Kempton.
-The two main modules are:
+exoplanet atmospheres.  Its roots are in ExoTransmit by Eliza Kempton, but
+it has dramatically changed since then.
+
+The main modules are:
 
    1. :class:`.TransitDepthCalculator`: computes a transit spectrum for an
       exoplanet
    2. :class:`.EclipseDepthCalculator`: computes an eclipse spectrum   
    3. :class:`.CombinedRetriever`: can retrieve atmospheric properties for
       transit depths, eclipse depths, or a combination of the two.
 
-The transit spectrum is calculated from 300 nm to 30 um, taking into
-account gas absorption, collisionally induced gas absorption, clouds, 
-and scattering.  :class:`.TransitDepthCalculator` is written
-entirely in Python and is designed for performance. By default, it
-calculates transit depths on a fine wavelength grid (λ/Δλ = 1000 with
-4616 wavelength points), which takes ~65 milliseconds on a midrange
-consumer computer.  The user can instead specify bins which are
-directly relevant to matching observational data, in which case the
-code avoids computing depths for irrelevant wavelengths and is many
-times faster.  The user can also download higher resolution data (R=10,000 or R=375,000) from `here <http://astro.caltech.edu/~mz/absorption.html>`_
-and drop them into PLATON's data folder; the runtime is roughly proportional
-to the resolution.
-
-The eclipse spectrum is calculated with the same physics included, but it does
-not include scattering as a source of emission; scattering is only included as
-a source of absorption.
+The transit spectrum is calculated from 0.2 um to 30 um, taking into
+account gas absorption, H- absorption, collisionally induced absorption,
+clouds, and scattering.  The eclipse spectrum is calculated with the same physics included, but it does not include scattering as a source of emission; scattering is only included as a source of absorption.
 
 The retrievers use TransitDepthCalculator/EclipseDepthCalculator as a forward
 model, and can retrieve atmospheric properties using either MCMC or nested
 sampling.  The speed of these retrievals is highly dependent on the wavelength
 range, data precision, prior ranges, opacity resolution, and number of live points (nested sampling)
 or iterations/walkers (MCMC).  A very rough guideline is that a retrieval with
-200 live points and R=1000 (suitable for exploratory work) for
-STIS + WFC3 + IRAC 3.6 um + IRAC 4.5 um data takes <1 hour, while a
-retrieval with 1000 live points and R=10,000 (suitable for the final version)
-takes 1-2 days.  There are a variety of ways to speed up the retrieval, as
-described in our PLATON II paper.  These include using correlated-k instead of
-opacity sampling with R=10,000, or removing the opacity data files of
-unimportant molecules (thereby zeroing their opacities).
+250 live points and R=20k for
+STIS + WFC3 + IRAC 3.6 um + IRAC 4.5 um data takes 19 minutes with multinest, or 75 minutes with dynesty.  There are a variety of ways to speed up the retrieval, as
+described on the Q&A page. 

docs/mie_scattering.rst

@@ -24,11 +24,10 @@ their actual, wavelength-dependent refractive indices, assuming a standard
 deviation in the lognormal size distribution of 0.5::
 
   calculator.compute_depths(Rs, Mp, Rp, T,
-      ri = "TiO2", frac_scale_height = 0.5, number_density = 1e9,
+      ri = "TiO2_anatase", frac_scale_height = 0.5, number_density = 1e9,
       part_size = 1e-6, cloudtop_pressure=1e5)
 
-The supported species are MgSiO3_sol, SiO2_amorph, and TiO2, using the
-refractive index data of `Kitzmann et al 2017 <https://arxiv.org/abs/1710.04946>`_.
+The supported species are those with `data in LX-MIE <https://github.com/NewStrangeWorlds/LX-MIE/tree/master/compilation>`, with the exception of Fe2SiO4 and MgAl2O4 (which do not have refractive index data all the way to 0.2 um).  
 
 To retrieve Mie scattering parameters, make sure to set log_scatt_factor to 0,
 and log_number_density to a finite value.  n and log_k specify the real component and log10 of the imaginary component of the complex refractive index.  We recommend fixing at least n.  Example::