Merge branch 'main' into wCorrFix

Author: michael-petersen

.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 = {Monthly Notices of the RAS},
+     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 = {Monthly Notices of the RAS},
+     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}",
@@ -28,7 +68,7 @@ @article{gaia_DR2_disk
 	Doi = {10.1051/0004-6361/201832865},
 	Eid = {A11},
 	Eprint = {1804.09380},
-	Journal = {A\&Ap},
+	Journal = {Astronomy and Astrophysics},
 	Month = {Aug},
 	Pages = {A11},
 	Primaryclass = {astro-ph.GA},
@@ -82,7 +122,7 @@ @misc{pybind11
 @ARTICLE{Weinberg:23,
        author = {{Weinberg}, Martin D.},
         title = "{New dipole instabilities in spherical stellar systems}",
-      journal = {MNRAS},
+      journal = {Monthly Notices of the RAS},
          year = 2023,
         month = nov,
        volume = {525},
@@ -97,7 +137,7 @@ @ARTICLE{Weinberg:23
 @ARTICLE{Weinberg:21,
        author = {{Weinberg}, Martin D. and {Petersen}, Michael S.},
         title = "{Using multichannel singular spectrum analysis to study galaxy dynamics}",
-      journal = {MNRAS},
+      journal = {Monthly Notices of the RAS},
          year = 2021,
         month = mar,
        volume = {501},
@@ -112,7 +152,7 @@ @ARTICLE{Weinberg:21
 @ARTICLE{Petersen:22,
        author = {{Petersen}, Michael S. and {Weinberg}, Martin D. and {Katz}, Neal},
         title = "{EXP: N-body integration using basis function expansions}",
-      journal = {\mnras},
+      journal = {Monthly Notices of the RAS},
      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,
@@ -128,7 +168,7 @@ @ARTICLE{Petersen:22
 @ARTICLE{Johnson:23,
        author = {{Johnson}, Alexander C. and {Petersen}, Michael S. and {Johnston}, Kathryn V. and {Weinberg}, Martin D.},
         title = "{Dynamical data mining captures disc-halo couplings that structure galaxies}",
-      journal = {MNRAS},
+      journal = {Monthly Notices of the RAS},
      keywords = {galaxies: disc, galaxies: haloes, galaxies: structure, Astrophysics - Astrophysics of Galaxies, Astrophysics - Instrumentation and Methods for Astrophysics},
          year = 2023,
         month = may,
@@ -188,7 +228,7 @@ @Article{matplotlib
 @ARTICLE{Weinberg:99,
        author = {{Weinberg}, Martin D.},
         title = "{An Adaptive Algorithm for N-Body Field Expansions}",
-      journal = {\aj},
+      journal = {Astronomical Journal},
      keywords = {CELESTIAL MECHANICS, STELLAR DYNAMICS, GALAXIES: STRUCTURE, GALAXY: STRUCTURE, METHODS: NUMERICAL, Astrophysics},
          year = 1999,
         month = jan,
@@ -256,7 +296,7 @@ @manual{mpi41
 @ARTICLE{GaravitoCamargo:21,
        author = {{Garavito-Camargo}, Nicol{\'a}s and {Besla}, Gurtina and {Laporte}, Chervin F.~P. and {Price-Whelan}, Adrian M. and {Cunningham}, Emily C. and {Johnston}, Kathryn V. and {Weinberg}, Martin and {G{\'o}mez}, Facundo A.},
         title = "{Quantifying the Impact of the Large Magellanic Cloud on the Structure of the Milky Way's Dark Matter Halo Using Basis Function Expansions}",
-      journal = {\apj},
+      journal = {Astrophysical Journal},
      keywords = {Milky Way dynamics, Large Magellanic Cloud, Milky Way dark matter halo, 1051, 903, 1049, Astrophysics - Astrophysics of Galaxies},
          year = 2021,
         month = oct,
@@ -275,7 +315,7 @@ @ARTICLE{GaravitoCamargo:21
 @ARTICLE{Hernquist:90,
        author = {{Hernquist}, Lars},
         title = "{An Analytical Model for Spherical Galaxies and Bulges}",
-      journal = {\apj},
+      journal = {Astrophysical Journal},
      keywords = {Computational Astrophysics, Elliptical Galaxies, Galactic Bulge, Galactic Structure, Astronomical Models, Astronomical Photometry, Brightness Distribution, Distribution Functions, Astrophysics, GALAXIES: PHOTOMETRY, GALAXIES: STRUCTURE},
          year = 1990,
         month = jun,
@@ -291,7 +331,7 @@ @ARTICLE{Hernquist:90
 @ARTICLE{Hernquist:92,
        author = {{Hernquist}, Lars and {Ostriker}, Jeremiah P.},
         title = "{A Self-consistent Field Method for Galactic Dynamics}",
-      journal = {\apj},
+      journal = {Astrophysical Journal},
      keywords = {Celestial Mechanics, Computational Astrophysics, Galaxies, Stellar Motions, Algorithms, Astronomical Models, Dynamical Systems, Numerical Analysis, Astrophysics, CELESTIAL MECHANICS, STELLAR DYNAMICS, METHODS: NUMERICAL},
          year = 1992,
         month = feb,
@@ -305,7 +345,7 @@ @ARTICLE{Hernquist:92
 @ARTICLE{NFW,
        author = {{Navarro}, Julio F. and {Frenk}, Carlos S. and {White}, Simon D.~M.},
         title = "{A Universal Density Profile from Hierarchical Clustering}",
-      journal = {\apj},
+      journal = {Astrophysical Journal},
      keywords = {Cosmology: Theory, Cosmology: Dark Matter, Galaxies: Halos, Methods: Numerical, Astrophysics},
          year = 1997,
         month = dec,

Paper/paper/paper.md

@@ -78,7 +78,7 @@ the variation of _any_ field in space.  In the context of galactic
 dynamics, these fields may be density, potential, force, velocity
 fields or any intrinsic field produced by simulations such as
 chemistry data.  By combining the coefficient information through time
-using multichannel singular spectral analysis (mSSA; @SSA), a
+using multichannel singular spectral analysis [mSSA, @SSA], a
 non-parametric spectral technique, `EXP` can deepen our understanding
 by discovering the dynamics of galaxy evolution directly from
 simulated, and by analogy, observed data.
@@ -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