diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..722c267a --- /dev/null +++ b/.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 \ No newline at end of file diff --git a/CMakeLists.txt b/CMakeLists.txt index 70a4dc53..df647b23 100644 --- a/CMakeLists.txt +++ b/CMakeLists.txt @@ -68,7 +68,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 REQUIRED) find_package(PNG) # Check for FE diff --git a/INSTALL.md b/INSTALL.md index 449daac4..efaeef46 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -1,5 +1,28 @@ # Configuring and building EXP +EXP uses CMake for building a configuration. + +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). + +### 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: @@ -12,18 +35,31 @@ This will install `yaml-cpp` in the `extern` directory. The png++ C++ wrappers to the png library are also installed in `extern`. Note: png support is optional. -## 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 +``` + +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 @@ -48,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: @@ -114,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 diff --git a/Paper/paper/paper.bib b/Paper/paper/paper.bib index f6dedcf6..a352729c 100644 --- a/Paper/paper/paper.bib +++ b/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}", diff --git a/Paper/paper/paper.md b/Paper/paper/paper.md index a593490b..fe305e0a 100644 --- a/Paper/paper/paper.md +++ b/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 diff --git a/Paper/paper/paper.pdf b/Paper/paper/paper.pdf index 1f8072ec..fd52d8ad 100644 Binary files a/Paper/paper/paper.pdf and b/Paper/paper/paper.pdf differ