Multi-board timing alignment and hit sorting. More...

#include <Timing.hpp>

Static Public Member Functions
static Double_t	FindDensestTimeWindowStartS (std::vector< Double_t > times, Double_t window_width_s, Double_t fallback_start_s)
	Start of the busiest window of a given width.
static void	ComputeNSD2 (const std::vector< Double_t > &ref_x, const std::vector< Double_t > &ref_y, const std::vector< Double_t > &gr_x, const std::vector< Double_t > &gr_y, Double_t shift, Double_t thresh_dt_us, Int_t &npts, Double_t &nsd2)
	Normalised squared deviation between two timing structures at a shift.
static Bool_t	IsLongChannel (const TString &name)
	Whether a channel name denotes a long end.
static Bool_t	LongChanOrder (const LongChan &a, const LongChan &b)
	Ordering predicate giving a stable channel sequence.
static std::vector< LongChan >	BuildLongChannelList ()
	Every long-end channel in the active map, in stable order.
static void	PlotExtremeEvents2D (TH2F h_before, TH2F h_after, TH2F h_before_zoom, TH2F h_after_zoom, const TString &file_label, Double_t before_zoom_t0_s, Double_t after_zoom_t0_s)
	Save the before-and-after alignment diagnostic figures.
static void	PlotCostLandscape (const std::vector< Double_t > &shifts, const std::vector< Double_t > &inv_nsd2_values, Double_t best_shift, UShort_t ref_board, UShort_t board, const TString &file_label, const TString &tag)
	Save the shift-search cost landscape for one board pair.
static Double_t	FindShiftBeam (TGraph ref, TGraph gr, Double_t overlap_tmin_s, Double_t overlap_tmax_s, Double_t thresh_dt_us, UShort_t ref_board, UShort_t board, const TString &file_label)
	Best shift aligning one board's beam structure to the reference's.
static std::vector< TGraph * >	ExtractAllChannelsTimingStructureFromHits (const std::vector< RawHit > &hits, const std::vector< LongChan > &channels, Double_t min_energy, Double_t max_energy, Double_t tmin_s, Double_t tmax_s, Double_t thresh_dt_us)
	Build the beam timing structure for each channel.
static TimeShiftResult	CalcTimeShiftsBeamMethodFromHits (const std::vector< RawHit > &hits, const TString &file_label, UShort_t ref_board, const std::vector< UShort_t > &board_channels, Double_t min_energy, Double_t max_energy, Double_t overlap_margin_s, Double_t thresh_dt_us)
	Measure every board's offset against a reference board.
static void	ApplyShiftsInPlace (std::vector< RawHit > &hits, const std::vector< Long64_t > &board_shifts)
	Add the measured offsets to the hits, in place.
static void	SortHitsByTimestamp (std::vector< RawHit > &hits)
	Sort hits into ascending timestamp order, in place.

Detailed Description

Multi-board timing alignment and hit sorting.

All-static; the parallel file workers share these without synchronisation.

Definition at line 56 of file Timing.hpp.

Member Function Documentation

◆ ApplyShiftsInPlace()

void Timing::ApplyShiftsInPlace	(	std::vector< RawHit > &	hits,
		const std::vector< Long64_t > &	board_shifts )

static

Add the measured offsets to the hits, in place.

Parameters

[in,out]	hits	Hits to shift.
	board_shifts	Offsets from CalcTimeShiftsBeamMethodFromHits().

Note: Leaves the hits out of time order; sort afterwards with SortHitsByTimestamp() before building events.

Definition at line 712 of file Timing.cpp.

Referenced by RunFusedPipelineForFile().

◆ BuildLongChannelList()

std::vector< LongChan > Timing::BuildLongChannelList ( )

static

Every long-end channel in the active map, in stable order.

Definition at line 163 of file Timing.cpp.

Referenced by CalcTimeShiftsBeamMethodFromHits().

◆ CalcTimeShiftsBeamMethodFromHits()

TimeShiftResult Timing::CalcTimeShiftsBeamMethodFromHits	(	const std::vector< RawHit > &	hits,
		const TString &	file_label,
		UShort_t	ref_board,
		const std::vector< UShort_t > &	board_channels,
		Double_t	min_energy,
		Double_t	max_energy,
		Double_t	overlap_margin_s,
		Double_t	thresh_dt_us )

static

Measure every board's offset against a reference board.

Parameters

hits	Raw hits for the subfile.
file_label	Subfile label, for diagnostics.
ref_board	Board every other is aligned to.
board_channels	Reference channel per board.
min_energy	Lower energy gate for beam-like hits.
max_energy	Upper energy gate.
overlap_margin_s	Margin trimmed from the overlap window, in seconds.
thresh_dt_us	Pairing tolerance, in microseconds.

Returns: The per-board shifts, with the reference board at zero.

Definition at line 476 of file Timing.cpp.

Referenced by RunFusedPipelineForFile().

◆ ComputeNSD2()

void Timing::ComputeNSD2	(	const std::vector< Double_t > &	ref_x,
		const std::vector< Double_t > &	ref_y,
		const std::vector< Double_t > &	gr_x,
		const std::vector< Double_t > &	gr_y,
		Double_t	shift,
		Double_t	thresh_dt_us,
		Int_t &	npts,
		Double_t &	nsd2 )

static

Normalised squared deviation between two timing structures at a shift.

The cost function the shift search minimises: how badly a candidate shift superimposes one board's beam structure on the reference's.

Parameters

	ref_x	Reference times.
	ref_y	Reference values at those times.
	gr_x	Candidate board's times.
	gr_y	Candidate board's values.
	shift	Trial shift applied to the candidate, in seconds.
	thresh_dt_us	Pairing tolerance, in microseconds.
[out]	npts	Points that paired up under `thresh_dt_us`.
[out]	nsd2	The normalised squared deviation; smaller is better.

Note: A shift is only trusted when npts exceeds Constants::cfg.TIMING_SHIFT_MIN_NPTS; too few pairs make a small deviation meaningless.

Definition at line 87 of file Timing.cpp.

Referenced by FindShiftBeam(), and ScanShiftRange().

◆ ExtractAllChannelsTimingStructureFromHits()

std::vector< TGraph * > Timing::ExtractAllChannelsTimingStructureFromHits	(	const std::vector< RawHit > &	hits,
		const std::vector< LongChan > &	channels,
		Double_t	min_energy,
		Double_t	max_energy,
		Double_t	tmin_s,
		Double_t	tmax_s,
		Double_t	thresh_dt_us )

static

Build the beam timing structure for each channel.

Parameters

hits	Raw hits for the subfile.
channels	Channels to extract, from BuildLongChannelList().
min_energy	Lower energy gate, selecting beam-like hits.
max_energy	Upper energy gate.
tmin_s	Window start, in seconds.
tmax_s	Window end.
thresh_dt_us	Pairing tolerance, in microseconds.

Returns: One graph per channel, in channels order. The caller owns every graph.

Definition at line 413 of file Timing.cpp.

Referenced by CalcTimeShiftsBeamMethodFromHits().

◆ FindDensestTimeWindowStartS()

Double_t Timing::FindDensestTimeWindowStartS	(	std::vector< Double_t >	times,
		Double_t	window_width_s,
		Double_t	fallback_start_s )

static

Start of the busiest window of a given width.

Beam is not delivered uniformly across a subfile, and the alignment wants the stretch with the most hits rather than an arbitrary one.

Parameters

times	Hit times in seconds. Taken by value and sorted.
window_width_s	Window width, in seconds.
fallback_start_s	Returned when `times` is empty or the width is not positive.

Returns: The window start, in seconds.

Definition at line 740 of file Timing.cpp.

Referenced by CalcTimeShiftsBeamMethodFromHits().

◆ FindShiftBeam()

Double_t Timing::FindShiftBeam	(	TGraph *	ref,
		TGraph *	gr,
		Double_t	overlap_tmin_s,
		Double_t	overlap_tmax_s,
		Double_t	thresh_dt_us,
		UShort_t	ref_board,
		UShort_t	board,
		const TString &	file_label )

static

Best shift aligning one board's beam structure to the reference's.

Scans candidate shifts and keeps the one maximising the inverse normalised squared deviation, over the overlap window where both boards have data.

Parameters

ref	Reference board's timing structure.
gr	Board being aligned.
overlap_tmin_s	Overlap window start, in seconds.
overlap_tmax_s	Overlap window end.
thresh_dt_us	Pairing tolerance, in microseconds.
ref_board	Reference board id, for the diagnostic plot.
board	Board being aligned, likewise.
file_label	Subfile label.

Returns: The best shift, in seconds.

Definition at line 298 of file Timing.cpp.

Referenced by CalcTimeShiftsBeamMethodFromHits().

◆ IsLongChannel()

Bool_t Timing::IsLongChannel ( const TString & name )

static

Whether a channel name denotes a long end.

Parameters

name	Channel name from the active map.

Definition at line 137 of file Timing.cpp.

Referenced by BuildLongChannelList().

◆ LongChanOrder()

Bool_t Timing::LongChanOrder	(	const LongChan &	a,
		const LongChan &	b )

static

Ordering predicate giving a stable channel sequence.

Parameters

a	First channel.
b	Second channel.

Returns: kTRUE when a sorts before b.

Definition at line 157 of file Timing.cpp.

Referenced by BuildLongChannelList().

◆ PlotCostLandscape()

void Timing::PlotCostLandscape	(	const std::vector< Double_t > &	shifts,
		const std::vector< Double_t > &	inv_nsd2_values,
		Double_t	best_shift,
		UShort_t	ref_board,
		UShort_t	board,
		const TString &	file_label,
		const TString &	tag )

static

Save the shift-search cost landscape for one board pair.

Shows whether the chosen shift sits at a clear maximum or on a plateau, which is the difference between a measurement and a coincidence.

Parameters

shifts	Trial shifts searched, in seconds.
inv_nsd2_values	Inverse deviation at each, so higher is better.
best_shift	The shift selected.
ref_board	Reference board id.
board	Board being aligned.
file_label	Subfile label.
tag	Extra tag distinguishing passes.

Definition at line 253 of file Timing.cpp.

Referenced by FindShiftBeam().

◆ PlotExtremeEvents2D()

void Timing::PlotExtremeEvents2D	(	TH2F *	h_before,
		TH2F *	h_after,
		TH2F *	h_before_zoom,
		TH2F *	h_after_zoom,
		const TString &	file_label,
		Double_t	before_zoom_t0_s,
		Double_t	after_zoom_t0_s )

static

Save the before-and-after alignment diagnostic figures.

Full-range and zoomed views of the same data, so both the gross alignment and the residual structure are visible.

Parameters

h_before	Timing structure before alignment.
h_after	And after.
h_before_zoom	Zoomed view before alignment.
h_after_zoom	And after.
file_label	Subfile label, used in the plot names.
before_zoom_t0_s	Zoom window start before alignment, in seconds.
after_zoom_t0_s	And after.

Definition at line 180 of file Timing.cpp.

Referenced by CalcTimeShiftsBeamMethodFromHits().

◆ SortHitsByTimestamp()

void Timing::SortHitsByTimestamp ( std::vector< RawHit > & hits )

static

Sort hits into ascending timestamp order, in place.

Parameters

[in,out] hits Hits to sort.

Note: Dispatches to the CUDA kernel when GpuAccel reports it available and a sort slot is free; otherwise sorts on the host. The result is identical either way.

Definition at line 726 of file Timing.cpp.

Referenced by RunFusedPipelineForFile().

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

tooling/include/Timing.hpp
tooling/src/Timing.cpp

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ ApplyShiftsInPlace()

◆ BuildLongChannelList()

◆ CalcTimeShiftsBeamMethodFromHits()

◆ ComputeNSD2()

◆ ExtractAllChannelsTimingStructureFromHits()

◆ FindDensestTimeWindowStartS()

◆ FindShiftBeam()

◆ IsLongChannel()

◆ LongChanOrder()

◆ PlotCostLandscape()

◆ PlotExtremeEvents2D()

◆ SortHitsByTimestamp()