EXP: nbody EXPansion code

EXP is a Basis Function Expansion C++ library and Python package for running N-body galactic simulations and dynamical discovery.

Repo organization

| Directory | Description | | --- | --- | | Paper | The JOSS paper for EXP | | cmake | Helpers for cmake installation process | | doc | The doxygen documentation for EXP | | expui | Classes used by Python wrappers and by the nbody code and other standalone utilities for coefficient IO support. | | exputil | The main EXP function and class library used by both pyEXP and EXP | | extern | The directory for external code needed for installation | | include | Include file for all common classes | | pyEXP | Source for Python wrappers | | src | Source for nbody code | | tests | An assortment of automatic tests for EXP | | utils | Older but still useful standalone C++ utilities |

Version reporting

EXP automatically stashes its compile time, git branch, and git commit hash when make is invoked in the src directory (e.g. as part of the cmake installation). You can see this info using pyEXP using the pyEXP.util.getVersionInfo() command. You can also see this info using the -v flag, i.e. mpirun -np 1 exp -v or exp -v. Note: some MPI implementations require the MPI-aware executable to be run using 'mpirun'. Some recent HPC systems using slurm require the use of srun instead of mpirun to better administer and schedule your resource request.

Compile hints

See INSTALL.md for a brief synposis and pointers to more detailed information.

A few quick additional notes. By default, both the n-body code and the Python bindings, the pyEXP interface, will be compiled by default. For those of you that only want pyEXP, add -DENABLE_NBODY=OFF to your cmake invocation or toggle ENABLE_NBODY using ccmake or your favorite gui configurator.

Documentation

Currently, EXP is extensively documented using doxygen. The documentation is in doc/html. You will need to enable the build using the cmake flag -DBUILD_DOCS=ON. A permanent online presense is in the works.

Companion repositories

We are developing two repositories of examples and tutorials:

| Repo | Description | | --- | --- | | EXP-examples | Each subdirectory contains a full set of body files and configurations to run EXP with with model galaxy | | pyEXP-examples | Tutorials and example workflows for a variety of envisioned use cases |

Both of these are available from the origin as EXP.

pyEXP

Provides a collection of EXP tools for processing and analyzing simulation data using BFE techniques and MSSA.

The main documentation is the many docstrings embedded in the code and a set of examples provided in the auxiliary pyEXP-examples repository. An online reference guide is in the works. We recommend beginning with the example Python scripts and IPython notebooks and adapting them to your own needs. You can explore the available classes and member functions using the usual Python help function. The classes are organized into six submodules that are described briefly below. Run help(pyEXP.xxxx) for each of the submodules below for more detailed usage info...

The pyEXP submodules

| Submodule | Description | | --- | --- | | read | Read particle snapshots of various types. Currently EXP, Gadget, Tipsy, and Bonzai types are supported. | | basis | Create and apply specific biorthogonal bases to generate coefficients from particle data and evaluate potential, density, and force fields. | | coefs | Classes for reading, passing, writing, converting, and querying coefficient sets. | | field | Create two- and three-dimension rectangular grids of fields for visualization. | | mssa | Tools to apply Multivariate Singular Spectrum Analysis (mSSA) to the coefficients computed using the 'basis' classes. | | edmd | Tools to test extended Dynamical Mode Decomposition (eDMD) using the basis as the 'observable' functions. | | util | Miscellaneous tools that support the others. Currently this include centering algorithms. While EXP has native methods for doing this, others will need to supply an estimated center. |

pyEXP example workflow

To provide some context, suppose you want to read some snapshots, make some coefficients, and then analyze them with MSSA. The class construction would go something like this:

1. Create a reader instance for your simulation, call it 'reader'.
2. Create a basis designed to represent the a particular particle type. Star particles, perhaps, so let's call it 'disk'.
3. We then pass 'reader' to the createCoefficients member of 'disk' to get coefficients for your snapshots, called 'coefs'
4. We might then want to explore dynamical patterns in these coefficients by passing 'coefs' to 'expMSSA'. 'expMSSA' will return principal signals as an updated coefficient object, that we call 'newcoefs'
5. 'newcoefs' and 'disk' can then be passed to the FieldGenerator to provide density, potential, force fields, etc. for the each principal signal

This is only one example of many possible uses. There are many variants to this work flow, of course, and we expect that you will invent some interesting ones.

Citation

If you use EXP in your research, please cite the JOSS paper, and consider including other papers from the list in CITATIONS.bib.