# uLib

[![DOI](https://zenodo.org/badge/36926725.svg)](https://zenodo.org/badge/latestdoi/36926725)

**uLib** is the base toolkit library for the **CMT (Cosmic Muon Tomography)** project, developed at the University of Padova and INFN Sezione di Padova, Italy.

It provides:

- **Core** – object model, timers, configuration, UUID utilities.
- **Math** – linear algebra (Eigen3), structured grids, voxel images, ray-tracing, image filters.
- **Python bindings** – full pybind11 interface for scripting and analysis workflows.
- Optional **CUDA** acceleration for voxel filtering (transparent RAM ↔ VRAM management).

---

## Quick Start

=== "Users (pip / poetry)"
    ```bash
    # Activate your conda/micromamba environment first
    micromamba activate mutom

    poetry install            # CPU build
    USE_CUDA=ON poetry install # GPU build
    ```

=== "Developers (CMake)"
    ```bash
    conan install . --output-folder=build --build=missing
    cmake --preset conan-release
    cmake --build build --target uLib_python -j$(nproc)

    export PYTHONPATH="$(pwd)/build/src/Python:$(pwd)/src/Python"
    ```

Then in Python:

```python
import uLib

# Core
timer = uLib.Core.Timer()
timer.Start()

# Math
grid = uLib.Math.StructuredGrid([10, 10, 10])
grid.SetSpacing([1.0, 1.0, 1.0])

img = uLib.Math.VoxImage([10, 10, 10])
img.SetValue(0, 3.14)
print(img.GetValue(0))
```

---

## Documentation Sections

| Section | Description |
|---|---|
| [Python – Installation](python/installation.md) | Environment setup, user install, developer build |
| [Python – API Usage](python/usage.md) | Full API reference with examples |
| [Python – Developer Guide](python/developer_guide.md) | Adding bindings, running tests, build details |
| [C++ Build – Usage & CUDA](usage/usage.md) | CMake build, CUDA configuration |