High-level accessor class for one beam-spill worth of ALCOR data. More...

#include <alcor_spilldata.h>

Inheritance diagram for alcor_spilldata:

Public Member Functions
	alcor_spilldata ()
	Default constructor — initialises to an empty spill.

	alcor_spilldata (const alcor_spilldata_struct &v)
	Construct from an existing spill-data struct (copied).

alcor_spilldata_struct	get_spilldata () const
	Returns a full copy of the internal spill-data struct.

std::map< uint32_t, alcor_lightdata_struct >	get_frame () const
	Returns a copy of the frame → light-data map.

std::map< uint8_t, uint32_t >	get_participants_mask () const
	Returns a copy of the device → participants-mask map.

std::map< uint8_t, uint32_t >	get_dead_mask () const
	Returns a copy of the device → dead-mask map.

std::vector< alcor_lightdata_struct >	get_frame_list () const
	Returns a copy of the flat light-data vector (TTree representation).

std::vector< uint32_t >	get_frame_reference_list () const
	Returns a copy of the flat frame-reference vector (TTree representation).

alcor_spilldata_struct &	get_spilldata_link ()
	Returns a mutable reference to the internal spill-data struct.

std::map< uint32_t, alcor_lightdata_struct > &	get_frame_link ()
	Returns a mutable reference to the frame → light-data map.

std::map< uint8_t, uint32_t > &	get_participants_mask_link ()
	Returns a mutable reference to the participants-mask map.

std::map< uint8_t, uint32_t > &	get_dead_mask_link ()
	Returns a mutable reference to the dead-mask map.

std::vector< alcor_lightdata_struct > &	get_frame_list_link ()
	Returns a mutable reference to the flat light-data vector.

std::vector< uint32_t > &	get_frame_reference_list_link ()
	Returns a mutable reference to the flat frame-reference vector.

std::vector< trigger_event > &	get_frame_trigger_hits (uint32_t index_of_frame)
	Returns a mutable reference to the trigger-hit list for a given frame.

std::vector< alcor_finedata_struct > &	get_frame_timing_hits (uint32_t index_of_frame)
	Returns a mutable reference to the timing-hit list for a given frame.

std::vector< alcor_finedata_struct > &	get_frame_tracking_hits (uint32_t index_of_frame)
	Returns a mutable reference to the tracking-hit list for a given frame.

std::vector< alcor_finedata_struct > &	get_frame_cherenkov_hits (uint32_t index_of_frame)
	Returns a mutable reference to the Cherenkov-hit list for a given frame.

void	set_spilldata (alcor_spilldata_struct v)
	Replaces the internal spill-data struct (copied).

void	set_frame (std::map< uint32_t, alcor_lightdata_struct > v)
	Replaces the frame → light-data map (copied).

void	set_participants_mask (std::map< uint8_t, uint32_t > v)
	Replaces the participants-mask map (copied).

void	set_dead_mask (std::map< uint8_t, uint32_t > v)
	Replaces the dead-mask map (copied).

void	set_spilldata_link (alcor_spilldata_struct &v)
	Replaces the internal spill-data struct (move-assigned from reference).

void	set_frame_link (std::map< uint32_t, alcor_lightdata_struct > &v)
	Replaces the frame map (move-assigned from reference).

void	set_participants_mask_link (std::map< uint8_t, uint32_t > &v)
	Replaces the participants-mask map (move-assigned from reference).

void	set_dead_mask_link (std::map< uint8_t, uint32_t > &v)
	Replaces the dead-mask map (move-assigned from reference).

void	clear ()
	Resets the spill to an empty state, also clearing the deletion registry.

bool	has_trigger (uint32_t index_of_frame)
	Returns `true` if the given frame contains at least one trigger hit.

void	add_trigger_to_frame (uint32_t index_of_frame, trigger_event trg)
	Appends a trigger event to the hit list of the specified frame.

void	do_not_write_frame (uint32_t index_of_frame)
	Marks a frame to be excluded from the next TTree fill.

std::map< uint32_t, std::vector< uint8_t > >	get_not_dead_participants ()
	Returns, per device, the list of channels that are participating but not marked as dead.

bool	has_data ()
	Returns `true` if this object contains any spill data.

void	link_to_tree (TTree *input_tree)
	Binds the flat-vector members to branches of an existing input TTree.

void	write_to_tree (TTree *output_tree)
	Creates branches on an output TTree and binds them to the flat vectors.

void	prepare_tree_fill ()
	Converts the working maps into flat vectors ready for `TTree::Fill`.

void	get_entry ()
	Placeholder called after `TTree::GetEntry` — currently a no-op.

Public Member Functions inherited from alcor_lightdata
	alcor_lightdata (const alcor_lightdata_struct &data_struct)

alcor_lightdata_struct	get_lightdata () const
	Get a copy of the internal lightdata struct.

std::vector< alcor_finedata_struct >	get_timing_hits () const
	Get a copy of the timing hits.

std::vector< alcor_finedata_struct >	get_tracking_hits () const
	Get a copy of the tracking hits.

std::vector< alcor_finedata_struct >	get_cherenkov_hits () const
	Get a copy of the Cherenkov hits.

std::vector< trigger_event >	get_triggers () const
	Get a copy of trigger hits.

alcor_lightdata_struct &	get_lightdata_link ()
	Get a reference to the internal lightdata struct.

std::vector< alcor_finedata_struct > &	get_timing_hits_link ()
	Get a reference to the internal timing hits.

std::vector< alcor_finedata_struct > &	get_tracking_hits_link ()
	Get a reference to the internal tracking hits.

std::vector< alcor_finedata_struct > &	get_cherenkov_hits_link ()
	Get a reference to the internal Cherenkov hits.

std::vector< trigger_event > &	get_triggers_link ()
	Get a reference to the internal trigger hits.

void	set_lightdata (alcor_lightdata_struct v)
	Set the internal lightdata struct.

void	set_timing_hits (std::vector< alcor_finedata_struct > v)

void	set_tracking_hits (std::vector< alcor_finedata_struct > v)

void	set_cherenkov_hits (std::vector< alcor_finedata_struct > v)

void	set_trigger (std::vector< trigger_event > v)

void	set_lightdata_link (alcor_lightdata_struct &v)

void	set_timing_hits_link (std::vector< alcor_finedata_struct > &v)

void	set_tracking_hits_link (std::vector< alcor_finedata_struct > &v)

void	set_cherenkov_hits_link (std::vector< alcor_finedata_struct > &v)

void	set_trigger_link (std::vector< trigger_event > &v)

std::optional< float >	get_trigger_time (uint8_t trigger_index)
	Get the trigger time for a given trigger index.

Public Member Functions inherited from alcor_finedata
	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.

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.

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.

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.

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].

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.

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.

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.

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.

Additional Inherited Members
Static Public Member Functions inherited from alcor_finedata
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.

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

High-level accessor class for one beam-spill worth of ALCOR data.

Wraps an alcor_spilldata_struct and adds:

Typed getters/setters (both by value and by reference).
Frame-level helpers (trigger queries, selective frame suppression).
ROOT TTree I/O (link_to_tree / write_to_tree / prepare_tree_fill).

Inherits from alcor_lightdata to reuse common hit-decoding infrastructure.

Constructor & Destructor Documentation

◆ alcor_spilldata()

alcor_spilldata::alcor_spilldata ( const alcor_spilldata_struct & v )

inlineexplicit

Construct from an existing spill-data struct (copied).

Parameters

v	Source struct; copied into internal storage.

Member Function Documentation

◆ add_trigger_to_frame()

void alcor_spilldata::add_trigger_to_frame	(	uint32_t	index_of_frame,
		trigger_event	trg
	)

inline

Appends a trigger event to the hit list of the specified frame.

Parameters

index_of_frame	Target frame ID.
trg	Trigger event to append.

◆ do_not_write_frame()

void alcor_spilldata::do_not_write_frame ( uint32_t index_of_frame )

inline

Marks a frame to be excluded from the next TTree fill.

Frames flagged here are skipped in prepare_tree_fill() and their light-data is discarded. This is the mechanism for online event selection.

Parameters

index_of_frame Frame ID to suppress.

◆ get_entry()

void alcor_spilldata::get_entry ( )

inline

Placeholder called after TTree::GetEntry — currently a no-op.

Reserved for post-read bookkeeping (e.g. rebuilding working maps from flat vectors) if needed in future revisions.

◆ get_frame_cherenkov_hits()

std::vector< alcor_finedata_struct > & alcor_spilldata::get_frame_cherenkov_hits ( uint32_t index_of_frame )

inline

Returns a mutable reference to the Cherenkov-hit list for a given frame.

Parameters

index_of_frame Frame ID key in the frame map.

◆ get_frame_timing_hits()

std::vector< alcor_finedata_struct > & alcor_spilldata::get_frame_timing_hits ( uint32_t index_of_frame )

inline

Returns a mutable reference to the timing-hit list for a given frame.

Parameters

index_of_frame Frame ID key in the frame map.

◆ get_frame_tracking_hits()

std::vector< alcor_finedata_struct > & alcor_spilldata::get_frame_tracking_hits ( uint32_t index_of_frame )

inline

Returns a mutable reference to the tracking-hit list for a given frame.

Parameters

index_of_frame Frame ID key in the frame map.

◆ get_frame_trigger_hits()

std::vector< trigger_event > & alcor_spilldata::get_frame_trigger_hits ( uint32_t index_of_frame )

inline

Returns a mutable reference to the trigger-hit list for a given frame.

Parameters

index_of_frame Frame ID key in the frame map.

◆ get_not_dead_participants()

std::map< uint32_t, std::vector< uint8_t > > alcor_spilldata::get_not_dead_participants ( )

Returns, per device, the list of channels that are participating but not marked as dead.

Computes (participants_mask & ~dead_mask) for each device, then decodes the result into a vector of active channel indices.

Supports both the flat-list representation (filled after a TTree GetEntry) and the map-based representation (filled during online processing).

Returns: Map of device ID → vector of active (non-dead) channel indices.

◆ has_data()

bool alcor_spilldata::has_data ( )

inline

Returns true if this object contains any spill data.

Checks whether either the map or list representation of the participants mask is non-empty; an empty spill has neither.

◆ has_trigger()

bool alcor_spilldata::has_trigger ( uint32_t index_of_frame )

inline

Returns true if the given frame contains at least one trigger hit.

Parameters

index_of_frame Frame ID to query.

◆ link_to_tree()

void alcor_spilldata::link_to_tree ( TTree * input_tree )

Binds the flat-vector members to branches of an existing input TTree.

Call once before entering the event loop that calls TTree::GetEntry. Uses SetBranchAddress with the stable *_ptr pointers so that ROOT can refill the vectors in-place on each GetEntry call.

Parameters

input_tree Pointer to the TTree to read from; no-op if nullptr.

◆ prepare_tree_fill()

void alcor_spilldata::prepare_tree_fill ( )

Converts the working maps into flat vectors ready for TTree::Fill.

Steps performed:

Clears and resets the flat vectors and their branch-address pointers.
Transfers dead_mask and participants_mask into their list counterparts.
Iterates over frame_and_lightdata, skipping frames registered via do_not_write_frame(), and moves surviving frames into the flat vectors.
Clears the now-consumed working maps.

Note: After this call the working maps are empty; they must be repopulated before the next spill is processed.

◆ write_to_tree()

void alcor_spilldata::write_to_tree ( TTree * output_tree )

Creates branches on an output TTree and binds them to the flat vectors.

Call once before the event loop that calls TTree::Fill. The branches written are: dead_mask, participants_mask, frame, and lightdata.

Parameters

output_tree Pointer to the TTree to write to; no-op if nullptr.

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_spilldata.h
/home/runner/work/epic-drich-beam-test-analysis/epic-drich-beam-test-analysis/src/alcor_spilldata.cxx

Public Member Functions

Additional Inherited Members

Detailed Description

Constructor & Destructor Documentation

◆ alcor_spilldata()

Member Function Documentation

◆ add_trigger_to_frame()

◆ do_not_write_frame()

◆ get_entry()

◆ get_frame_cherenkov_hits()

◆ get_frame_timing_hits()

◆ get_frame_tracking_hits()

◆ get_frame_trigger_hits()

◆ get_not_dead_participants()

◆ has_data()

◆ has_trigger()

◆ link_to_tree()

◆ prepare_tree_fill()

◆ write_to_tree()