Merge pull request #56 from xuanxu/review

Review improvements

Author: xuanxu

CONTRIBUTING.md

@@ -19,7 +19,7 @@ Pull requests are welcome. If you want to contribute code to solve an open issue
 * Create a topic branch based on main.
 * Commit there your code to solve the issue.
 * Make sure all test are passing (and add specs to test any new feature if needed).
-* Follow the code styles and practices already in place.
+* Follow the code styles and practices already in place. Starmatrix follows [PEP8](https://peps.python.org/pep-0008/).
 * Open a *pull request* to the main repository mentioning the issue you are addressing.
 
 ## Cleaning up
@@ -47,6 +47,10 @@ In the rush of time sometimes things get messy, you can help us cleaning things
   * Actual response
 * Sometimes it is also helpful if you mention your operating system or shell.
 
+## License
+
+Starmatrix is released under the [MIT license](https://github.com/xuanxu/starmatrix/blob/main/LICENSE).
+
 ## Code of Conduct
 
 Obviously there is very little chance of having fun or creating anything interesting in an environment where people do not feel safe. That's why `starmatrix` has a [Code of Conduct](CODE_OF_CONDUCT.md) every contributor must comply. Please read it if you plan to be part of the `starmatrix` community.

README.rst

@@ -33,6 +33,8 @@ Starmatrix computes the contribution matrix of 15 elements:
 H D He3 He4 C C13 N O n.r. Ne Mg Si S Ca Fe
 = = === === = === = = ==== == == == = == ==
 
+Starmatrix is a tool for astronomers working with galactic chemical evolution models needing detailed datasets to use as input, wanting to compare the validity of different yield sets or assessing different nucleosynthesis modeling assumptions.
+
 Installation
 ============
 
@@ -46,6 +48,17 @@ A previous installation can be upgraded to the latest version with::
 
     $ pip install --upgrade starmatrix
 
+Edge
+----
+
+If you want to play with the latest code present in this repository even if it has not been released yet, you can do it by cloning the repo locally and instructing pip to install it::
+
+    $ git clone https://github.com/xuanxu/starmatrix.git
+    $ cd starmatrix
+    $ pip install -e .
+
+Python >= 3.7 is required.
+
 Test installation
 -----------------
 
@@ -56,6 +69,18 @@ To test installation worked you can just run Starmatrix with default values runn
 
 The first command will generate a basic configuration file (named ``config-example.yml``) and the second command will run Starmatrix using that configuration. A folder named ``results``should be created with the output files.
 
+Test suite
+==========
+
+Starmatrix includes a test suite located in the ``/src/starmatrix/tests`` directory. The current state of the build is `publicly tracked by GitHub CI`_. You can run the latest tests locally and get information on code coverage if you clone the code to your local machine, install its development dependencies and use ``pytest``::
+
+    $ git clone https://github.com/xuanxu/starmatrix.git
+    $ cd starmatrix
+    $ pip install -e ".[dev]"
+    $ pytest -v --cov=starmatrix
+
+.. _`publicly tracked by GitHub CI`: https://github.com/xuanxu/starmatrix/actions/workflows/tests.yml
+
 Usage
 =====
 
@@ -71,6 +96,10 @@ Running starmatrix will produce a directory with three output files:
 * **imf_supernova_rates**: the initial mass functions for the supernova rates for each mass interval
 * **qm-matrices**: the Q(m) matrices for every mass interval defined in the *mass_intervals* file
 
+You can find the complete documentation at `ReadTheDocs' Starmatrix page`_.
+
+.. _`ReadTheDocs' Starmatrix page`: https://starmatrix.readthedocs.io/
+
 Input params
 ============
 
@@ -97,7 +126,7 @@ If you want to use an existent configuration file as template for your own, you
 
     $ starmatrix --generate-config
 
-That command will create a ``config-example.yml`` file in the current dir.
+That command will create a ``config-example.yml`` file in the current dir containing the default values.
 
 
 Initial mass function
@@ -177,26 +206,14 @@ The ``sn_yields`` param in the config file can be set to use any of the availabl
 :mor2018-1: Data from Mori, K. et al., 2018, ApJ, 863:176 W7
 :mor2018-2: Data from Mori, K. et al., 2018, ApJ, 863:176 WDD2
 
-Test suite
-==========
-
-Starmatrix includes a test suite located in the ``/src/starmatrix/tests`` directory. The current state of the build is `publicly tracked by GitHub CI`_. You can run the latest tests locally and get information on code coverage if you clone the code to your local machine, install its development dependencies and use ``pytest``::
-
-    $ git clone https://github.com/xuanxu/starmatrix.git
-    $ cd starmatrix
-    $ pip install -e ".[dev]"
-    $ pytest -v --cov=starmatrix
-
-.. _`publicly tracked by GitHub CI`: https://github.com/xuanxu/starmatrix/actions/workflows/tests.yml
+Contributions
+=============
 
-Edge
-====
+If you find a bug or have a question, please [open an issue in the project's repo](https://github.com/xuanxu/starmatrix/issues).
 
-If you want to play with the latest code present in this repository even if it has not been released yet, you can do it by cloning the repo locally and instructing pip to install it::
+Contributions are welcome, please read our `contributing guidelines`_.
 
-    $ git clone https://github.com/xuanxu/starmatrix.git
-    $ cd starmatrix
-    $ pip install -e .
+.. _`contributing guidelines`: https://github.com/xuanxu/starmatrix/blob/review/CONTRIBUTING.md
 
 License
 =======

docs/usage.rst

@@ -38,7 +38,7 @@ This is the list of all Starmatrix modules::
 
 **Examples:**
 
-Run a model with your own custom parameters from inside your programs::
+Run a model with your own custom parameters (in this example custom_params is a dict object modifying any of the available :doc:`configuration parameters <configuration>`) from inside your programs::
 
     import starmatrix
     import starmatrix.settings as settings

paper/paper.md

@@ -23,17 +23,17 @@ bibliography: paper.bib
 
 `Starmatrix` is a Python package for computing the chemical contribution to the interstellar medium ejected by simple stellar populations (SSPs).
 
-One of the key ingredients of galactic chemical evolution models is the nucleosynthetic contribution returned to the interstellar medium by the evolving stellar populations and supernovae. This yields varies depending on the age and metallicity of the stars and are combined following the mass distribution of stars to represent a simple stellar population. Repeating this process adjusting for the the star formation at each time step is one of the main mechanisms of GCE models.
+One of the key ingredients of galactic chemical evolution (GCE) models is the nucleosynthetic contribution returned to the interstellar medium by the evolving stellar populations and supernovae. This yields vary depending on the age and metallicity of the stars and are combined following the mass distribution of stars to represent a simple stellar population. Repeating this process adjusting for the the star formation at each time step is one of the main mechanisms of GCE models.
 
-`Starmatrix` reads a single configuration file and calculates the combined contributions of chemical elements ejected to the interstellar medium during the lifetime of stars in the provided mass range. For each mass step an ejections matrix is computed for these fifteen elements: $H$, $D$, $^{3}He$, $^{4}He$, $^{12}C$, $^{16}O$, $^{14}N$, $^{13}C$, $^{20}Ne$, $^{24}Mg$, $^{28}Si$, $^{32}S$, $^{40}Ca$, $^{56}Fe$, and neutron-rich elements as only one group.
+`Starmatrix` reads a single configuration file and calculates the combined contributions of chemical elements ejected to the interstellar medium during the lifetime of stars in the provided mass range. For each mass step an ejections matrix is computed for these fifteen elements: $H$, $D$, $^{3}He$, $^{4}He$, $^{12}C$, $^{16}O$, $^{14}N$, $^{13}C$, $^{20}Ne$, $^{24}Mg$, $^{28}Si$, $^{32}S$, $^{40}Ca$, $^{56}Fe$, and also all neutron-rich CNO isotopes as only one group.
 
-Using explicit (and configurable) values for *solar abundances*, *metallicity (z)*, *ejection rates* and *Initial Mass Function (IMF)*, `Starmatrix` calculates matrices $Q_{ij}$ of masses of elements `i` ejected to the galactic medium as element `j`, integrating for a given range of stellar masses, and accounting for Supernovae (SNe) of types *I* and *II*. Based on the *Matrices Q formalism* [@ferrini1992;@portinari1998], an output file is generated containing matrices linking any ejected species to all its different nucleosynthetic sources.
+Using explicit (and configurable) values for *solar abundances*, *metallicity (z)*, *ejection rates* and *Initial Mass Function (IMF)*, `Starmatrix` calculates matrices $Q_{ij}$ of masses of elements `j` ejected to the galactic medium as element `i`, integrating for a given range of stellar masses, and accounting for Supernovae (SNe) of types *I* and *II*. Based on the *Matrices Q formalism* [@ferrini1992;@portinari1998], an output file is generated containing matrices linking any ejected species to all its different nucleosynthetic sources.
 
 # Statement of need
 
 Calculating the contributions of chemical elements from different stars in several mass ranges is a necessary step for galactic chemical evolution models [@molla2017]. Usually this is done internally and the chemical yields are convoluted with a star formation history (SFH) inside the model, making it difficult to find reusable opensourced code for calculating the yield for a simple stellar population. The central module in Chempy [@rybizki2017] and the SYGMA module from the NUPYCEE framework [@sygma2018] are exceptions, but being part of bigger codebases they are not available as standalone libraries, not listed in the official Python Package Index and learning how to install and use them is not simple.
 
-`Starmatrix` isolates the SSP yield calculation step as a open source permissively licensed Python implementation, in a modular an flexible way that can be used to provide detailed datasets to be used as input for galactic chemical evolution models, to compare the validity of different yield sets from the literature or to assess different nucleosynthesis modeling assumptions [@bazan2003].
+`Starmatrix` isolates the SSP yield calculation step as an open source permissively licensed Python implementation, in a modular an flexible way that can be used to provide detailed datasets to be used as input for galactic chemical evolution models, to compare the validity of different yield sets from the literature or to assess different nucleosynthesis modeling assumptions [@bazan2003].
 
 # Features
 
@@ -42,7 +42,7 @@ Then, the time step is converted back into stellar mass intervals and a $Q$ matr
 
 All quantities in the $Q$ matrix are calculated on the base of the ejected mass from stars, using for it the dataset of yields per stellar mass that is entered as input for the code. The code is prepared to include any sets of stellar yields from the literature but if none is declared a default dataset for solar metallicity and with low and intermediate mass star yields from [@gavilan2006] and yields of massive stars from [@chieffi2004] will be used.
 
-![A sample plot using the output data from several `Starmatrix` runs. Lines show true yields `p` of Oxigen using different datasets for low and intermediate mass yields (columns) and for massive stars yields (rows), for a range of metallicity values (bottom horizontal axis) and different IMFs available as Starmatix' settings.\label{fig:oxigen}](sample_plot.png)
+![A sample plot using the output data from several `Starmatrix` runs. Lines show true yields `p` of Oxygen using different datasets for low and intermediate mass yields (columns) and for massive stars yields (rows), for a range of metallicity values (bottom horizontal axis) and different IMFs available as Starmatix' settings.\label{fig:oxygen}](sample_plot.png)
 
 Configurable parameters include metallicity, mass range for $Q$ matrices, fraction of binary systems, lower and upper mass limits for the IMF, total time steps for integration and yield correction factors. The code also includes a variety of options for `IMFs`, `solar abundances` data, Supernovae `yields` and `Delay Time Distributions` from the literature to choose from. A complete list of available options can be found in the documentation. To make the code more reusable and to allow it to be integrated in or called by other codebases, Starmatrix defines a base class for each of these parameters to be subclassed if needed so custom options can be easily added programmatically. The code also includes extensive test coverage.