Represents a single calibrated ALCOR TDC hit with fine-time correction. More...

#include <alcor_finedata.h>

Inheritance diagram for alcor_finedata:

Public Member Functions
	alcor_finedata ()
	Default constructor. Initialises all fields to zero.

	alcor_finedata (const alcor_finedata_struct &s)
	Construct from a decoded alcor_finedata_struct.

	alcor_finedata (const alcor_data_struct &d)
	Construct directly from a raw alcor_data_struct.

	alcor_finedata (const alcor_finedata &o)
	Copy constructor.

Raw Field Getters
alcor_finedata_struct	get_data_struct () const
	Returns a copy of the underlying alcor_finedata_struct.

uint32_t	get_global_index () const
	Returns the calibration index identifying the TDC channel.

uint32_t	get_rollover () const
	Returns the rollover counter.

uint16_t	get_coarse () const
	Returns the coarse timestamp (clock-cycle count).

uint8_t	get_fine () const
	Returns the fine timestamp (TDC bin within a clock cycle).

float	get_hit_x () const
	Returns the x-axis position from mapping.

float	get_hit_y () const
	Returns the y-axis position from mapping.

uint32_t	get_mask () const
	Returns the hit bitmask.

Derived Timing Getters
float	get_phase () const
	Returns the calibrated fine-time phase in clock cycles. Computed from the 3-parameter calibration stored in `calibration_parameters`.

float	get_time () const
	Returns the calibrated hit time in clock cycles. Combines rollover, coarse, and the fine-time phase correction. All unsigned fields are promoted to float before arithmetic to avoid unsigned underflow when subtracting the (potentially non-zero) phase.

float	get_time_ns () const
	Returns the calibrated hit time in nanoseconds.

Derived Address Getters
int	get_tdc () const
	Returns the TDC index decoded from the calibration index.

int	get_device () const
	Returns the readout device ID decoded from the calibration index.

int	get_fifo () const
	Returns the FIFO number decoded from the calibration index.

int	get_chip () const
	Returns the chip ID decoded from the calibration index.

int	get_eo_channel () const
	Returns the even/odd channel index decoded from the calibration index.

int	get_column () const
	Returns the column address decoded from the calibration index.

int	get_pixel () const
	Returns the pixel address decoded from the calibration index.

int	get_device_index () const
	Returns the per-device TDC index.

int	get_global_channel_index () const
	Returns the global channel index stripped of TDC info.

Spatial Getters
float	get_hit_x_rnd () const
	Returns the pixel-randomised x-coordinate, uniform within ±1.5 mm of the hit position.

float	get_hit_y_rnd () const
	Returns the pixel-randomised y-coordinate, uniform within ±1.5 mm of the hit position.

float	get_hit_r_rnd () const
	Returns the radial distance from the origin using a freshly randomised position.

float	get_hit_phi_rnd () const
	Returns the azimuthal angle from the origin using a freshly randomised position [rad].

float	get_hit_r_rnd (std::array< float, 2 > v) const
	Returns the radial distance from a custom centre using a freshly randomised position.

float	get_hit_phi_rnd (std::array< float, 2 > v) const
	Returns the azimuthal angle from a custom centre using a freshly randomised position [rad].

Hit Mask Flags
void	add_mask_bit (hit_mask bit)
	Sets a single bit in the hit mask.

void	clear_mask_bit (hit_mask bit)
	Clears a single bit in the hit mask.

bool	has_mask_bit (hit_mask bit) const
	Checks whether a single bit is set in the hit mask.

bool	is_ring_tag_first () const
	Checks whether the hit is tagged as part of a ring (first pass).

bool	is_ring_tag_second () const
	Checks whether the hit is tagged as part of a ring (second pass).

bool	is_cross_talk () const
	Checks whether the hit is flagged as cross-talk.

bool	is_afterpulse () const
	Checks whether the hit is flagged as an afterpulse.

bool	is_part_lane () const
	Checks whether the hit originates from a partially active lane.

bool	is_dead_lane () const
	Checks whether the hit originates from a dead lane.

Raw Field Setters
void	set_data_struct (const alcor_finedata_struct &d)
	Replaces the underlying data struct.

void	set_global_index (uint32_t calib)
	Sets the calibration index.

void	set_rollover (uint32_t r)
	Sets the rollover counter.

void	set_coarse (uint16_t c)
	Sets the coarse timestamp.

void	set_fine (uint8_t f)
	Sets the fine timestamp.

void	set_mask (uint32_t mask)
	Sets the hit bitmask.

void	set_streaming_ring_trigger_mask ()
	Flags the hit as a streaming ring trigger participant.

Comparison Operators
Compare hits by their calibrated timestamp.
bool	operator< (const alcor_finedata &v) const
	Less-than comparison against an alcor_finedata hit.

bool	operator<= (const alcor_finedata &v) const
	Less-than-or-equal comparison against an alcor_finedata hit.

bool	operator> (const alcor_finedata &v) const
	Greater-than comparison against an alcor_finedata hit.

bool	operator>= (const alcor_finedata &v) const
	Greater-than-or-equal comparison against an alcor_finedata hit.

Calibration
void	generate_calibration (TH2F *calibration_histogram, bool overwrite_calibration)
	Derives calibration parameters from a 2D fine-time histogram.

void	update_calibration (TH2F *h)
	Updates calibration without overwriting existing entries. Alias for generate_calibration with `overwrite_calibration` = `false`.

void	write_calib_to_file (const std::string &filename)
	Writes the current calibration parameters to a plain-text file.

void	read_calib_from_file (const std::string &filename, bool clear_first=true, bool overwrites=true)
	Loads calibration parameters from a plain-text file.

Static Public Member Functions
Calibration Parameter Setters
static void	set_param0 (int global_tdc_index, float value)
	Sets calibration parameter 0 for a given TDC channel.

static void	set_param1 (int global_tdc_index, float value)
	Sets calibration parameter 1 for a given TDC channel.

static void	set_param2 (int global_tdc_index, float value)
	Sets calibration parameter 2 for a given TDC channel.

Ring-finding algorithms
static std::vector< mist::ring_finding::ring_result >	alcor_find_rings_hough (mist::ring_finding::hough_transform &ht, std::vector< alcor_finedata > &alcor_hits, float threshold_fraction, int min_hits, int min_active, int max_rings=2, float collection_radius=6.f)
	Convert a vector of alcor_finedata hits into hough_hit, run the Hough-transform ring finder, write mask bits back onto the original hits, and return the ring results.

Detailed Description

Represents a single calibrated ALCOR TDC hit with fine-time correction.

Wraps an alcor_finedata_struct and provides:

Accessors for raw timing fields and derived channel-address fields.
A static calibration table (shared across all instances) mapping global TDC indices to a 3-parameter calibration array.
Methods to generate, persist, and load the calibration from ROOT histograms or plain files.

The fine-time phase is computed from the calibration parameters stored in the static calibration_parameters map.

Constructor & Destructor Documentation

◆ alcor_finedata() [1/3]

alcor_finedata::alcor_finedata ( const alcor_finedata_struct & s )

Construct from a decoded alcor_finedata_struct.

Parameters

s	Pre-filled struct with rollover, coarse, fine, and mask.

◆ alcor_finedata() [2/3]

alcor_finedata::alcor_finedata ( const alcor_data_struct & d )

Construct directly from a raw alcor_data_struct.

Parameters

d	Raw data word; decoded internally via alcor_finedata_struct.

◆ alcor_finedata() [3/3]

alcor_finedata::alcor_finedata ( const alcor_finedata & o )

Copy constructor.

Parameters

o	Source object to copy from.

Member Function Documentation

◆ add_mask_bit()

void alcor_finedata::add_mask_bit ( hit_mask bit )

inline

Sets a single bit in the hit mask.

Parameters

bit	Bit position to set (from hit_mask enum).

◆ alcor_find_rings_hough()

std::vector< mist::ring_finding::ring_result > alcor_finedata::alcor_find_rings_hough	(	mist::ring_finding::hough_transform &	ht,
		std::vector< alcor_finedata > &	alcor_hits,
		float	threshold_fraction,
		int	min_hits,
		int	min_active,
		int	max_rings = `2`,
		float	collection_radius = `6.f`
	)

static

Convert a vector of alcor_finedata hits into hough_hit, run the Hough-transform ring finder, write mask bits back onto the original hits, and return the ring results.

All ALCOR-specific knowledge is concentrated here:

Afterpulse filtering (is_afterpulse()).
Device-index guard (device ≥ 200 excluded).
LUT key derivation (get_global_index() / 4).
Mask-bit assignment (_HITMASK_hough_ring_tag_first/second).

Parameters

ht	Pre-built hough_transform instance. hough_transform::build_lut must have been called with geometry consistent with `alcor_hits`.
alcor_hits	Calibrated ALCOR hits for the current event. Mask bits are written back in-place for tagged hits.
threshold_fraction	Minimum fraction of active hits required in the peak accumulator cell (range 0–1).
min_hits	Minimum absolute vote count for a ring to be accepted.
max_rings	Maximum number of rings to extract (default 2).
collection_radius	Distance from the ring arc within which a hit is assigned to the ring [mm] (default 6).

Returns: Vector of hough_ring_result (indices refer to the alcor_hits vector), in descending peak-vote order.

◆ clear_mask_bit()

void alcor_finedata::clear_mask_bit ( hit_mask bit )

inline

Clears a single bit in the hit mask.

Parameters

bit	Bit position to clear (from hit_mask enum).

◆ generate_calibration()

void alcor_finedata::generate_calibration	(	TH2F *	calibration_histogram,
		bool	overwrite_calibration
	)

Derives calibration parameters from a 2D fine-time histogram.

Fits each Y-slice of calibration_histogram to extract the 3 calibration parameters and populates the static calibration_parameters map.

Parameters

calibration_histogram	2D histogram with TDC index on X and fine counts on Y, typically accumulated during a dedicated calibration run.
overwrite_calibration	If `true`, existing entries are replaced.

◆ get_hit_phi_rnd()

float alcor_finedata::get_hit_phi_rnd ( std::array< float, 2 > v ) const

Returns the azimuthal angle from a custom centre using a freshly randomised position [rad].

Parameters

v	Centre coordinates {x, y}.

◆ get_hit_r_rnd()

float alcor_finedata::get_hit_r_rnd ( std::array< float, 2 > v ) const

Returns the radial distance from a custom centre using a freshly randomised position.

Parameters

v	Centre coordinates {x, y}.

◆ has_mask_bit()

bool alcor_finedata::has_mask_bit ( hit_mask bit ) const

inline

Checks whether a single bit is set in the hit mask.

Parameters

bit	Bit position to check (from hit_mask enum).

Returns: true if the bit is set.

◆ read_calib_from_file()

void alcor_finedata::read_calib_from_file	(	const std::string &	filename,
		bool	clear_first = `true`,
		bool	overwrites = `true`
	)

Loads calibration parameters from a plain-text file.

Parameters

filename	Path to the calibration file to read.
clear_first	If `true`, clears existing parameters before loading (default: `true`).
overwrites	If `true`, existing entries are overwritten by file values (default: `true`).

◆ set_coarse()

void alcor_finedata::set_coarse ( uint16_t c )

inline

Sets the coarse timestamp.

Parameters

c	New coarse value.

◆ set_data_struct()

void alcor_finedata::set_data_struct ( const alcor_finedata_struct & d )

inline

Replaces the underlying data struct.

Parameters

d	New alcor_finedata_struct to assign.

◆ set_fine()

void alcor_finedata::set_fine ( uint8_t f )

inline

Sets the fine timestamp.

Parameters

f	New fine value.

◆ set_global_index()

void alcor_finedata::set_global_index ( uint32_t calib )

inline

Sets the calibration index.

Parameters

calib New calibration index value.

◆ set_mask()

void alcor_finedata::set_mask ( uint32_t mask )

inline

Sets the hit bitmask.

Parameters

mask	New mask value.

◆ set_param0()

static void alcor_finedata::set_param0	(	int	global_tdc_index,
		float	value
	)

inlinestatic

Sets calibration parameter 0 for a given TDC channel.

Parameters

global_tdc_index	Global TDC index to update.
value	New value for parameter 0.

◆ set_param1()

static void alcor_finedata::set_param1	(	int	global_tdc_index,
		float	value
	)

inlinestatic

Sets calibration parameter 1 for a given TDC channel.

Parameters

global_tdc_index	Global TDC index to update.
value	New value for parameter 1.

◆ set_param2()

static void alcor_finedata::set_param2	(	int	global_tdc_index,
		float	value
	)

inlinestatic

Sets calibration parameter 2 for a given TDC channel.

Parameters

global_tdc_index	Global TDC index to update.
value	New value for parameter 2.

◆ set_rollover()

void alcor_finedata::set_rollover ( uint32_t r )

inline

Sets the rollover counter.

Parameters

r	New rollover value.

◆ update_calibration()

void alcor_finedata::update_calibration ( TH2F * h )

inline

Updates calibration without overwriting existing entries. Alias for generate_calibration with overwrite_calibration = false.

Parameters

h	2D fine-time histogram (same format as generate_calibration).

◆ write_calib_to_file()

void alcor_finedata::write_calib_to_file ( const std::string & filename )

Writes the current calibration parameters to a plain-text file.

Parameters

filename Path to the output calibration file.

The documentation for this class was generated from the following files:

/home/runner/work/epic-drich-beam-test-analysis/epic-drich-beam-test-analysis/include/alcor_finedata.h
/home/runner/work/epic-drich-beam-test-analysis/epic-drich-beam-test-analysis/src/alcor_finedata.cxx

Public Member Functions

Static Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ alcor_finedata() [1/3]

◆ alcor_finedata() [2/3]

◆ alcor_finedata() [3/3]

Member Function Documentation

◆ add_mask_bit()

◆ alcor_find_rings_hough()

◆ clear_mask_bit()

◆ generate_calibration()

◆ get_hit_phi_rnd()

◆ get_hit_r_rnd()

◆ has_mask_bit()

◆ read_calib_from_file()

◆ set_coarse()

◆ set_data_struct()

◆ set_fine()

◆ set_global_index()

◆ set_mask()

◆ set_param0()

◆ set_param1()

◆ set_param2()

◆ set_rollover()

◆ update_calibration()

◆ write_calib_to_file()