IMAGINE Model Library

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.

Requirements

Requires:

• Python 3 (>=3.6)
• C++ (>=17)

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):

• pybind11

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.

Installation

The installation procedures are preliminary only

Installation (Python)

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.

Installation (C++)

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.

Examples

Including the library

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.

Adding new models TBD

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.

List of Models

Magnetic/Vector Fields

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

Thermal electron/Scalar Fields

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	✔	✔