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 and 3D matrices in the .cmat format generated by the GASPware and gsort acquisition and sorting suites.

python-cmat includes dedicated subroutines and interactive analysis environments for 2D $\gamma$-$\gamma$ coincidence matrices and 3D matrix cubes (such as $\gamma$-$\gamma$-$\text{Rings}$ and $\gamma$-$\gamma$-$\Delta t$ datasets), featuring multi-plane orthogonal slicing, 3D coincidence gating, 2D Banana graphical ROIs, and Gamba & Morhác coincidence peak fitting.

---

Documentation Directory

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

🚀 Getting Started & Web Viewers

• Interactive Web Viewer Overview of the 2D browser interface, dual 1D projection engine, multi-matrix differential analysis, remote SSH access, and vector PDF export.
• 3D Matrix Analysis & Web Viewer Dedicated guide for 3D matrix cubes, memory-mapped caching, multi-plane orthoslicing (0-1, 0-2, 1-2), 3D coincidence cuts, and 2D polygonal Banana ROIs.
• 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 and python-cmat3d-config.txt settings, default discovery rules, per-axis energy calibration parameters, and saving options.
• Python API & CLI Tools Programmatic usage of CMATReader and CMAT3DReader 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 python3-matplotlib

• 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 & 2D/3D Banana ROIs: Arbitrary 1D peak gates ($W$) and background windows ($B$) with channel width normalization, plus 2D polygonal Banana ROIs (Shift+G Peak / Shift+B Bg) for 2D area integration/subtraction and 3D coincidence projection cuts.
• 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.