Merge pull request #47 from DavoGrant/joss

JOSS review: documentation imporvements

CONTRIBUTING.md

@@ -9,8 +9,8 @@ We recommend that you **fork** the repository and submit your requests according
 1) Search previous issues and pull requests as your question or suggestion might be a duplicate.
 2) Open a separate issue or pull request for each suggestion or bug report.
 3) Pull requests, issues and commits should have a useful title.
-4) Give every PR a description and open it against **develop**, the default branch of the repository.
-5) Every PR that adds or changes a feature should also add or change an/the according **test**, if applicable, as well
+4) Give every PR a description and open it against **dev**, the development branch of the repository.
+5) Every PR that adds or changes a feature should also add or change the corresponding **test**, if applicable, as well
 as **documentation**.
 
 ## Code of conduct

docs/source/index.rst

@@ -31,6 +31,7 @@ to the modelled :math:`I(\mu)` profile.
    Supported instruments <views/supported_instruments>
    Tutorials <views/tutorials>
    API <views/api/api>
+   Contributing <views/contributing>
    Citation <views/citation>
 
 Acknowledgements
@@ -43,7 +44,8 @@ improvements by Iva Laginja. The git history associated with the original
 implementation can be found in the `ExoTiC-ISM <https://github.com/Exo-TiC/ExoTiC-ISM>`_
 package from which this is a spin-off repository. We also thank Natasha Batalha
 for providing the JWST throughput information from their PandExo package and
-to Lili Alderson for reviewing and testing.
+to Lili Alderson for reviewing and testing. Anyone can get involved by following
+the :doc:`contributing guidelines <views/contributing>`.
 
 If you make use of ExoTiC-LD in your research, see the :doc:`citation page <views/citation>`
 for info on how to cite this package and the underlying stellar models.

docs/source/views/api/api.rst

@@ -1,23 +1,32 @@
 API
 ===
 
-Primary Interface
------------------
+This page provides an index of all functions and classes in the ExoTiC-LD
+package, organized by module. Click on the links for detailed documentation.
+For a step-by-step guide, you may prefer to check out the :doc:`tutorials <../tutorials>`.
 
-.. currentmodule:: exotic_ld
 
-.. automodule:: exotic_ld
+Primary Interface
+-----------------
 
-.. autosummary::
-    :toctree: summary
+The primary class in ExoTiC-LD is StellarLimbDarkening. On instantiation, this
+class handles the stellar models. Next, there are methods for computing the
+limb-darkening coefficients utilising the aforementioned stellar models. A list of
+all the methods are given below.
 
-   StellarLimbDarkening
+.. toctree::
+    :maxdepth: 2
 
+    stellar_limb_darkening
 
 Subpackages
 -----------
 
+The available limb-darkening laws are listed here. These functions are utilised by
+the corresponding StellarLimbDarkening methods shown above. Functional forms of each
+law can be seen by clicking into the functions.
+
 .. toctree::
-    :maxdepth: 1
+    :maxdepth: 2
 
     ld_laws

docs/source/views/api/stellar_limb_darkening.rst

@@ -0,0 +1,17 @@
+StellarLimbDarkening
+--------------------
+
+.. currentmodule:: exotic_ld
+
+.. automodule:: exotic_ld
+
+.. autosummary::
+   :toctree: summary
+
+    StellarLimbDarkening
+    StellarLimbDarkening.compute_linear_ld_coeffs
+    StellarLimbDarkening.compute_quadratic_ld_coeffs
+    StellarLimbDarkening.compute_kipping_ld_coeffs
+    StellarLimbDarkening.compute_squareroot_ld_coeffs
+    StellarLimbDarkening.compute_3_parameter_non_linear_ld_coeffs
+    StellarLimbDarkening.compute_4_parameter_non_linear_ld_coeffs

docs/source/views/contributing.rst

@@ -0,0 +1,18 @@
+Contributing guidelines
+=======================
+
+Hello and thank you for contributing to our project! Go ahead open a new issue or new pull request (PR) for bugs,
+feedback, or new features you would like to see by following these guidelines.
+Leave a comment anywhere and we will be happy to assist. New contributions and contributors are very welcome!
+We recommend that you **fork** the repository and submit your requests according to these guidelines:
+
+1) Search previous issues and pull requests as your question or suggestion might be a duplicate.
+2) Open a separate issue or pull request for each suggestion or bug report.
+3) Pull requests, issues and commits should have a useful title.
+4) Give every PR a description and open it against **dev**, the development branch of the repository.
+5) Every PR that adds or changes a feature should also add or change the corresponding **test**, if applicable, as well as **documentation**.
+
+Code of conduct
+---------------
+This package follows the Contributor Covenant `Code of Conduct <https://github.com/Exo-TiC/ExoTiC-LD/blob/main/CODE_OF_CONDUCT.md>`_
+to provide a welcoming community to everybody.

docs/source/views/installation.rst

@@ -45,3 +45,28 @@ limb-darkening coefficients right away.
     You can place the downloaded directory anywhere on your machine, you'll
     just need to pass the path, "path/to/exotic_ld_data", as an input when
     running the code.
+
+**Installing from source:**
+
+Alternatively, you may install ExoTiC-LD from source. This is option is primarily
+useful for those wishing to contribute to the project. The project can be cloned
+from the `GitHub repository <https://github.com/Exo-TiC/ExoTiC-LD>`_, or your
+own fork.
+
+    ::
+
+       git clone https://github.com/Exo-TiC/ExoTiC-LD.git
+
+Next, navigate into the root directory of the package and install
+
+    ::
+
+       pip install .
+
+For running the unit tests, again, navigate into the root directory of the package
+and run
+
+    ::
+
+       python -m unittest tests/test_stellar_models_framework.py
+       python -m unittest tests/test_ld_computation.py

exotic_ld/ld_laws.py

@@ -1,31 +1,93 @@
 def linear_ld_law(mu, u1):
-    """ Linear limb darkening law. """
+    """ Linear limb-darkening law.
+
+    .. math::
+
+                \\frac{I(\\mu)}{I(\\mu = 1)} = 1 - u_1 (1 - \\mu),
+
+    where :math:`\\mu = \\sqrt{1 - r^2}`, and :math:`u_1` is the
+    limb-darkening coefficient.
+
+    """
     return 1. - u1 * (1. - mu)
 
 
 def quadratic_ld_law(mu, u1, u2):
-    """ Quadratic limb darkening law. """
+    """ Quadratic limb-darkening law.
+
+    .. math::
+
+                \\frac{I(\\mu)}{I(\\mu = 1)} = 1 - u_1 (1 - \\mu) - u_2 (1 - \\mu)^2,
+
+    where :math:`\\mu = \\sqrt{1 - r^2}`, and :math:`u_1`, :math:`u_2`
+    are the limb-darkening coefficients.
+
+    """
     return 1. - u1 * (1. - mu) - u2 * (1. - mu)**2
 
 
 def kipping_ld_law(mu, q1, q2):
-    """ Kipping limb darkening law. """
+    """ Kipping limb-darkening law.
+
+    .. math::
+
+                \\frac{I(\\mu)}{I(\\mu = 1)} = 1 - u_1 (1 - \\mu) - u_2 (1 - \\mu)^2,
+
+    where,
+
+        .. math::
+
+                u_1 &= 2 \\sqrt{q_1} q_2,
+
+                u_2 &= \\sqrt{q_1} (1 - 2 q_2),
+
+    and :math:`\\mu = \\sqrt{1 - r^2}`, and :math:`q_1`, :math:`q_2`
+    are the limb-darkening coefficients.
+
+    """
     u1 = 2. * q1**0.5 * q2
     u2 = q1**0.5 * (1. - 2. * q2)
     return 1. - u1 * (1. - mu) - u2 * (1. - mu)**2
 
 
 def squareroot_ld_law(mu, u1, u2):
-    """ Square root limb darkening law. """
+    """ Square root limb-darkening law.
+
+    .. math::
+
+                \\frac{I(\\mu)}{I(\\mu = 1)} = 1 - u_1 (1 - \\mu) - u_2 (1 - \\sqrt{\\mu}),
+
+    where :math:`\\mu = \\sqrt{1 - r^2}`, and :math:`u_1`, :math:`u_2`
+    are the limb-darkening coefficients.
+
+    """
     return 1. - u1 * (1. - mu) - u2 * (1. - mu**0.5)
 
 
 def nonlinear_3param_ld_law(mu, u1, u2, u3):
-    """ Non-linear 3-parameter limb darkening law. """
+    """ Non-linear 3-parameter limb-darkening law.
+
+    .. math::
+
+                \\frac{I(\\mu)}{I(\\mu = 1)} = 1 - u_1 (1 - \\mu) - u_2 (1 - \\mu^{1.5}) - u_3 (1 - \\mu^2),
+
+    where :math:`\\mu = \\sqrt{1 - r^2}`, and :math:`u_1`, :math:`u_2`,
+    :math:`u_3` are the limb-darkening coefficients.
+
+    """
     return 1. - u1 * (1. - mu) - u2 * (1. - mu**1.5) - u3 * (1. - mu**2)
 
 
 def nonlinear_4param_ld_law(mu, u1, u2, u3, u4):
-    """ Non-linear 4-parameter limb darkening law. """
+    """ Non-linear 4-parameter limb-darkening law.
+
+    .. math::
+
+                \\frac{I(\\mu)}{I(\\mu = 1)} = 1 - u_1 (1 - \\mu^{0.5}) - u_2 (1 - \\mu) - u_2 (1 - \\mu^{1.5}) - u_3 (1 - \\mu^2),
+
+    where :math:`\\mu = \\sqrt{1 - r^2}`, and :math:`u_1`, :math:`u_2`,
+    :math:`u_3`, :math:`u_4` are the limb-darkening coefficients.
+
+    """
     return 1. - u1 * (1. - mu**0.5) - u2 * (1. - mu) \
            - u3 * (1. - mu**1.5) - u4 * (1. - mu**2)

joss/paper.bib

@@ -203,6 +203,7 @@ @article{Husser:2013
   journal={Astronomy \& Astrophysics},
   volume={553},
   year={2013},
+  doi = {10.1051/0004-6361/201219058},
   publisher={EDP Sciences}
 }
 
@@ -222,6 +223,7 @@ @article{Magic:2015
   volume={573},
   pages={A90},
   year={2015},
+  doi = {10.1051/0004-6361/201423804},
   publisher={EDP Sciences}
 }
 
@@ -233,6 +235,7 @@ @article{Kostogryz:2023
   number={3},
   pages={39},
   year={2023},
+  doi = {10.3847/2515-5172/acc180},
   publisher={The American Astronomical Society}
 }
 
@@ -243,6 +246,7 @@ @article{Kostogryz:2022
   volume={666},
   pages={A60},
   year={2022},
+  doi = {10.1051/0004-6361/202243722},
   publisher={EDP Sciences}
 }
 
@@ -277,7 +281,8 @@ @article{Morello:2020
   volume={5},
   number={46},
   pages={1834},
-  year={2020}
+  year={2020},
+  doi = {10.21105/joss.01834}
 }
 
 @software{Bourque:2021,