General-purpose utilities, fitting functions, and ALCOR address decoders. More...

#include <cstdint>
#include <optional>
#include <vector>
#include <random>
#include <unordered_set>
#include <fstream>
#include <filesystem>
#include <Math/Functor.h>
#include <Fit/Fitter.h>
#include <TEllipse.h>
#include <TH1.h>
#include <TH2.h>
#include <TGraph.h>
#include <TGraph2D.h>
#include <TFile.h>
#include <TTree.h>
#include <TF1.h>
#include <TProfile.h>
#include <Math/Minimizer.h>
#include <functional>
#include <iostream>
#include <mist/mist.h>

Functions
uint32_t	encode_bit (uint8_t active_bit)
	Encode a single bit into a 32-bit mask.

uint32_t	encode_bits (const std::vector< uint8_t > &active_bits)
	Encode multiple bits into a 32-bit mask.

uint8_t	count_trailing_zeros (uint32_t mask)
	Count trailing zeros (portable C++17)

std::vector< uint8_t >	decode_bits (uint32_t mask)
	Decode a 32-bit mask into the indices of set bits.

ALCOR global-index address decoders
Extract sub-fields from a packed global TDC index. The global index is defined as: (device-192)1024 + chip32 + eo_channel/44 + tdc Todo:* Move to mapping.h once the device-numbering convention is stabilised.
int	get_hit_tdc_from_global_tdc_index (int global_tdc_index)
	Extract the TDC sub-index (0–3) from a global TDC index.

int	get_device_from_global_tdc_index (int global_tdc_index)
	Decode the readout device ID (192+) from a global TDC index.

int	get_fifo_from_global_tdc_index (int global_tdc_index)
	Decode the FIFO number from a global TDC index.

int	get_chip_from_global_tdc_index (int global_tdc_index)
	Decode the chip number from a global TDC index.

int	get_eo_channel_index_from_global_tdc_index (int global_tdc_index)
	Decode the even/odd channel index from a global TDC index.

int	get_column_from_global_tdc_index (int global_tdc_index)
	Decode the column address from a global TDC index.

int	get_pixel_from_global_tdc_index (int global_tdc_index)
	Decode the pixel address from a global TDC index.

int	get_calib_index_from_global_tdc_index (int global_tdc_index)
	Compute the calibration look-up index from a global TDC index.

int	get_device_index_from_global_tdc_index (int global_tdc_index)
	Compute the per-device flat index from a global TDC index.

int	get_pdu_from_global_tdc_index (int global_tdc_index)
	Decode the PDU number (1-based) from a global TDC index.

int	get_matrix_from_global_tdc_index (int global_tdc_index)
	Decode the matrix number (1-based) from a global TDC index.

uint32_t	get_global_index (int device, int chip, int channel, int tdc)
	Pack device, chip, channel, and TDC sub-index into a global TDC index.

ROOT file helpers
TFile *	open_or_build_rootfile (const std::string &filename, std::function< void(std::string, std::string, int, bool, int, std::string, std::string, std::string)> builder, const std::string &data_repository, const std::string &run_name, int max_spill, bool force_rebuild=false)
	Open a ROOT file for reading, rebuilding it if missing or corrupted.

ROOT graphical helpers
void	draw_circle (std::array< float, 3 > parameters, int line_colour=kBlack, int line_style=kSolid, int line_width=1)
	Draw a circle on the current ROOT canvas pad.

Circle fitting
Least-squares circle fit minimising radial residuals.
using	circle_fit_results = std::array< std::array< float, 2 >, 3 >
	Result type: { {x0,σx0}, {y0,σy0}, {R,σR} }.

circle_fit_results	fit_circle (std::vector< std::array< float, 2 > > points, std::array< float, 3 > initial_values, bool fix_XY=true, std::vector< int > exclude_points={{}})
	Fit a circle to a set of 2-D points.

Ring model and fit utilities
Analytical ring signal model and histogram-based ring fitter.
using	ring_fit_results = std::array< std::array< double, 2 >, 6 >
	Result type for ring fits: { {x0,σ}, {y0,σ}, {R,σ}, {sigma_R,σ}, {N,σ}, {bkg,σ} }.

double	logistic (double variable, double amplitude, double center_1, double sigma_1, double center_2, double sigma_2)
	Difference-of-logistic function used to model azimuthal acceptance gaps.

double	clip_phi (double phi, double low_bound, double high_bound)
	Clip an angle to a given range (placeholder — currently returns -1).

double	ring_fit_function_sigma_function (double phi, double baseline_sigma, std::vector< std::array< double, 4 > > input_values={})
	Azimuthally-varying ring-width model.

double	ring_fit_function (std::array< double, 2 > input_values, std::array< double, 6 > parameters, std::vector< std::array< double, 4 > > logistic_input_values={})
	Evaluate the ring signal + flat background model in (R, φ) coordinates.

double	ring_fit_function_xy (std::array< double, 2 > input_values, std::array< double, 6 > parameters, std::vector< std::array< double, 4 > > logistic_input_values={})
	Evaluate the ring model in Cartesian (x, y) coordinates.

double	ring_fit_function_xy (std::array< double, 2 > input_values, const double *parameters, int how_many_logistics=0)
	Overload accepting a raw C-style parameter array (ROOT fitter compatible).

ring_fit_results	fit_ring_integral (TH2 *target_histogram, std::array< double, 6 > initial_values, bool fix_XY=true)
	Fit a 2-D ring model to a histogram using chi-squared minimisation.

std::vector< TGraph * >	plot_ring_integral (ring_fit_results fit_results, std::vector< float > sigma_values, std::vector< std::array< double, 4 > > logistic_input_values={}, int n_points=500)
	Generate ring-contour TGraphs at specified sigma levels from a fit result.

Global random-number generator
A single shared Mersenne-Twister engine used for pixel-position smearing. Todo: Move to a dedicated header or a utility singleton.
std::random_device	_global_rd_
	Seeding device for _global_gen_.

std::mt19937	_global_gen_ (_global_rd_())
	Mersenne-Twister 19937 engine seeded from _global_rd_.

std::uniform_real_distribution	_rnd_ (0.0, 1.0)
	Uniform float distribution in [0, 1).

Detailed Description

General-purpose utilities, fitting functions, and ALCOR address decoders.

Todo:

: in multiple spills parallelise I/O and frames processing

: git workflow formatting

Provides:

Bit manipulation — encode_bit, encode_bits, decode_bits.
Global RNG — a shared Mersenne-Twister generator and uniform float distribution.
ALCOR address decoders — inline functions to extract device, chip, FIFO, column, pixel, and PDU from a packed global TDC index.
Circle and ring fitting — fit_circle, fit_ring_integral and helpers.
ROOT graphical helpers — draw_circle, open_or_build_rootfile.

Note: The address decoder functions and the global RNG are candidates for migration to mapping.h and a dedicated RNG header respectively.

Function Documentation

◆ clip_phi()

double clip_phi	(	double	phi,
		double	low_bound,
		double	high_bound
	)

inline

Clip an angle to a given range (placeholder — currently returns -1).

Parameters

phi	Input angle [rad].
low_bound	Lower bound.
high_bound	Upper bound.

Returns: Clipped angle (implementation incomplete).

Todo:: Complete implementation.

◆ count_trailing_zeros()

uint8_t count_trailing_zeros ( uint32_t mask )

inline

Count trailing zeros (portable C++17)

Parameters

mask	32-bit mask

Returns: Index of least significant set bit, 32 if mask is 0

◆ decode_bits()

std::vector< uint8_t > decode_bits ( uint32_t mask )

inline

Decode a 32-bit mask into the indices of set bits.

Parameters

mask	32-bit mask

Returns: Vector of indices where bits are set

◆ draw_circle()

void draw_circle	(	std::array< float, 3 >	parameters,
		int	line_colour = `kBlack`,
		int	line_style = `kSolid`,
		int	line_width = `1`
	)

inline

Draw a circle on the current ROOT canvas pad.

Parameters

parameters	{x0, y0, R} [mm].
line_colour	ROOT line colour (default: `kBlack`).
line_style	ROOT line style (default: `kSolid`).
line_width	ROOT line width in pixels (default: 1).

◆ encode_bit()

uint32_t encode_bit ( uint8_t active_bit )

inline

Encode a single bit into a 32-bit mask.

Parameters

active_bit Index of the bit to set (0..31)

Returns: 32-bit mask with only that bit set

◆ encode_bits()

uint32_t encode_bits ( const std::vector< uint8_t > & active_bits )

inline

Encode multiple bits into a 32-bit mask.

Parameters

active_bits Vector of bit indices to set (0..31)

Returns: 32-bit mask with all specified bits set

◆ fit_circle()

circle_fit_results fit_circle	(	std::vector< std::array< float, 2 > >	points,
		std::array< float, 3 >	initial_values,
		bool	fix_XY = `true`,
		std::vector< int >	exclude_points = `{{}}`
	)

inline

Fit a circle to a set of 2-D points.

Minimises the sum of squared radial residuals using ROOT's Fitter.

Parameters

points	Input points {x, y} [mm].
initial_values	Initial guess {x0, y0, R}.
fix_XY	If `true`, fix the centre and fit only R (default: true).
exclude_points	Indices of points to exclude from the fit (default: empty).

Returns: Fit result with central values and uncertainties.

◆ fit_ring_integral()

ring_fit_results fit_ring_integral	(	TH2 *	target_histogram,
		std::array< double, 6 >	initial_values,
		bool	fix_XY = `true`
	)

inline

Fit a 2-D ring model to a histogram using chi-squared minimisation.

Integrates ring_fit_function_xy over each bin and minimises the sum of squared normalised residuals.

Parameters

target_histogram	Input TH2 (any bin size; bins with zero content are skipped).
initial_values	Initial guess {x0, y0, R, sigma_R, N_gamma, bkg}.
fix_XY	If `true`, fix (x0, y0) and fit only R and normalisation (default: true).

Returns: Fit result with central values and uncertainties.

◆ get_global_index()

uint32_t get_global_index	(	int	device,
		int	chip,
		int	channel,
		int	tdc
	)

inline

Pack device, chip, channel, and TDC sub-index into a global TDC index.

Parameters

device	Readout device ID (≥ 192).
chip	Chip number on the device.
channel	Even/odd channel index.
tdc	TDC sub-index (0–3).

Returns: Packed global TDC index.

◆ logistic()

double logistic	(	double	variable,
		double	amplitude,
		double	center_1,
		double	sigma_1,
		double	center_2,
		double	sigma_2
	)

inline

Difference-of-logistic function used to model azimuthal acceptance gaps.

Parameters

variable	Independent variable (e.g. azimuthal angle φ [rad]).
amplitude	Peak amplitude.
center_1	Centre of the rising logistic.
sigma_1	Width of the rising logistic.
center_2	Centre of the falling logistic.
sigma_2	Width of the falling logistic.

Returns: Function value at variable.

◆ open_or_build_rootfile()

TFile * open_or_build_rootfile	(	const std::string &	filename,
		std::function< void(std::string, std::string, int, bool, int, std::string, std::string, std::string)>	builder,
		const std::string &	data_repository,
		const std::string &	run_name,
		int	max_spill,
		bool	force_rebuild = `false`
	)

inline

Open a ROOT file for reading, rebuilding it if missing or corrupted.

Tries to open filename. If the file is absent, a zombie, or force_rebuild is true, calls builder with the supplied arguments to regenerate it, then re-opens it.

Parameters

filename	Path to the ROOT file to open.
builder	Callable that creates the file from raw data.
data_repository	Passed verbatim as the first argument to `builder`.
run_name	Passed verbatim as the second argument.
max_spill	Passed verbatim as the third argument.
force_rebuild	If `true`, always rebuild (default: false).

Returns: Open TFile* in READ mode, or nullptr on failure.

◆ plot_ring_integral()

std::vector< TGraph * > plot_ring_integral	(	ring_fit_results	fit_results,
		std::vector< float >	sigma_values,
		std::vector< std::array< double, 4 > >	logistic_input_values = `{}`,
		int	n_points = `500`
	)

inline

Generate ring-contour TGraphs at specified sigma levels from a fit result.

Parameters

fit_results	Result of fit_ring_integral.
sigma_values	List of sigma multipliers (e.g. {0, 1, -1} for centre ± 1σ).
logistic_input_values	Optional azimuthal-gap descriptors for the sigma model.
n_points	Number of points per contour (default: 500).

Returns: One TGraph per sigma value, caller takes ownership.

◆ ring_fit_function()

double ring_fit_function	(	std::array< double, 2 >	input_values,
		std::array< double, 6 >	parameters,
		std::vector< std::array< double, 4 > >	logistic_input_values = `{}`
	)

inline

Evaluate the ring signal + flat background model in (R, φ) coordinates.

Parameters

input_values	{R [mm], φ [rad]} of the point to evaluate.
parameters	{x0, y0, R0, sigma_R, N_gamma, bkg_level}.
logistic_input_values	Optional azimuthal-gap descriptors (see ring_fit_function_sigma_function).

Returns: Expected density at the given (R, φ).

◆ ring_fit_function_sigma_function()

double ring_fit_function_sigma_function	(	double	phi,
		double	baseline_sigma,
		std::vector< std::array< double, 4 > >	input_values = `{}`
	)

inline

Azimuthally-varying ring-width model.

Returns a baseline sigma plus contributions from one or more logistic features at configurable azimuthal positions. Used to model PDU boundaries.

Parameters

phi	Azimuthal angle [rad].
baseline_sigma	Constant ring-width baseline.
input_values	Logistic feature descriptors: each element is {amplitude, centre, width, logistic-sigma}.

Returns: Effective ring-width sigma at phi.

◆ ring_fit_function_xy() [1/2]

double ring_fit_function_xy	(	std::array< double, 2 >	input_values,
		const double *	parameters,
		int	how_many_logistics = `0`
	)

inline

Overload accepting a raw C-style parameter array (ROOT fitter compatible).

Parameters

input_values	{x [mm], y [mm]}.
parameters	Parameter array: [0–5] = {x0,y0,R,sigma,N,bkg}, followed by 4 values per logistic feature.
how_many_logistics	Number of logistic features appended after element 5.

Returns: Expected density at (x, y).

◆ ring_fit_function_xy() [2/2]

double ring_fit_function_xy	(	std::array< double, 2 >	input_values,
		std::array< double, 6 >	parameters,
		std::vector< std::array< double, 4 > >	logistic_input_values = `{}`
	)

inline

Evaluate the ring model in Cartesian (x, y) coordinates.

Parameters

input_values	{x [mm], y [mm]} of the point to evaluate.
parameters	{x0, y0, R0, sigma_R, N_gamma, bkg_level}.
logistic_input_values	Optional azimuthal-gap descriptors.

Returns: Expected density at (x, y).

Functions

Circle fitting

Ring model and fit utilities

Global random-number generator

Detailed Description

Function Documentation

◆ clip_phi()

◆ count_trailing_zeros()

◆ decode_bits()

◆ draw_circle()

◆ encode_bit()

◆ encode_bits()

◆ fit_circle()

◆ fit_ring_integral()

◆ get_global_index()

◆ logistic()

◆ open_or_build_rootfile()

◆ plot_ring_integral()

◆ ring_fit_function()

◆ ring_fit_function_sigma_function()

◆ ring_fit_function_xy() [1/2]

◆ ring_fit_function_xy() [2/2]