EXP is a Basis Function Expansion C++ library and Python package for running N-body galactic simulations and dynamical discovery.
| 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 |
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.
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.
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.
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.
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...
| 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. |
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:
- Create a reader instance for your simulation, call it 'reader'.
- Create a basis designed to represent the a particular particle type. Star particles, perhaps, so let's call it 'disk'.
- We then pass 'reader' to the createCoefficients member of 'disk' to get coefficients for your snapshots, called 'coefs'
- 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'
- '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.
If you use EXP in your research, please cite the JOSS paper, and consider including other papers from the list in CITATIONS.bib.
