ncuhep 0.2.0

NCU High Energy Physics tools for muography and related analysis.

ncuhep

A small high-energy / astroparticle utilities library with a focus on muography and dimension-aware units.

The two main pieces are:

• ncuhep.muography – an end-to-end muography pipeline
  from raw DAQ _Mu.txt files → reconstructed tracks → Monte Carlo basis → flux map Φ(θₓ, θᵧ).
• ncuhep.units – a lightweight units system (Length, Time, Flux, …)
  with SI storage, attribute-style unit access, and dimensional arithmetic.

---

Features

Muography (ncuhep.muography)

• Detector geometry & configuration

  • PlaneDetector – detector geometry, pixel sizes, layer positions, channel → pixel mapping.
  • MuTxtFormat – description of your _Mu.txt DAQ format (columns, bit sizes, dtypes).
  • AnalysisConfig – time windows and multiplicity cuts for event building.

• Reconstruction pipeline

  • parser – raw _Mu.txt → timestamped hit records + live time.
  • identifier – hit list → cleaned, coincident events.
  • tracker – events → straight-line tracks in 3D with χ².

• Monte Carlo basis & geometric factor

  • MonteCarloRenderer – simulates straight muons through the same geometry, producing:
    • a 4D response basis basis[i_meas_x, i_meas_y, i_inc_x, i_inc_y]
    • a geometric factor map G(θₓᶦⁿᶜ, θᵧᶦⁿᶜ) in m²·sr
  • Optional multi-GPU acceleration via Numba/CUDA.

• Flux reconstruction

  • Combine reconstructed tracks + basis + geometric factor →
    flux map Φ(θₓ, θᵧ) in units of counts·m⁻²·s⁻¹·sr⁻¹.

---

Units (ncuhep.units)

• SI-based internal storage for each quantity (Length, Time, Mass, Flux, …).
• Attribute-based access to units:
  • L.mm = 50, L.m, T.s, T.h, ρ.g_cm3, Φ.counts_m2_s_sr, …
• Automatic dimensional arithmetic:
  • Length * Length → Area
  • Mass / Volume → Density
  • Counts / (Area * Time * SolidAngle) → Flux
• Generic fallback type (GenericQuantity) for any unregistered dimension.
• Basic support for custom units attached at runtime (e.g. “pixel” → 50 mm, “counts_cm2_min_sr”, …).

---

License

This project is currently distributed under the NCUHEP Research Read-Only License.

In short:

• ✅ You may download, run, and study the code for personal, educational, or academic research.
• ❌ You may not redistribute the code or modified versions of it.
• ❌ You may not use the code for commercial purposes.
• 📑 If you use the software or results produced by it in a publication or presentation, citation is mandatory (see the recommended citation in the LICENSE file).

The full legal terms are in LICENSE.

Author: Phay Kah Seng – [e-mail]

Installation

From PyPI:

pip install ncuhep