Merge pull request #100 from EXP-code/JOSSedits

Changes for JOSS reviewing process

Author: The9Cat

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,52 @@
+name: Bug report
+description: Create a report describing unexpected or incorrect behavior in EXP.
+labels: Bug
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Thanks for taking the time to fill out this bug report! Please provide a clear and concise description of the bug you've encountered.
+  - type: dropdown
+    id: interface
+    attributes:
+      label: Interface
+      description: Which interface of EXP are you using?
+      options:
+        - pyEXP
+        - EXP N-body
+      default: 0
+    validations:
+      required: true
+  - type: dropdown
+    id: version
+    attributes:
+      label: Version
+      description: How are you accessing EXP?
+      options:
+        - Docker
+        - Local compile
+      default: 0
+    validations:
+      required: true
+  - type: textarea
+    id: exactversion
+    attributes:
+      label: Exact Version
+      description: Please provide the exact version of EXP you are using. If using pyEXP, please provide the output of `python -c "import pyEXP; pyEXP.util.getVersionInfo()"`; If using N-body, please provide the output of `exp -v`.
+      render: shell
+  - type: textarea
+    attributes:
+      label: Description
+      description: >-
+        A clear and concise description of what the bug is.
+  - type: textarea
+    attributes:
+      label: Expected behavior
+      description: >-
+        A clear and concise description of what you expected to happen.
+  - type: textarea
+    id: logs
+    attributes:
+      label: Relevant log output
+      description: Please copy and paste any relevant log output. This will be automatically formatted into code, so no need for backticks.
+      render: shell

CITATIONS.bib

@@ -0,0 +1,36 @@
+@ARTICLE{2022MNRAS.510.6201P,
+       author = {{Petersen}, Michael S. and {Weinberg}, Martin D. and {Katz}, Neal},
+        title = "{EXP: N-body integration using basis function expansions}",
+      journal = {\mnras},
+     keywords = {methods: numerical, Galaxy: halo, galaxies: haloes, galaxies: kinematics and dynamics, galaxies: structure, Astrophysics - Astrophysics of Galaxies, Astrophysics - Instrumentation and Methods for Astrophysics},
+         year = 2022,
+        month = mar,
+       volume = {510},
+       number = {4},
+        pages = {6201-6217},
+          doi = {10.1093/mnras/stab3639},
+archivePrefix = {arXiv},
+       eprint = {2104.14577},
+ primaryClass = {astro-ph.GA},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2022MNRAS.510.6201P},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+@ARTICLE{1999AJ....117..629W,
+       author = {{Weinberg}, Martin D.},
+        title = "{An Adaptive Algorithm for N-Body Field Expansions}",
+      journal = {\aj},
+     keywords = {CELESTIAL MECHANICS, STELLAR DYNAMICS, GALAXIES: STRUCTURE, GALAXY: STRUCTURE, METHODS: NUMERICAL, Astrophysics},
+         year = 1999,
+        month = jan,
+       volume = {117},
+       number = {1},
+        pages = {629-637},
+          doi = {10.1086/300669},
+archivePrefix = {arXiv},
+       eprint = {astro-ph/9805357},
+ primaryClass = {astro-ph},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/1999AJ....117..629W},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+

CMakeLists.txt

@@ -74,7 +74,7 @@ find_package(OpenMP)
 find_package(FFTW REQUIRED)
 find_package(HDF5 COMPONENTS C CXX HL REQUIRED)
 find_package(TIRPC)	       # Check for alternative Sun rpc support
-find_package(Eigen3 REQUIRED)
+find_package(Eigen3 3.4...<3.5 REQUIRED)
 find_package(PNG)
 find_package(Git)
 

CONTRIBUTING.md

@@ -2,7 +2,8 @@
 
 There are many ways to contribute to EXP. Here are some of them:
 
--   Blog about EXP. Cite the EXP published papers. Tell the world how
+-   Blog about EXP. Cite the EXP published papers (using 
+    the papers in [`CITATIONS.bib`](https://github.com/EXP-code/EXP/blob/main/CITATIONS.bib)). Tell the world how
     you're using EXP. This will help newcomers with more examples and
     will help the EXP project to increase its visibility.
 -   Report bugs and request features in the [issue

INSTALL.md

@@ -1,18 +1,31 @@
 # Configuring and building EXP
 
-We are now using git submodules to provide a number of packages that
-are not common in the HPC environments.  These include
+EXP uses CMake for building a configuration.
 
-- `HighFive`, a C++ wrapper
-class to HDF5
-- `yaml-cpp`, a C++ class for reading and emitting YAML code
-- `pybind11` which is used for Python bindings to the C++ classes
-- `rapidxml`, used to write VTK files for rendering outside of EXP
-- `png++`, C++ wrappers to the png library [Note: png support is optional]
+We recommend building "out of source" to allow for multiple
+configurations.  This allows one to have build various versions
+available from the same source, such as `Release` and `Debug` (see below). 
+
+## Required Libraries for installation
+
+Most required libraries will be available on HPC systems, but a local 
+user may need to install some libraries (e.g. using `apt-get` on linux, 
+and `homebrew` or `macports` on OSX).
+
+| Library | Version   |
+|---------|-----------|
+| Eigen   | >= 3.4    |
+| FFTW    | >= 2.0    |
+| HDF5    | >=1.12    |
+| OpenMPI | >=4.0     |
+
+Other libraries are automatically installed along with EXP using `git submodule` (see next step).
 
-CMake will automatically download and configure these packages on the
-first call. However, if you would to do this manually, from the
-top-level directory, execute the following command:
+### Obtaining Additional libraries
+
+We are now using git submodules to provide `yaml-cpp`, which is not
+common in the HPC environments.  So, from the top-level directory, do
+the following:
 
 ```
    git submodule update --init --recursive
@@ -21,18 +34,32 @@ top-level directory, execute the following command:
 This will install the source packages in the `extern` directory.
 
 
-## EXP uses CMake for building a configuration
-
-I recommend building "out of source" to allow for multiple
-configurations.  This allows one to have build various versions
-available from the same source, such as `Release` and `Debug`.  To
-begin, make a build directory and change to that:
+## Building using CMake
 
+To begin the CMake configuration, make a build directory and change to that:
 ```
    mkdir -p build
    cd build
 ```
 
+The next step is to create the CMake configuration,
+```
+   cmake ..
+```
+build,
+```
+   make -j 4
+```
+and finally install.
+```
+   make install
+```
+The `-j 4` flag allows up to 4 processes to compile simulateously. Change 4 to the number of cores you can allot to compiling.
+
+More details are available below, and troubleshooting can be found in the GitHub discussions.
+
+## In more detail...
+
 CMake is designed to detect commonly used utilities and libraries
 automatically, but sometimes needs help and hints.  For example, if
 CMake does not find a library, you can add the location of the library
@@ -57,7 +84,7 @@ Generally, the install location will need to be changed in the example
 below.  E.g. I would use `-DCMAKE_INSTALL_PREFIX=/home/mdw_umass_edu`
 on the UMass Unity cluster to install in my home directory.
 
-## EXP options
+### EXP options
 
 There are a number of EXP-specific options that control the build.
 The most important of these are:
@@ -123,7 +150,7 @@ Putting these together so far, your CMake call would be:
 ```
 export CUDAARCHS="75;80;86"
 cmake -DCMAKE_BUILD_TYPE=Release -DENABLE_CUDA=YES -DENABLE_USER=YES -DEigen3_DIR=$EIGEN_BASE/share/eigen3/cmake -DCMAKE_INSTALL_PREFIX=/home/user -Wno-dev ..
-````
+```
 
 ## Configuring without CUDA
 

Paper/paper/paper.bib

@@ -7,6 +7,46 @@ @book{Binney:2008
   	Year = 2008
 }
 
+@ARTICLE{Gadget4,
+       author = {{Springel}, Volker and {Pakmor}, R{\"u}diger and {Zier}, Oliver and {Reinecke}, Martin},
+        title = "{Simulating cosmic structure formation with the GADGET-4 code}",
+      journal = {\mnras},
+     keywords = {methods: numerical, galaxies: interactions, dark matter, Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Cosmology and Nongalactic Astrophysics},
+         year = 2021,
+        month = sep,
+       volume = {506},
+       number = {2},
+        pages = {2871-2949},
+          doi = {10.1093/mnras/stab1855},
+archivePrefix = {arXiv},
+       eprint = {2010.03567},
+ primaryClass = {astro-ph.IM},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2021MNRAS.506.2871S},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+
+
+@ARTICLE{Wang:15,
+       author = {{Wang}, Long and {Spurzem}, Rainer and {Aarseth}, Sverre and {Nitadori}, Keigo and {Berczik}, Peter and {Kouwenhoven}, M.~B.~N. and {Naab}, Thorsten},
+        title = "{NBODY6++GPU: ready for the gravitational million-body problem}",
+      journal = {\mnras},
+     keywords = {methods: numerical, globular clusters: general, Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Solar and Stellar Astrophysics},
+         year = 2015,
+        month = jul,
+       volume = {450},
+       number = {4},
+        pages = {4070-4080},
+          doi = {10.1093/mnras/stv817},
+archivePrefix = {arXiv},
+       eprint = {1504.03687},
+ primaryClass = {astro-ph.IM},
+       adsurl = {https://ui.adsabs.harvard.edu/abs/2015MNRAS.450.4070W},
+      adsnote = {Provided by the SAO/NASA Astrophysics Data System}
+}
+
+
+
 @article{gaia,
     author = {{Gaia Collaboration}},
     title = "{The Gaia mission}",

Paper/paper/paper.md

@@ -139,11 +139,21 @@ computed bases and resulting coefficient data are stored in HDF5
 
 ## N-body simulation
 
+Computing the gravitational potential and forces from a collection of
+N particles is typically an expensive endeavour. EXP reduces the cost
+by using BFE to compute the potential and forces such that computational
+effort scales with the number of particles. Other modern N-body codes
+use direct summation [@Wang:15] or tree-based solutions [@Gadget4],
+which have computational effort that scales as N$^2$ and N log N,
+respectively. The trade off for BFE solutions comes in the form of
+restricted degrees of freedom; for many problems in near-equilibrium
+galactic dynamics this is not a problem, but rather a feature.
+
 Our design includes a wide choice of run-time summary diagnostics,
 phase-space output formats, dynamically loadable user libraries, and
 easy extensibility. Stand-alone routines include the EOF and mSSA 
 methods described above, and the modular software architecture of 
-EXP enables users to easily build and maintain extensions. The `EXP` 
+`EXP` enables users to easily build and maintain extensions. The `EXP` 
 code base is described in published papers [@Petersen:22; @Weinberg:23]
 and has been used, enhanced, and rigorously tested for nearly two 
 decades.
@@ -174,12 +184,15 @@ table above as well as coefficients for an input data set.  Each of
 these tools are Python classes that accept `numpy` [@numpy] arrays for
 immediate interoperability with `matplotlib` [@matplotlib] and
 Astropy.  We include a verified set of stand-alone routines that read
-phase-space files from many major cosmological tree codes and produce
+phase-space files from many major cosmological tree codes (for example,
+@Gadget4) and produce
 BFE-based analyses.  The code suite includes adapters for reading and
 writing phase space for many of the widely used cosmology codes, with
 a base class for developing new ones.  There are multiple ways to use
 the versatile and modular tools in `pyEXP`, and we anticipate
-pipelines that we have not yet imagined.
+pipelines that we have not yet imagined. The flexibility of the basis
+sets available in `EXP` greatly enhances the number of available basis
+sets implemented in Python (see, e.g. @gala).
 
 
 ## Using pyEXP to analyze time series