numerics

MonkhorstPackGrid(N_grid, material, shift=True, use_sym=False)

A class representing a Monkhorst-Pack grid for Brillouin zone sampling.

Attributes:

Name	Type	Description
k_frac	ndarray	The fractional coordinates of the k vectors.
weights	ndarray	The weights of the k vectors.

N_grid (ArrayLike): The number of grid points along each reciprocal lattice vector. material (Material): The material for which the grid is generated. shift (bool): Whether to shift the grid. Defaults to a shifted grid to avoid singularities in DWF. use_sym (bool, optional): Whether to use symmetry to reduce the number of grid points. Defaults to False. The W tensor is only calculated once so this isn't necessary to use and causes issues.

Source code in darkmagic/numerics.py

def __init__(
    self,
    N_grid: ArrayLike,
    material: Material,
    shift: bool = True,
    use_sym: bool = False,
):
    """
    Constructor for the MonkhorstPackGrid class.

    N_grid (ArrayLike): The number of grid points along each reciprocal lattice vector.
    material (Material): The material for which the grid is generated.
    shift (bool): Whether to shift the grid. Defaults to a shifted grid to avoid singularities in DWF.
    use_sym (bool, optional): Whether to use symmetry to reduce the number of grid points. Defaults to False. The W tensor is only calculated once so this isn't necessary to use and causes issues.
    """
    shift = [1, 1, 1] if shift else [0, 0, 0]
    # SGA struggles with the struct in 1/eV, so we scale back to ang
    struct = deepcopy(material.structure)
    struct.scale_lattice(struct.volume * (const.inveV_to_Ang) ** 3)
    sga = SpacegroupAnalyzer(struct)
    if use_sym:
        points = sga.get_ir_reciprocal_mesh(N_grid, is_shift=shift)
        self.k_frac, self.weights = map(np.array, zip(*points))
    else:
        self.k_frac, _ = sga.get_ir_reciprocal_mesh_map(N_grid, is_shift=shift)
        self.weights = np.ones_like(self.k_frac[:, 0])

SphericalGrid(m_chi, v_e, use_q_cut, N_grid, material)

Represents a spherical grid used for numerical calculations in DarkMAGIC.

Attributes:

Name	Type	Description
nq	int	The number of q points.
q_max	float	The maximum value of the q vector (eV).
q_cart	ndarray	The Cartesian coordinates of the q vectors (eV).
q_frac	ndarray	The fractional coordinates of the q vectors.
q_norm	ndarray	The norms of the q vectors (eV).
q_hat	ndarray	The unit vectors of the q vectors.
G_cart	ndarray	The Cartesian coordinates of the G vectors (eV).
G_frac	ndarray	The fractional coordinates of the G vectors.
jacobian	ndarray	The Jacobian determinant for the spherical grid.
k_frac	ndarray	The fractional coordinates of the k vectors.
k_cart	ndarray	The Cartesian coordinates of the k vectors.

Parameters:

Name	Type	Description	Default
m_chi	float	The mass of the dark matter particle.	required
v_e	ArrayLike	The velocity of the Earth.	required
use_q_cut	bool	Whether to use the q_cut value.	required
N_grid	ArrayLike	The number of grid points (radial, azimuthal, polar)	required
material	Material	A Material object containing the material properties.	required

Source code in darkmagic/numerics.py

def __init__(
    self,
    m_chi: float,
    v_e: ArrayLike,
    use_q_cut: bool,
    N_grid: ArrayLike,
    material: Material,
):
    """
    Spherical grid constructor.

    Args:
        m_chi: The mass of the dark matter particle.
        v_e: The velocity of the Earth.
        use_q_cut: Whether to use the q_cut value.
        N_grid: The number of grid points (radial, azimuthal, polar)
        material: A Material object containing the material properties.
    """
    # Get q and G vectors
    q_cut = material.q_cut if use_q_cut else 1e10
    self.q_max = min(2 * m_chi * (const.VESC + const.VE), q_cut)
    self.q_cart, self.q_frac = self._get_q_points(
        N_grid, m_chi, v_e, material.recip_cart_to_frac
    )
    self.nq = self.q_cart.shape[0]
    # These show up often so it's efficient to compute them only once
    self.q_norm = LA.norm(self.q_cart, axis=1)
    self.q_hat = self.q_cart / self.q_norm[:, None]

    # Get G-vectors
    self.G_cart, self.G_frac = self._get_G_vectors(material.recip_frac_to_cart)
    # Deriving this is straightforward, remember we're sampling
    # with a power of 2 in the q direction, hence the square roots on |q|
    self.jacobian = 8 * np.pi * self.q_norm ** (5 / 2) * self.q_max ** (1 / 2)
    # Volume element dV = d^3q J(q) / (2pi)^3 / N^3
    self.vol_element = self.jacobian / ((2 * np.pi) ** 3 * np.prod(N_grid))

    # Get the k-vectors
    self.k_frac = self.q_frac - self.G_frac
    self.k_cart = np.matmul(self.k_frac, material.recip_frac_to_cart)

    # Outer product of qhat with itself is frequently used
    self._qhat_qhat = None

Numerics(N_grid=None, N_DWF_grid=None, bin_width=0.001, use_q_cut=True, use_special_mesh=False, threshold=0, power_abc=None)

A class that represents the numerical parameters for DarkMAGIC calculations.

Parameters:

Name	Type	Description	Default
N_grid	ArrayLike	The number of grid points in each dimension. Defaults to [20, 10, 10].	None
power_abc	ArrayLike	The power of each dimension in the grid. Defaults to [2, 1, 1].	None
N_DWF_grid	ArrayLike	The number of grid points in each dimension for the density-weighted Fermi grid. Defaults to [20, 20, 20].	None
bin_width	float	The width of the bin. Defaults to 1e-3 (1 meV).	0.001
use_q_cut	bool	Whether to use a cutoff in momentum space. Defaults to True.	True
use_special_mesh	bool	Whether to use a special mesh for the grid. Defaults to False.	False

Attributes:

Name	Type	Description
N_grid	ndarray	The number of grid points in the spherical grid used to sample the momentum transfer (radial, azimuthal, polar).
power_abc	ndarray	The power of each dimension in the grid (currently unsued)
N_DWF_grid	ndarray	The size of the Monkhorst-Pack grid used to compute the Debye-Waller factor.
bin_width	float	The width of the energy bin. Rebinning to larger bins is possible in postprocessing.
use_q_cut	bool	Whether to use a cutoff for the momentum transfer from DM. If False, the cutoff is set to the maximum possible value \(2 m_{\chi} (v_{\text{esc}} + v_{\text{e}})\).
use_special_mesh	bool	Whether to use a special mesh for the spherical grid (currently unused)

Methods:

Name	Description
get_grid	float, v_e: ArrayLike, material: Material) -> SphericalGrid: Returns the spherical grid for the given dark matter mass, Earth velocity, and material.
get_DWF_grid	Material) -> MonkhorstPackGrid: Returns the Monkhorst-Pack grid for computing the Debye-Waller factor.

Parameters:

Name	Type	Description	Default
N_grid	ndarray	The number of grid points in the spherical grid used to sample the momentum transfer (radial, azimuthal, polar).	None
power_abc	ndarray	The power of each dimension in the grid (currently unsued)	None
N_DWF_grid	ndarray	The size of the Monkhorst-Pack grid used to compute the Debye-Waller factor.	None
bin_width	float	The width of the energy bin. Rebinning to larger bins is possible in postprocessing.	0.001
use_q_cut	bool	Whether to use a cutoff for the momentum transfer from DM. If False, the cutoff is set to the maximum possible value \(2 m_{\chi} (v_{\text{esc}} + v_{\text{e}})\).	True
use_special_mesh	bool	Whether to use a special mesh for the spherical grid (currently unused)	False
threshold	float	unused, DarkMAGIC does not impose any thresholds during the actual calculation. Maintained for backwards compatibility.	0

Source code in darkmagic/numerics.py

def __init__(
    self,
    N_grid: ArrayLike = None,
    N_DWF_grid: ArrayLike = None,
    bin_width: float = 1e-3,
    use_q_cut: bool = True,
    use_special_mesh: bool = False,
    threshold=0,
    power_abc: ArrayLike = None,
):
    r"""
    Constructor for the Numerics class.

    Args:
        N_grid (ndarray): The number of grid points in the spherical grid used to sample the momentum transfer (radial, azimuthal, polar).
        power_abc (ndarray): The power of each dimension in the grid (currently unsued)
        N_DWF_grid (ndarray): The size of the Monkhorst-Pack grid used to compute the Debye-Waller factor.
        bin_width (float): The width of the energy bin. Rebinning to larger bins is possible in postprocessing.
        use_q_cut (bool): Whether to use a cutoff for the momentum transfer from DM. If False, the cutoff is set to the maximum possible value $2 m_{\chi} (v_{\text{esc}} + v_{\text{e}})$.
        use_special_mesh (bool): Whether to use a special mesh for the spherical grid (currently unused)
        threshold (float): unused, DarkMAGIC does not impose any thresholds during the actual calculation. Maintained for backwards compatibility.
    """
    if N_grid is None:
        N_grid = [20, 10, 10]
    if power_abc is None:
        power_abc = [2, 1, 1]
    if N_DWF_grid is None:
        N_DWF_grid = [20, 20, 20]
    self.N_grid = np.array(N_grid)
    self._power_abc = np.array(power_abc)
    self.N_DWF_grid = np.array(N_DWF_grid)
    self.bin_width = bin_width
    self.use_q_cut = use_q_cut
    self._use_special_mesh = use_special_mesh
    self._threshold = threshold

from_dict(d) classmethod

Create a Numerics object from a dictionary.

Parameters:

Name	Type	Description	Default
d	dict	The dictionary containing the numerical parameters.	required

Returns:

Name	Type	Description
Numerics		The Numerics object.

Source code in darkmagic/numerics.py

@classmethod
def from_dict(cls, d: dict):
    """
    Create a Numerics object from a dictionary.

    Args:
        d (dict): The dictionary containing the numerical parameters.

    Returns:
        Numerics: The Numerics object.
    """
    return cls(
        d["N_grid"],
        d["N_DWF_grid"],
        d["bin_width"],
        d["use_q_cut"],
        d["_use_special_mesh"],
        d["_threshold"],
        d["_power_abc"],
    )

to_dict()

Convert the Numerics object to a dictionary.

Returns:

Name	Type	Description
dict		The dictionary containing the numerical parameters.

Source code in darkmagic/numerics.py

def to_dict(self):
    """
    Convert the Numerics object to a dictionary.

    Returns:
        dict: The dictionary containing the numerical parameters.
    """
    return {
        "N_grid": self.N_grid,
        "N_DWF_grid": self.N_DWF_grid,
        "bin_width": self.bin_width,
        "use_q_cut": self.use_q_cut,
        "_use_special_mesh": self._use_special_mesh,
        "_threshold": self._threshold,
        "_power_abc": self._power_abc,
    }

get_grid(m_chi, v_e, material)

Returns the spherical grid object.

Parameters:

Name	Type	Description	Default
m_chi	float	The mass of the dark matter particle.	required
v_e	ArrayLike	The velocity of the Earth.	required
material	Material	The material object.	required

Returns:

Name	Type	Description
SphericalGrid	SphericalGrid	The spherical grid object.

Source code in darkmagic/numerics.py

def get_grid(
    self, m_chi: float, v_e: ArrayLike, material: Material
) -> SphericalGrid:
    """
    Returns the spherical grid object.

    Args:
        m_chi (float): The mass of the dark matter particle.
        v_e (ArrayLike): The velocity of the Earth.
        material (Material): The material object.

    Returns:
        SphericalGrid: The spherical grid object.
    """
    return SphericalGrid(m_chi, v_e, self.use_q_cut, self.N_grid, material)

get_DWF_grid(material)

Returns the density-weighted Fermi grid object.

Parameters:

Name	Type	Description	Default
material	Material	The material object.	required

Returns:

Name	Type	Description
MonkhorstPackGrid	MonkhorstPackGrid	The density-weighted Fermi grid object.

Source code in darkmagic/numerics.py

def get_DWF_grid(self, material: Material) -> MonkhorstPackGrid:
    """
    Returns the density-weighted Fermi grid object.

    Args:
        material (Material): The material object.

    Returns:
        MonkhorstPackGrid: The density-weighted Fermi grid object.
    """
    return MonkhorstPackGrid(self.N_DWF_grid, material)