DarkHistory

DarkHistory is a Python code package that calculates the global temperature and ionization history of the universe given an exotic source of energy injection, such as dark matter annihilation or decay. DarkHistory is described in a paper available at arXiv:1904.09296. Please cite this paper if you use DarkHistory in a scientific publication. For detailed information, please visit our readthedocs webpage here.

Installation

Updated 2024/10/04

• Clone this repository. Checkout the branch you would like to use. (Current active branches: master, lowengelec_upgrade, early_halo_cooling)
• Create a new virtual environment for DarkHistory (recommended). For example, using conda:

conda create -n darkhistory python=3.12 pip
conda activate darkhistory

• Install via pip in the DarkHistory/ directory

pip install .

• Download data files required to run DarkHistory and save to an arbitrary location.
• Inform DarkHistory of the location by setting the variable data_path_default in darkhistory/config.py or the environment variable DH_DATA_DIR to the directory containing data files.
• Now you should be able to run DarkHistory. Test with the example code below. You can also familiarize yourself with DarkHistory using notebooks in examples/.

Notes:

• 2024/10/04: Please make sure to set cosmology parameters in darkhistory/physics.py consistent with your purpose! The current master branch may have updated parameters compared to earlier versions.
• 2024/10/04: Package dependency is now updated in pyproject.toml and requirements.txt. Installing via pip install . will automatically install the required packages. We currently do not recommend pip install darkhistory, as the PyPI version may not be most up-to-date.
• 2024/08/12: For versatility, all data files required to use DarkHistory have been converted to either HDF5, JSON, or plain text files. All active branches of DarkHistory (master, lowengelec_upgrade, andearly_halo_cooling) have been updated to use the new set of data files. You can download the new data files at the following link. See below for older datasets.

Available Versions

DarkHistory v1.1.2 for DM21cm

The version of DarkHistory used in DM21cm, a semi-numerical simulation of inhomogemeous dark matter energy injection based on DarkHistory and 21cmFAST. DM21cm is described in arXiv:2312.11608. Branch: master.

DarkHistory v2.0, with improved treatment of low energy electrons and spectral distortions

The branch containing the upgraded treatment for low energy electrons and spectral distortions can be found here. In additional to the data files needed for v1.0, this upgrade requires additional data files.

The upgrades are described in a paper available at arXiv:2303.07366, and examples of applications are given in arXiv:2303.07370. Please cite these as well as arXiv:1904.09296 if you use this version of DarkHistory in a scientific publication. Branch: lowengelec_upgrade.

DarkHistory v1.1 with Neural Network transfer functions

Added Neural Network transfer functions to optionally replace large tabulated transfer functions. Requires Tensorflow 2.0 in addition to v1.0 dependencies, and a compact dataset to use the Neural Network transfer functions. (To upgrade from v1.0, one can simply add the compact dataset to the existing data directory). To use the tabulated transfer functions, a full dataset is required. (This version of DarkHistory also works with v1.0 dataset with setting use_v1_0_data=True in config.py.)

The update is described in a paper available at arXiv:2207.06425. Please cite this paper as well as arXiv:1904.09296 if you use this version of DarkHistory in a scientific publication. The release for this version can be found here.

DarkHistory v1.0

First release of DarkHistory. DarkHistory v1.0 is described in a paper available at arXiv:1904.09296. Please cite this paper if you use DarkHistory in a scientific publication. The data files for required for this version can be found here. The release for this version can be found here. For more information, please visit our webpage here.

Example usage

from darkhistory.main import evolve

solution = evolve(
    DM_process = 'decay', # 'decay' or 'swave'
    mDM = 1e8,            # [eV]
    lifetime = 3e25,      # [s]
    primary='elec_delta', # primary decay channel
    start_rs = 3000,      # 1+z
    coarsen_factor = 12,  # log(1+z) would change by 0.001 * coarsen_factor for next step
    backreaction = True,  # Enable injection backreaction on matter temperature and ionization levels.
    helium_TLA = True,    # Enable Helium Three Level Atom (TLA).
    reion_switch = True,  # Enable a pre-defined reionization energy injection.
)

solution.keys() # 'rs', 'x', 'Tm', 'highengphot', 'lowengphot', 'lowengelec', 'f'