# 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`](./LICENSE).

Author: **Phay Kah Seng** – <phay_ks@icloud.com>


## Installation

From PyPI:

```bash
pip install ncuhep
