A model library usable for Galactic inference engines. The library is (mostly) written C++, but can be accessed via both C++ and Python. Some (non-essential) elements are written in pure Python, which presently cannot be accessed in the C++ version of the library. A full list of implemented models can be found here.
Please note that this library is work in progress and in early development. By far not everything has been tested, and interfaces may still change. Don't hesitate to use this software, but beware of the risks.Requires:
Python Libraries:
- NumPy (>=1.22)
Optional:
- FFTW3 (>3.3, necessary for random models)
- autodiff (>1.0, necessary for building gradients w.r.t. to model parameters)
Optional (Developers):
Note that pybind is included in the current repository, so in the current state you should not need to install it. This may change in the future.
The installation procedures are preliminary only
Easiest via
pip3 install --user git+https://github.com/IMAGINE-Consortium/imagine-models.git
If you install the library in a virtual environment, remove the --user tag.
If you want to specify a branch, you can do so by adding @branch-name to the above command.
Alternatively, (e.g. if you want to add your own model) you need to clone the repository via
git clone --recursive https://github.com/IMAGINE-Consortium/imagine-models.git
The --recursive flag makes sure that also the pybind module is cloned (to the /extern folder).
The package can then be installed with
python3 -m pip install folder/where/setup/py/is/
You can then add your model at the appropriate locations.
Note that the editable install flag '-e' for pip does not work, which means that you will have to reinstall your local version of the library each time you want to test something.
The installer will automatically figure out which of the optional dependencies you have installed.
If you want to disable those, you can do so by defining the USE_AUTODIFF=OFF and USE_FFTW=OFF environment variables BEFORE you run pip.
First, one needs download the source files, e.g. via cloning the repository with
git clone --recursive https://github.com/IMAGINE-Consortium/imagine-models.git
The --recursive flag makes sure that also the pybind11 module is cloned (to the /extern folder), in case you also want to build the Python package.
One can then install the C++ library via:
mkdir build
cd build
cmake ..
sudo make install
The installer will automatically figure out which of the optional dependencies you have installed.
If you want to disable those, you can do so by defining the USE_AUTODIFF=OFF and USE_FFTW=OFF environment variables BEFORE you run cmake.
Example scripts demonstrating how to include both the python and C++ version are located in the ./demo folder. In the python case, we also include Jupyter notebooks. In these notebooks you can find an overview with information and plots for each of the models listed below.
Defining your own models is easy in both Python and C++.
For that you can start with the model templates provided in the \templates folder.
Binding a C++ model to Python is a bit more involved. For the simplest case, a template exists as well.
| MODEL NAME | PYTHON | C++ | reference | notes | original implementation | notebook and plots |
|---|---|---|---|---|---|---|
| Regular models | ||||||
| Uniform | ✔ | ✔ | used for unit tests | |||
| Helix | ✔ | ✔ | ||||
| Axissymetric spiral | ✔ | ✘ | Pelgrims, V. | Pelgrims, V. | ||
| Archimedean spiral | ✔ | ✔ | simple demonstrative ASS model | CRPropa | ipynb | |
| Local Bubble | ✔ | ✘ | Pelgrims et al. | Only defined on the shell | Pelgrims, V. | |
| Jaffe | ✔ | ✔ | Jaffe et al. (2010) | based on ASS-A spiral with modifications, parameter values taken from hammurabi, not from any publication | Hammurabi X | ipynb |
| Sun2007 | ✔ | ✔ | Sun et al. (2007) | ASS+Ring as disk field implemented, toroidal asymmetric halo with updated halo parameter from Sun et al. (2010), central part of disk field is constant in z-direction (unphysical) | Hammurabi (old) | ipynb |
| Han2018 | ✔ | ✔ | Han et al. (2018) | BSS-S disk field | / | ipynb |
| Pshirkov | ✔ | ✔ | Pshirkov et al. | possible to change between ASS-S and BSS-S, and to switch halo field on/off which is asymmetrical with respect to the plane (A) | CRPropa | ipynb |
| HMR | ✔ | ✔ | Harari et al. (1999) | BSS-S model | Hammurabi (old) and Kachelrieß (2007) | ipynb |
| TT | ✔ | ✔ | Tinyakov and Tkachev (2017) | BSS-A model implemented (eq. 5 in ref.) | Hammurabi (old) and Kachelrieß (2007) | ipynb |
| TF | ✔ | ✔ | Terral and Ferriere (2017) | different halo and disk models available. Note that only the halo has been fitted using data, leading to very strong magnetic field strengths and unexpected features in the disk fields. Also, the halo fields can converge to infinite field strengths at infinite r/z. Thus, the field should be viewed more as a mathematical exercise than an actual model and should not be used for e.g. cosmic ray propagation. | CRPropa | ipynb |
| Fauvet | ✔ | ✔ | Fauvet et al. (2012) | modified logarithmic spiral with two arms (BSS-S) and z-component, fitted to simulated data (no real data used!) | Hammurabi (old) | ipynb |
| Stanev | ✔ | ✔ | Stanev (1996) | BSS-S model implemented, change in halo field at abs(z)=0.5 was not in hammurabi implementation | Hammurabi (old) | ipynb |
| WMAP | ✔ | ✔ | Page et al. (2007) | logarithmic spiral with constant amplitude(B) and z-component, parameters are taken from original publication, not from update mentioned in Ruiz-Granados et al 2010. | / | ipynb |
| Jansson Farrar | ✔ | ✔ | Jansson & Farrar (2012) | regular JF12 field (disk + symmetric toroidal halo + X-field in z-direction) | Hammurabi X | ipynb |
| Random models | ||||||
| Jansson Farrar | ✔ | ✔ | Jansson & Farrar (2012) | depends on the JF12 regular model | Hammurabi X | ipynb |
| Ensslin Steininger | ✔ | ✔ | Hammurabi X |
| MODEL NAME | PYTHON | C++ | reference | notes | original implementation | notebook and plots |
|---|---|---|---|---|---|---|
| Regular models | ||||||
| YMW16 | ✔ | ✔ | Yao et al. (2016) | Hammurabi X | ||
| Random models | ||||||
| GaussianScalar | ✔ | ✔ | used for random number unit testing (TBD!) | |||
| LogNormalScalar | ✔ | ✔ |