WimPyDD: Modular Code for WIMP Detection

• WimPyDD Code is a modular Python toolkit designed for calculating Weakly Interacting Massive Particle direct-detection signals via factorized effective operator decomposition.
• It integrates particle, nuclear, and astrophysical physics using object-oriented principles, enabling rapid evaluation over high-dimensional parameter spaces.
• The framework supports inelastic scattering, arbitrary WIMP spin, and various Galactic halo models while optimizing performance through precomputed response functions.

WimPyDD is a modular, object-oriented Python codebase for the calculation of Weakly Interacting Massive Particle (WIMP) direct-detection signals within the Galilean-invariant non-relativistic effective theory (NREFT) framework. Its architecture is designed to handle virtually any physical and experimental scenario, including inelastic scattering, arbitrary WIMP spin, and generic Galactic halo velocity distributions. WimPyDD facilitates phenomenological studies of the direct-detection rate via effective operator decompositions and factorized computational design, offering transparency and rapid evaluation even for high-dimensional model parameter spaces (Jeong et al., 2021, Tomar et al., 2021).

1. Architecture and Modular Design

WimPyDD is constructed in Python (v3.7) following explicit modular and object-oriented principles. The computation of expected event rates is segmented across three independent domains:

• Particle Physics: Managed with effective operators and Wilson coefficient functions that link the ultraviolet completion of the high-energy theory to observable nuclear interactions. The eft_hamiltonian class formalizes the Hamiltonian, while Wilson coefficients may depend on the WIMP mass ($m_\chi$), mass splitting ($\delta$), or momentum transfer ($q$).
• Nuclear Physics/Detector Response: Encapsulated in element classes (for isotopes), target classes (for detector compounds), and an experiment class that codifies exposure, detector resolution, efficiency, quenching factors, and binning. Integrated nuclear and detector response functions are precomputed and stored, enabling fast interpolation during signal evaluation.
• Astrophysics: The Galactic halo is parametrized via a halo function derived from the WIMP velocity distribution $f(v,t)$; computational routines can accommodate Maxwellian, non-Maxwellian, or user-defined distributions. The streamed_halo_function supports arbitrary superpositions of velocity streams.

These modules are decoupled and their outputs stored separately for interpolation, which minimizes repetitive computation and enhances efficiency in parameter scans.

2. Calculation Components and Mathematical Formalism

Three factorized quantities are convolved to produce the direct-detection signal:

• Wilson Coefficients ($c_j^\tau$): Encode model-dependent physics in the effective Hamiltonian

$$\mathcal{H}(w_i, q) = \sum_{\tau=0,1}\sum_j c_j^{(\tau)}(w_i, q) \, \mathcal{O}_j(\mathbf{q}) \, t^{(\tau)}$$

• Nuclear/Detector Response ($\overline{\mathcal{R}}_T$): Encompass recoil spectra and experimental resolution
• Halo Function ($\eta(v, t)$): Represents the astrophysical component

$$\eta(v, t) = \int_{v}^{\infty} \frac{f(v', t)}{v'} d^3 v'$$

The master rate formula aggregates these elements:

$$S^{(0,1)}_{[E'_1, E'_2]} = \frac{\rho_\chi}{m_\chi} \sum_k \delta\eta_k^{(0,1)} \int_{E_R^{\min}(v_k)}^{E_R^{\max}(v_k)} \left[ \overline{\mathcal{R}}^0_T(E_R) + (v_k^2 - v_{T,\min}^2(E_R)) \overline{\mathcal{R}}^1_T(E_R) \right] dE_R$$

where $\rho_\chi$ is the local DM density, and $v_{T,\min}$ the recoil-dependent threshold velocity.

This factorized convolution structure is central; nuclear response functions depend solely on recoil energy and experiment details, independent of WIMP mass and couplings, permitting precomputation.

3. Supported Physical and Experimental Scenarios

The code supports a comprehensive parameter space:

• Inelastic Scattering: Changing the mapping $E_R^{\min}(v)$ and $v_{\min}(E_R)$ to encode mass splitting $\delta$ scenarios; kinematic thresholds are dynamically computed.
• Arbitrary WIMP Spin: For $j_\chi = 1/2$, the standard NREFT operator basis (e.g., 14 operators). For $j_\chi > 1/2$, the operator basis is extended as in Ref. [all_spins], allowing for irreducible tensor decompositions and higher-order operator contributions.
• Generic Halo Models: Default Maxwellian velocity distributions may be substituted with stream or user-defined models. Annual modulation effects ($\eta^{(1)}$, DAMA/LIBRA-like analyses) can be calculated.
• Compound Detectors and Multiple Targets: Objects representing compound targets (e.g., NaI, LNGS-based multi-nucleus detectors) can be instantiated and their contributions computed individually or as stoichiometric combinations.

Customization is facilitated through user-defined Python functions for Wilson coefficients, effective Hamiltonians, and halo functions.

4. Efficiency, Performance, and Scaling

WimPyDD's computational strategy emphasizes precomputation:

• Response Functions are tabulated as a function of recoil energy for each experimental setup and stored as interpolated tables on disk.
• Signal Evaluation is reduced to fast combination: when scanning the model parameter space (over $m_\chi$, $\delta$, couplings $w_i$), only the model-dependent factors (Wilson coefficients) are re-evaluated and contracted with the pre-tabulated response and halo outputs.
• Scaling: This approach is especially effective for large-dimensional scans and interference patterns among operators due to the decoupling of operator, nuclear response, and astrophysical pieces. The computational cost grows sublinearly with parameter space dimensionality after the initial tabulation.

5. Exemplary Use Cases and Practical Application

Several concrete calculations exemplify the code's extensibility:

Application	Description	Key Routines
Differential rate in NaI	Computes recoil spectrum for NaI detector; operator and isospin decompositions	diff_rate, elements_list
Integrated rate (detector bins)	Calculates binned rates using experiment specifics	wimp_dd_rate
Exclusion plots (σ_p, M)	Parameter scan over $m_\chi$ to generate exclusion curves, e.g., XENON1T	mchi_vs_exclusion
Annual modulation	Computes modulated rates for DAMA/LIBRA-phase2 dataset	Provided examples
Nonstandard physics scenarios	Implements custom Wilson coefficients, operator combinations	User Python functions

For time-averaged rates:

$$R_{[E'_1, E'_2]}(t) = \frac{\rho_\chi}{m_\chi} \int_{v_*}^{\infty} dv\, \mathcal{R}_{T,[E'_1,E'_2]}(v)\, \eta(v,t)$$

where $v_* = \sqrt{2\delta/\mu_{\chi T}}$ is the inelastic scattering threshold velocity.

6. Limitations and Assumptions

WimPyDD is predicated on several assumptions:

• Non-Relativistic Effective Theory: All interactions are described by Galilean-invariant NREFT operators; relativistic corrections are not included.
• Factorization: Assumes independence of Wilson coefficients, nuclear response functions, and the halo function; extensions beyond this structure may require significant customization.
• Dependence on External Data: Users must supply accurate nuclear response and experimental data (e.g., XENON1T or PICO60 files); any uncertainties in these propagate into predictions.
• Velocity Distribution Choices: While arbitrary distributions are supported, standard routines typically employ discrete stream decompositions or Maxwellian forms; not all astrophysical uncertainties may be fully represented.

7. Significance and Phenomenological Impact

WimPyDD provides a transparent and efficient tool for the calculation of direct-detection event rates, tailored to both top-down (ultraviolet model matching) and bottom-up (model-independent operator scans) studies. Users can rapidly test effective theories, produce exclusion limits, and analyze detector responses under diverse experimental and physical assumptions. The code's factorized, object-oriented design enables targeted studies (from elastic and inelastic scattering to arbitrarily high-spin WIMPs, and halo-independent approaches) that were previously difficult to achieve without custom tooling.

This architectural paradigm, now reflected in extended modules such as WimPyC for WIMP capture studies (Kang et al., 24 Oct 2025), is recognized for both computational transparency and extensibility, facilitating robust and systematic phenomenological analysis of dark matter detection in direct-detection experiments.