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.

The viewers can also load TH1/TH2 histograms from ROOT files and stream live TH1/TH2/TH3 histograms from the ROOT THttpServer (including c4Root), applying the same gating and fitting tools.

---

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.
• ROOT Files & Live Histograms ROOT file input (TH1/TH2 via uproot), live TH1/TH2/TH3 streaming from ROOT THttpServer / c4Root, live TH3 plane gating with double gates and polygon cuts, and time-spectra half-life fits.

🔬 Analysis & Scripting

• ENSDF Automated Isotope Identification Offline Evaluated Nuclear Structure Data File (ENSDF) search engine, 2D prompt cascade matching, global mass-clustering parsimony, and interactive web pop-up file browser.
• 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.
• Sparse On-Demand 3D Engine: Fast direct block-indexing engine (.cmat3d_cache/<file>.idx) that opens massive 3D symmetric cubes ($8192^3$ channels, $>2\text{ TB}$ uncompressed) in $<0.5\text{ s}$ and extracts gated slices on-demand in $<10\text{ ms}$ without disk explosion or RAM exhaustion.
• Exact Diagonal Symmetrization (2D & 3D): Dual-level intra-block tetrahedral unfolding for 3D matrices and diagonal multiplicity unfolding ($2 \times \text{val}$) for 2D symmetric matrices, completely resolving dark diagonal lines/triangular artifacts and maintaining exact match with 1D stored projections ($\Delta = 0$).
• Gamba 3D Coincidence Slicing: Automatically decomposes 3rd axis coincidence projections with 4-component Gamba discrete background subtraction ($P|P, P|BG, BG|P, BG|BG$) when fitting 2D coincidence peaks in 3D volumes.
• 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.
• ROOT File & Live Histogram Support: TH1/TH2 readout from local ROOT files through uproot, and live TH1/TH2/TH3 streaming from ROOT THttpServer / c4Root — no PyROOT or local ROOT installation required, with all existing gates, fits, Banana ROIs, and PDF export working unchanged.
• Live TH3 Analysis: Orthogonal-plane display of live TH3 cubes (e.g. energy–energy–time) from full immutable JSON snapshots, with double $W$ gates, polygon cuts, and half-life fitting on the time axis.
• 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 (a Peak / b Bg vertices at the cursor) 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.