Hazma

Logo

| Overview | Installation | Documentation | Usage | Community Extensions | Citing Hazma

CI Documentation Status DOI arXiv

Overview

Hazma is a tool for studying indirect detection of sub-GeV dark. Its main uses are:

  • Computing gamma-ray and electron/positron spectra from dark matter annihilations;
  • Setting limits on sub-GeV dark matter using existing gamma-ray data;
  • Determining the discovery reach of future gamma-ray detectors;
  • Deriving accurate CMB constraints.

Hazma comes with several sub-GeV dark matter models, for which it provides functions to compute dark matter annihilation cross sections and mediator decay widths. A variety of low-level tools are provided to make it straightforward to define new models.

📦 Installation

Hazma can be installed from PyPI using:

pip install hazma

Alternatively, you can clone the Hazma repo and build from source:

git clone https://github.com/LoganAMorrison/Hazma.git
cd Hazma
pip install .

Since Hazma utilizes C to rapidly compute gamma ray, electron and positron spectra, you will need to have Cython and a c/c++ compiler installed.

🚀 Usage

Computing Photon, Positron and Neutrino Spectra

hazma has built in utilities for generating photon, positron and neutrino spectra. All spectra generation functions live in hazma.spectra. The easiest to use and most versatile functions for spectrum generation are: hazma.spectra.dnde_photon, hazma.spectra.dnde_positron and hazma.spectra.dnde_neutrino. As an example, to compute the photon spectrum from 5 neutral pions, use:

import numpy as np
from hazma import spectra
from hazma.parameters import neutral_pion_mass as mpi0

# Spectra from 5 neutral pions
cme = 6 * mpi0 # center-of-mass energy
photon_energies = np.geomspace(1e-3, 1.0) * cme
final_states = ["pi0"] * 5 # 5 neutral pions
dnde = spectra.dnde_photon(
 photon_energies=photon_energies,
 cme=cme,
 final_states=final_states
)

By replacing dnde_photon with dnde_positron or dnde_neutrino, you can compute the positron or neutrino spectra.

You can supply a squared matrix element to improve the accuracy when there are more than 2 final state particles. For example, suppose you want to compute the muon decay spectrum into photons (hazma has built-in functions for computing the analytic result, so this is simply for demonstration.) By default, for a three-body final state, the matrix element is assumed to accept two invariant masses: s = (p2 + p3)^2 and t=(p1+p3)^2. The user can change this assumption by using msqrd_signature. To compute the muon decay spectrum, use:

import numpy as np
from hazma import spectra
from hazma import parameters

mmu = parameters.muon_mass
me = parameters.electron_mass

# Squared matrix element for mu -> e + nu + nu
# s = (p2 + p3)^2, t = (p1 + p3)^2
# with p1 = pe, p2 = pve, p3 = pvm (same order as `final_states`)
def msqrd(s, t):
    return 16.0 * GF ** 2 * (mmu**2 - t) * (t - me**2)

# Spectra from mu -> e + nu_e + nu_mu
cme = mmu
photon_energies = np.geomspace(1e-3, 1.0) * cme
final_states = ["e", "ve", "vm"]

dnde = spectra.dnde_photon(
    photon_energies=photon_energies,
    cme=cme,
    final_states=final_states,
    msqrd=msqrd,
)

The dnde_photon (and sibling functions) can also be used to compute spectra from a single final state. For example, dnde_positron(positron_energies, cme, "phi") will compute the positron spectrum from a phi vector meson.

Working with Lorentz Invariant Phase Space

hazma include several functions to integrate over Lorentz invariant phase space. Notably, hazma can integrate over N-body phase space using the RAMBO algorithm. There is also special code for computing three-body phase space integrals.

To demonstrate, let's consider a silly squared matrix element of a 5 body final state. We take the squared matrix element to be the product of pairs of final state momenta.

Before we do so, we need to mention how hazma treats four-momenta. For-momenta are taken to be NumPy arrays with the first-axis containing the energy, x-momentum, y-momenta and z-momenta. The second axis contains the different particles. The last axis contains the number of groups of four-momenta we have (number of 'events'.) For example, if we have 5 particles and 100 events, then the momenta will be stored in a NumPy are with shape momenta.shape == (4, 5,100).

  • To access all the four-momenta of particle 3, you would use momenta[:,2].
  • To access the energies of all the particles over all events, you would use momenta[0].
  • To access all the four-momenta of the first event, you would use momenta[:,:,0] or momenta[...,0].

With that out of the way, our squared matrix element will be:

import numpy as np
from hazma.utils import ldot # computes Minkowski dot product of numpy arrays
import itertools

# compute all combinations of two particles
pairs = np.array(list(itertools.combinations(range(5), 2)))

# The below numpy trickery is equivalent to:
# npts = momenta.shape[-1]
# msqrd = np.ones((npts,))
# for i in range(5):
#   for j in range(i+1, 5):
#       msqrd *= ldot(momenta[:, i], momenta[:, j])
# return msqrd
def msqrd(momenta):
    p1s = momenta[:, pairs.T[0], :]
    p2s = momenta[:, pairs.T[1], :]
    return np.prod(ldot(p1s, p2s), axis=0)

To integrate over phase space, we create a Rambo object from hazma.phase_space. We then call integrate, specifying how many Monte-Carlo points should be used to compute the integral:

from hazma import phase_space
cme = 20.0 # Center-of-mass energy
masses = [1.0, 2.0, 3.0, 4.0, 5.0] # Masses of the final state particles
rambo = phase_space.Rambo(cme=cme, masses=masses, msqrd=msqrd)
# Integrate! We use 2^14 points, this take ~20ms
rambo.integrate(n=1<<14)

Vector Form Factors

In version 2.0, we introduced vector form factors for a large set of mesonic final states. These form factors are available in hazma.form_factors.vector. All the form factors have a similar interface and similar functionality. We provide functions to compute:

  • the raw form-factor (scalar function coefficients of the Lorentz structures),
  • integrals of the form factors over phase space,
  • decay widths of a massive vector or cross section of dark matter annihilation,
  • energy distributions and invariant mass distributions of the final state mesons

Examples:

import hazma.form_factors.vector as vff

# compute pi-pi electromagnetic form-factor between 300 MeV and 1 GeV
ff_pipi = vff.VectorFormFactorPiPi()
energies = np.linspace(300.0, 1000.0, 100)
ff_pipi.form_factor(q=energies, gvuu=2.0/3.0, gvdd=-1.0/3.0)

# Integrate the pi-pi-pi0 form-factor over phase-space between 450 MeV and 1 GeV
ff_pipipi0 = vff.VectorFormFactorPiPiPi0()
energies = np.linspace(450.0, 1000.0, 100)
ff_pipipi0.integrated_form_factor(q=energies, gvuu=2.0/3.0, gvdd=-1.0/3.0, gvss=-1.0/3.0)

# Generate energy distributions of the pi0-k-k form factor at 1 GeV
ff_pikk = vff.VectorFormFactorPi0KpKm()
ff_pikk.energy_distributions(q=1000.0, gvuu=2.0/3.0, gvdd=-1.0/3.0, gvss=-1.0/3.0, nbins=100)

Community Extensions

The flexibility of Hazma allows for the implementation of a wide variety of dark matter models. Below are extensions and model implementations developed by the community:

If you have developed a public extension or model implementation using Hazma, feel free to open a pull request to add it to this list!

Other information

Citing

If you use Hazma in your own research, please cite our paper:

@article{Coogan:2019qpu,
      author         = "Coogan, Adam and Morrison, Logan and Profumo, Stefano",
      title          = "{Hazma: A Python Toolkit for Studying Indirect Detection
                        of Sub-GeV Dark Matter}",
      year           = "2019",
      eprint         = "1907.11846",
      archivePrefix  = "arXiv",
      primaryClass   = "hep-ph"
}

If you use any of the models we've included that rely on chiral perturbation theory, please also cite the paper explaining how they were constructed:

@article{Coogan:2021sjs,
    author = "Coogan, Adam and Morrison, Logan and Profumo, Stefano",
    title = "{Precision Gamma-Ray Constraints for Sub-GeV Dark Matter Models}",
    eprint = "2104.06168",
    archivePrefix = "arXiv",
    primaryClass = "hep-ph",
    month = "4",
    year = "2021"
}

Papers using hazma

  • arXiv
  • arXiv
  • arXiv

Logo design: David Reiman and Adam Coogan; icon from Freepik from flaticon.com.

Project links

Data verified by PyPI on Aug 4, 2026
Data provided by the project maintainers, verified at the time the release was uploaded to PyPI.

Key dates

PyPI data
Data sourced directly from PyPI's database.
  • Released:
Latest release

2 maintainers

PyPI data
Data sourced directly from PyPI's database.
Avatar for acoogan from gravatar.com acoogan Avatar for LoganAMorrison from gravatar.com LoganAMorrison

Credits

Author/Maintainer: Adam Coogan

GitHub Statistics

Data verified by PyPI on Aug 4, 2026
The GitHub source repository was provided by the project maintainers and verified by PyPI at the time of upload. Stars, forks, and open issues/PRs are derived from that repository and have not been independently verified.

Requires

Python >=3.10

Provides Extra

dev

Tags

dark-matter mev-dark-matter gamma-ray-spectra

Classifiers

Report project as malware

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

hazma-2.1.0.tar.gz (6.8 MB view details)

Uploaded Source

Built Distributions

If you're not sure about the file name format, learn more about wheel file names.

hazma-2.1.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (19.6 MB view details)

Uploaded CPython 3.14manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

hazma-2.1.0-cp314-cp314-macosx_11_0_arm64.whl (8.9 MB view details)

Uploaded CPython 3.14macOS 11.0+ ARM64

hazma-2.1.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (19.7 MB view details)

Uploaded CPython 3.13manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

hazma-2.1.0-cp313-cp313-macosx_11_0_arm64.whl (8.8 MB view details)

Uploaded CPython 3.13macOS 11.0+ ARM64

hazma-2.1.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (19.9 MB view details)

Uploaded CPython 3.12manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

hazma-2.1.0-cp312-cp312-macosx_11_0_arm64.whl (8.9 MB view details)

Uploaded CPython 3.12macOS 11.0+ ARM64

hazma-2.1.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (19.6 MB view details)

Uploaded CPython 3.11manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

hazma-2.1.0-cp311-cp311-macosx_11_0_arm64.whl (8.8 MB view details)

Uploaded CPython 3.11macOS 11.0+ ARM64

hazma-2.1.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl (19.0 MB view details)

Uploaded CPython 3.10manylinux: glibc 2.24+ x86-64manylinux: glibc 2.28+ x86-64

hazma-2.1.0-cp310-cp310-macosx_11_0_arm64.whl (8.8 MB view details)

Uploaded CPython 3.10macOS 11.0+ ARM64

File details

Details for the file hazma-2.1.0.tar.gz.

File metadata

  • Download URL: hazma-2.1.0.tar.gz
  • Upload date:
  • Size: 6.8 MB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for hazma-2.1.0.tar.gz
Algorithm Hash digest
SHA256 829d6677f40d21cb9502920fc51df7f30db7f66bc47f4d5853c37feee980caea
MD5 a688af0bfee31f7fadf43f3a7bc9c663
BLAKE2b-256 fa1169376482c68e075d5d08751824668c83bd901cd80b08bbb0f279028393a2

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0.tar.gz:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hazma-2.1.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for hazma-2.1.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 9930229c04b11341f78b6412b2fcf2ceb849bb920f95856415a66e768a239b2e
MD5 7ceeac6fd64c87466181ed6a70e7fa93
BLAKE2b-256 2c64043c7500b08f8a2382e08843c698b95a978083aef078ac0fb0261cebe4ee

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0-cp314-cp314-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hazma-2.1.0-cp314-cp314-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hazma-2.1.0-cp314-cp314-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 5c13fff56656b11323753116c23c1436cb7d4f85bf1fd6e6364f7534405e136e
MD5 859a2841156483dc59db754d77c993d1
BLAKE2b-256 f496a9531a18e4beaa6e968f3a5c0dae806725a9043d085ecd6eda3715ece24d

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0-cp314-cp314-macosx_11_0_arm64.whl:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hazma-2.1.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for hazma-2.1.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 97846b7193fe64fc1ec0cd0c867e4af1213d84c4966878ef5bdc7be251d9c83e
MD5 16d76804f16d51f4f6d19353b963e8f6
BLAKE2b-256 430121696fe999c5312a58ccabb8dacbacd471e00c71f1c1ed3d419677b081b1

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0-cp313-cp313-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hazma-2.1.0-cp313-cp313-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hazma-2.1.0-cp313-cp313-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 8eafa4f082dc25d0ebeda0812b2c1c0ca4d5dc1e38d4e3162c98149b63eeff51
MD5 af66bb01ba9a2bf6c1ad4444ba318ce2
BLAKE2b-256 b422bc0a83ae1a34f4107f6c6c5eef9114c00f9f3b14a610e5b4ad9e82447ba6

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0-cp313-cp313-macosx_11_0_arm64.whl:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hazma-2.1.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for hazma-2.1.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 55d91e731a7c63124129541559b42f2f7926cf4f886917b2471a46435294f21e
MD5 9410945aa6e386189ceb566745944608
BLAKE2b-256 fdc6fba2006c3fec992d8b4023454af55113529d1243c05717fa18b01ea985fb

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0-cp312-cp312-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hazma-2.1.0-cp312-cp312-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hazma-2.1.0-cp312-cp312-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 0e68f7f4dd4e7b4c8af8c573a2d50c61cab4386a3578b6a774e346c5e21a3e8e
MD5 c6f395bee48d918e61f7efc8a720d375
BLAKE2b-256 856739c9429464b90ae913009c3fa1349495d0378ffb232307921ca081734638

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0-cp312-cp312-macosx_11_0_arm64.whl:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hazma-2.1.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for hazma-2.1.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 1d65b953b4e1ad856f9f80d989b1bd6778d3653905f10b12a6ad64ed360e7940
MD5 8160a30d4011766f29ecc689b3a7c721
BLAKE2b-256 32dd82549968f7171789896aa0e122a675335983d69e7e39170aef79df8e4496

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0-cp311-cp311-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hazma-2.1.0-cp311-cp311-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hazma-2.1.0-cp311-cp311-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f610fe87fbe94cd8018083bdc58beb3d12ca2ba7fcb5eeb0ca2211daf08ed343
MD5 ca9247975c013ad9d173aefd8c24a301
BLAKE2b-256 74e1c4929996bc38368e6390995f10a734e4338c6dd7eea6fb796eb3573ede91

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0-cp311-cp311-macosx_11_0_arm64.whl:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hazma-2.1.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl.

File metadata

File hashes

Hashes for hazma-2.1.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl
Algorithm Hash digest
SHA256 f1bbb8b9b4d16accd4a809ff9b1e6e88e004e65f695ee8b2fb70b4d231078ee8
MD5 0cd263ed119b66a3b0ae07904b0e84e3
BLAKE2b-256 3d6650392eedbbe63a6048645f81c05a0b3fd8ec0d60cdad79a175477c1442bd

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0-cp310-cp310-manylinux_2_24_x86_64.manylinux_2_28_x86_64.whl:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

File details

Details for the file hazma-2.1.0-cp310-cp310-macosx_11_0_arm64.whl.

File metadata

File hashes

Hashes for hazma-2.1.0-cp310-cp310-macosx_11_0_arm64.whl
Algorithm Hash digest
SHA256 f1fda4f9c6ad71f225812ff114d9729698c25c7d4d56aeb672d6de03b2fb31a9
MD5 144d37b3dbb500b7e04dcca10ae0ffbe
BLAKE2b-256 652c77ce29aaed2321ab7c457e9b22a6fa3c2eab2e5b3058da627f8f0e4b8dd2

See more details on using hashes here.

Provenance

The following attestation bundles were made for hazma-2.1.0-cp310-cp310-macosx_11_0_arm64.whl:

Publisher: release.yml on LoganAMorrison/Hazma

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Release history Release notifications | RSS feed

This release

2.1.0 This release

11 files

1.1

4 files

1.0.3

5 files

1.0.2

5 files

1.0.1

7 files

1.0.0

8 files

0.1

4 files

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Depot Continuous Integration Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page