Skip to content

Initial editorial tweaks for JOSS paper #138

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
The9Cat merged 1 commit into from
May 5, 2025
Merged

Initial editorial tweaks for JOSS paper #138

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
56 changes: 28 additions & 28 deletions Paper/paper/paper.bib
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ @book{Binney: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},
journal = {Monthly Notices of the Royal Astronomical Society},
keywords = {methods: numerical, galaxies: interactions, dark matter, Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Cosmology and Nongalactic Astrophysics},
year = 2021,
month = sep,
Expand All @@ -30,7 +30,7 @@ @ARTICLE{Gadget4
@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},
journal = {Monthly Notices of the Royal Astronomical Society},
keywords = {methods: numerical, globular clusters: general, Astrophysics - Instrumentation and Methods for Astrophysics, Astrophysics - Solar and Stellar Astrophysics},
year = 2015,
month = jul,
Expand All @@ -50,14 +50,15 @@ @ARTICLE{Wang:15
@article{gaia,
author = {{Gaia Collaboration}},
title = "{The Gaia mission}",
journal = {Astronomy and Astrophysics},
journal = {Astronomy \& Astrophysics},
archivePrefix = "arXiv",
eprint = {1609.04153},
primaryClass = "astro-ph.IM",
keywords = {space vehicles: instruments, Galaxy: structure, astrometry, parallaxes, proper motions, telescopes},
year = 2016,
month = nov,
volume = 595,
pages = "A1",
doi = {10.1051/0004-6361/201629272},
url = {http://adsabs.harvard.edu/abs/2016A%26A...595A...1G},
}
Expand All @@ -68,7 +69,7 @@ @article{gaia_DR2_disk
Doi = {10.1051/0004-6361/201832865},
Eid = {A11},
Eprint = {1804.09380},
Journal = {Astronomy and Astrophysics},
Journal = {Astronomy \& Astrophysics},
Month = {Aug},
Pages = {A11},
Primaryclass = {astro-ph.GA},
Expand All @@ -80,7 +81,7 @@ @article{gaia_DR2_disk
@article{astropy,
author = {{Astropy Collaboration}},
title = "{Astropy: A community Python package for astronomy}",
journal = {Astronomy and Astrophysics},
journal = {Astronomy \& Astrophysics},
archivePrefix = "arXiv",
eprint = {1307.6212},
primaryClass = "astro-ph.IM",
Expand All @@ -101,13 +102,13 @@ @article{gala
volume = {2},
number = {18},
author = {Adrian M. Price-Whelan},
title = {Gala: A Python package for galactic dynamics},
title = "{Gala: A Python package for galactic dynamics}",
journal = {The Journal of Open Source Software}}


@misc{hdf5,
author = {{The HDF Group}},
title = "{Hierarchical data format version 5}",
title = "{Hierarchical Data Format, version 5}",
year = {2000-2010},
howpublished = {http://www.hdfgroup.org/HDF5}
}
Expand All @@ -116,13 +117,13 @@ @misc{pybind11
author = {Wenzel Jakob and Jason Rhinelander and Dean Moldovan},
year = {2017},
note = {https://github.com/pybind/pybind11},
title = {pybind11 -- Seamless operability between C++11 and Python}
title = "{pybind11 -- Seamless operability between C++11 and Python}"
}

@ARTICLE{Weinberg:23,
author = {{Weinberg}, Martin D.},
title = "{New dipole instabilities in spherical stellar systems}",
journal = {Monthly Notices of the RAS},
journal = {Monthly Notices of the Royal Astronomical Society},
year = 2023,
month = nov,
volume = {525},
Expand All @@ -137,7 +138,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 = {Monthly Notices of the RAS},
journal = {Monthly Notices of the Royal Astronomical Society},
year = 2021,
month = mar,
volume = {501},
Expand All @@ -152,7 +153,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 = {Monthly Notices of the RAS},
journal = {Monthly Notices of the Royal Astronomical Society},
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,
Expand All @@ -168,7 +169,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 = {Monthly Notices of the RAS},
journal = {Monthly Notices of the Royal Astronomical Society},
keywords = {galaxies: disc, galaxies: haloes, galaxies: structure, Astrophysics - Astrophysics of Galaxies, Astrophysics - Instrumentation and Methods for Astrophysics},
year = 2023,
month = may,
Expand All @@ -187,7 +188,7 @@ @book{SSA
year={2001},
publisher={CRC press}
}

@Article{numpy,
title = {Array programming with {NumPy}},
author = {Charles R. Harris and K. Jarrod Millman and St{\'{e}}fan J.
Expand Down Expand Up @@ -227,8 +228,8 @@ @Article{matplotlib

@ARTICLE{Weinberg:99,
author = {{Weinberg}, Martin D.},
title = "{An Adaptive Algorithm for N-Body Field Expansions}",
journal = {Astronomical Journal},
title = {An Adaptive Algorithm for {N}-Body Field Expansions},
journal = {The Astronomical Journal},
keywords = {CELESTIAL MECHANICS, STELLAR DYNAMICS, GALAXIES: STRUCTURE, GALAXY: STRUCTURE, METHODS: NUMERICAL, Astrophysics},
year = 1999,
month = jan,
Expand Down Expand Up @@ -277,11 +278,11 @@ @INCOLLECTION{jupyter
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

@misc{cuda,
author={NVIDIA and Vingelmann, Péter and Fitzek, Frank H.P.},
title={CUDA, release: 10.2.89},
year={2020},
url={https://developer.nvidia.com/cuda-toolkit},
@misc{cuda,
author={NVIDIA and Vingelmann, Péter and Fitzek, Frank H.P.},
title={CUDA, release: 10.2.89},
year={2020},
url={https://developer.nvidia.com/cuda-toolkit},
}

@manual{mpi41,
Expand All @@ -296,7 +297,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 = {Astrophysical Journal},
journal = {The 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,
Expand All @@ -314,8 +315,8 @@ @ARTICLE{GaravitoCamargo:21

@ARTICLE{Hernquist:90,
author = {{Hernquist}, Lars},
title = "{An Analytical Model for Spherical Galaxies and Bulges}",
journal = {Astrophysical Journal},
title = {An Analytical Model for Spherical Galaxies and Bulges},
journal = {The 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,
Expand All @@ -330,8 +331,8 @@ @ARTICLE{Hernquist:90

@ARTICLE{Hernquist:92,
author = {{Hernquist}, Lars and {Ostriker}, Jeremiah P.},
title = "{A Self-consistent Field Method for Galactic Dynamics}",
journal = {Astrophysical Journal},
title = {A Self-consistent Field Method for Galactic Dynamics},
journal = {The 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,
Expand All @@ -344,8 +345,8 @@ @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 = {Astrophysical Journal},
title = {A Universal Density Profile from Hierarchical Clustering},
journal = {The Astrophysical Journal},
keywords = {Cosmology: Theory, Cosmology: Dark Matter, Galaxies: Halos, Methods: Numerical, Astrophysics},
year = 1997,
month = dec,
Expand All @@ -359,4 +360,3 @@ @ARTICLE{NFW
adsurl = {https://ui.adsabs.harvard.edu/abs/1997ApJ...490..493N},
adsnote = {Provided by the SAO/NASA Astrophysics Data System}
}

49 changes: 24 additions & 25 deletions Paper/paper/paper.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ authors:
affiliations:
- name: University of Edinburgh, UK
index: 1
- name: University of Massachusetts/Amherst, USA
- name: University of Massachusetts Amherst, USA
index: 2
date: 01 June 2024
bibliography: paper.bib
Expand All @@ -39,16 +39,16 @@ bodies to evolve under their mutual gravity are capable of reproducing
such complexities but robust links to fundamental theoretical
explanations are still missing.

Basis Function Expansions (BFE) represent fields as a linear
Basis Function Expansions (BFEs) represent fields as a linear
combination of orthogonal functions. BFEs are particularly well-suited
for studies of perturbations from equilibrium, such as the evolution
of a galaxy. For any galaxy simulation, a biorthogonal BFE can fully
represent the density, potential and forces by time series of
coefficients. The coefficients have physical meaning: they represent
the gravitational potential energy in a given function. The variation
the gravitational potential energy in a given function. The variation of
the function coefficients in time encodes the dynamical evolution.
The representation of simulation data by BFE results in huge
compression of the information in the dynamical fields; for example,
The representation of simulation data by BFEs results in huge
compression of the information in the dynamical fields. For example,
1.5 TB of phase space data enumerating the positions and velocities of
millions of particles becomes 200 MB of coefficient data!

Expand All @@ -73,7 +73,7 @@ The need for methodology that seamlessly connects theoretical
descriptions of dynamics, N-body simulations, and compact descriptions
of observed data gave rise to `EXP`. This package provides recent
developments from applied mathematics and numerical computation to
represent complete series of _Basis Function Expansions_ that describe
represent complete series of BFEs that describe
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
Expand All @@ -85,11 +85,11 @@ simulated, and by analogy, observed data.

`EXP` decomposes a galaxy into multiple bases for a variety of scales
and geometries and is thus able to represent arbitrarily complex
simulation with many components (e.g., disk, bulge, dark matter halo,
simulations with many components (e.g., disk, bulge, dark matter halo,
satellites). `EXP` is able to efficiently summarize the degree and
nature of asymmetries through coefficient amplitudes tracked through
time and provide details at multiple scales. The
amplitudes themselves enable ex-post-facto dynamical discovery.
amplitudes themselves enable ex-post-facto dynamical discovery.
`EXP` is a collection of object-oriented C++ libraries with an
associated modular N-body code and a suite of stand-alone analysis
applications.
Expand All @@ -106,11 +106,11 @@ coefficients and discover dynamical relationships using time series
analysis such as mSSA. We provide a [full online
manual](https://exp-docs.readthedocs.io) hosted by ReadTheDocs.

The software package brings published -- but difficult to implement --
applied-math technologies into the astronomical mainstream. `EXP` and
The software package brings published---but difficult to implement---applied-math
technologies into the astronomical mainstream. `EXP` and
the associated Python interface `pyEXP` accomplish this by providing
tools integrated with the Python ecosystem, and in particular are
well-suited for interactive Python [@iPython] use through (e.g.)
well-suited for interactive Python [@iPython] use through, e.g.,
Jupyter notebooks [@jupyter]. `EXP` serves as the
scaffolding for new imaginative applications in galactic dynamics,
providing a common dynamical language for simulations and analytic
Expand All @@ -126,36 +126,36 @@ computed bases and resulting coefficient data are stored in HDF5

| Name | Description |
| ----------- | ------------- |
| sphereSL | Sturm-Liouville basis function solutions to Poisson's equation for any arbitrary input spherical density |
| sphereSL | Sturm--Liouville basis function solutions to Poisson's equation for any arbitrary input spherical density |
| bessel | Basis constructed from eigenfunctions of the spherical Laplacian |
| cylinder | EOF solutions tabulated on the meridional plane for distributions with cylindrical geometries |
| flatdisk | EOF basis solutions for the three-dimensional gravitational field of a razor-thin disk |
| cube | Trigonometric basis solution for expansions in a cube with boundary criteria |
| field | General-purpose EOF solution for scalar profiles |
| velocity | EOF solution for velocity flow coefficients |

![Example cylinder basis functions, where the color encodes the amplitude of the function, for an exponential disk with a scalelength of 3 and a scaleheight of 0.3 in arbitrary units. We select three functions at low, medium, and higher order (corresponding to the number of nodes). The color scale has been normalised such that the largest amplitude is unity in each panel. \label{fig:examplecylinder}](examplefunctions.png)
![Example cylinder basis functions, where the color encodes the amplitude of the function, for an exponential disk with a scale length of 3 and a scale height of 0.3 in arbitrary units. We select three functions at low, medium, and higher order (corresponding to the number of nodes). The color scale has been normalised such that the largest amplitude is unity in each panel. \label{fig:examplecylinder}](examplefunctions.png)


## N-body simulation

Computing the gravitational potential and forces from a collection of
N particles is typically an expensive endeavour. EXP reduces the cost
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
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`
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`
code base is described in published papers [@Petersen:22; @Weinberg:23]
and has been used, enhanced, and rigorously tested for nearly two
and has been used, enhanced, and rigorously tested for nearly two
decades.


Expand All @@ -181,10 +181,10 @@ can be extended by users.
`pyEXP` provides an interface to many of the classes in the `EXP` C++
library, allowing for both the generation of all bases listed in the
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
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 [for example,
phase-space files from many major cosmological tree codes [e.g.,
@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
Expand All @@ -201,11 +201,11 @@ The `EXP` library includes multiple time series analysis tools,
documented in the manual. Here, we briefly highlight one technique
that we have already used in published work: mSSA [@Weinberg:21;
@Johnson:23]. Beginning with coefficient series from the previous
tools, mSSA summarizes signals _in time_ that describes dynamically
tools, mSSA summarizes signals _in time_ that describe dynamically
correlated responses and patterns. Essentially, this is BFE in time
and space. These temporal and spatial patterns allow users to better
identify dynamical mechanisms and enable intercomparisons and
filtering for features in simulation suites; e.g. computing the
filtering for features in simulation suites, e.g. computing the
fraction galaxies with grand design structure or hosting
bars. Random-matrix techniques for singular-value decomposition ensure
that analyses of large data sets is possible. All mSSA decompositions
Expand All @@ -221,4 +221,3 @@ Robert Blackwell for invaluable help with HPC best practices.


# References