Home

Welcome to the python-cmat Wiki

python-cmat (pycmat) is a modern, standalone Python toolkit for nuclear physics data analysis. It enables experimentalists to decompress, inspect, convert, and interactively navigate proprietary 2D matrices in the .cmat format generated by the GASPware and gsort acquisition and sorting suites.

While designed as a general reader, converter, and visualizer for any 2D .cmat matrix, python-cmat features dedicated subroutines tailored for $\gamma$-$\gamma$ coincidence matrices (such as normalized coincidence gating, Gamba & Morhác 4-component coincidence background decomposition, and per-axis energy calibration). Future releases will introduce handling of 3D matrices as well as time-difference spectra.

---

Documentation Directory

Explore the full documentation topics below or navigate using the sidebar:

🚀 Getting Started & Web Viewer

• Interactive Web Viewer Overview of the high-performance browser interface, dual 1D projection engine, multi-matrix differential analysis, remote SSH access, and vector PDF export.
• Keyboard Shortcuts & Controls Complete reference for all mouse gestures, hotkeys, gate limit definitions, peak fitting shortcuts, and viewport navigation.

🔬 Analysis & Scripting

• Spectroscopy Commands & Macros Comprehensive manual for the headless spectroscopy engine, command-line one-liners, interactive REPL shell, and automated batch macro scripts (*.mac).
• Configuration Guide Detailed explanation of python-cmat-config.txt settings, default discovery rules, per-axis energy calibration parameters, and saving options.
• Python API & CLI Tools Programmatic usage of CMATReader in Python scripts/Jupyter notebooks and the cmat2amat.py command-line matrix conversion tool.

📐 Scientific Theory & File Specifications

• Peak Fitting & Background Models Rigorous mathematical formulations for 1D and 2D photopeak models (Gaussian, RadWare/SAMPO exponential tails, Hypermet EMG), Gamba & Morhác 4-component coincidence background decomposition, CWT continuous wavelet peak search, and the Peak-Aware Continuum baseline engine.
• Format Reference & Decompression Detailed reverse-engineered specification of the IVF .cmat file container (512-byte records, sub-matrix block grids, asymmetric step sizes) and Modes 0–41 decompression routines.
• Scientific References Complete bibliography of foundational papers and citations covering gamma-ray spectroscopy algorithms.

---

Quick Installation & Setup

Prerequisites (Ubuntu / Debian Linux)

sudo apt update && sudo apt install python3 python3-pip python3-venv

Clone & Install

git clone https://github.com/rlica/python-cmat.git
cd python-cmat

On modern Linux environments enforcing PEP 668 (externally-managed-environment):

• Virtual Environment (Recommended):

  python3 -m venv .venv && source .venv/bin/activate
  pip install -r requirements.txt

• System APT Packages (Zero venv setup):

  sudo apt install python3-numpy python3-scipy

• Direct Pip Flag:

  pip install -r requirements.txt --break-system-packages

---

Key Capabilities at a Glance

• Pure Python + NumPy Decompression: Fully reverse-engineers all proprietary IVF block compression algorithms (Modes 0–32 bit-packing, Mode 33 16-bit sparse lists, Mode 34 32-bit sparse lists, Mode 37 tagged token bit-streams, and Mode 41 unary run-length shift maps) without requiring legacy 32-bit Fortran binaries or external C libraries.
• Arbitrary Geometry: Handles symmetric, asymmetric, and arbitrary step sizes ($32 \times 32$, $32 \times 64$, $64 \times 128$, $128 \times 128$, etc.).
• Interactive Web Interface: Ultra-responsive HTML5 Canvas architecture with pixel-matched data decimation and 2D max-pooling to preserve narrow photopeaks even when viewing the entire 4096×4096 matrix.
• Simultaneous Dual 1D Projections: Stacked top/bottom stepped staircase histograms displaying Det 1 (X projection sliced over visible Y) and Det 2 (Y projection sliced over visible X) with synchronized crosshair tracking and calibrated energy readouts.
• Advanced 1D Peak Fitting: Fits Standard Symmetric Gaussian, RadWare / SAMPO Left Exponential Tail, and Hypermet Convolved Tail + $\text{erfc}$ Compton Step models with complete statistical covariance error propagation.
• Multi-Gate Slicing with Background Subtraction: Arbitrary peak gates ($W$) and background windows ($B$) with automated channel width normalization ($\text{Scale} = \sum \Delta W / \sum \Delta B$).
• True 2D Coincidence Peak Fitting: Gamba & Morhác 4-component decomposition separating net coincidence volume ($p|p^t$), orthogonal cross-ridges ($p|bg$, $bg|p$), and 2D Compton continuum + randoms ($bg|bg$).
• Multi-Matrix Comparison: Instant cycling between loaded matrices with locked viewport coordinates, coincidence gates, and auto-refitted peak parameters.
• Automated CWT Peak Search & Multi-Fit: Continuous Wavelet Transform detection combined with Peak-Aware Continuum baseline estimation that handles noise grass in background-subtracted coincidence cuts without clipping bias.
• Vector PDF Publication Engine: Produces vector PDF figures with Times New Roman typography, calibrated axes, stepped histograms, fit curves, and background baselines.