mapping Class Reference

Public Member Functions
Construction & calibration I/O
	mapping (std::string conf_file_name)
	Construct and immediately load a calibration file.
void	load_calib (std::string filename, bool verbose=false)
	Load (or reload) calibration data from a TOML file.
Single-hit position look-ups
All getters return std::nullopt when the requested identifier is out of range or not present in the calibration tables, making it safe to call without prior validity checks.
std::optional< int >	get_do_channel (int matrix, int eo_channel) const
	Translate an EO (even/odd) channel index to a DO (data-out) channel index for the given matrix quadrant.
std::optional< std::array< int, 2 > >	get_pdu_matrix (int device, int chip) const
	Retrieve the (PDU, matrix) pair for a given ALCOR (device, chip).
std::optional< std::array< float, 2 > >	get_position_from_pdu_column_row (int pdu, int column, int row) const
	Compute the physical (x, y) position from a PDU grid address.
std::optional< std::array< float, 2 > >	get_position_from_pdu_matrix_eoch (int pdu, int matrix, int eo_channel) const
	Compute the physical position from a (PDU, matrix, EO channel) triplet.
std::optional< std::array< float, 2 > >	get_position_from_device_chip_eoch (int device, int chip, int eo_channel) const
	Compute the physical position from an ALCOR (device, chip, EO channel) triplet.
std::optional< std::array< float, 2 > >	get_position_from_finedata (alcor_finedata entry) const
	Compute the physical position directly from a decoded ALCOR fine-data word.
std::optional< std::array< float, 2 > >	get_position_from_global_index (int global_index) const
	Compute the physical position from a global TDC channel index.
void	assign_position (alcor_finedata_struct &entry)
	Fill the hit_x / hit_y fields of a fine-data struct in-place.
Position cache construction
These methods pre-compute bidirectional look-up tables between global TDC channel indices and physical (x, y) positions. Building the caches once and reusing them is significantly faster than calling the full look-up chain inside tight event loops. The caches are invalidated automatically when load_calib() is called.
void	build_index_to_position_cache (float origin_cut=5.f)
	Build the index → position cache.
void	build_position_to_index_cache (std::string collision_policy="first")
	Build the position → index reverse cache.
std::optional< std::array< float, 2 > >	get_cached_position (int global_index) const
	Query the index→position cache built by build_index_to_position_cache().
std::optional< int >	get_cached_index (float x, float y) const
	Query the position→index cache built by build_position_to_index_cache().
const std::map< int, std::array< float, 2 > > &	get_index_to_position_map () const
	Read-only access to the full index→position cache map.
const std::map< std::array< float, 2 >, int > &	get_position_to_index_map () const
	Read-only access to the full position→index cache map.

Constructor & Destructor Documentation

mapping()

mapping::mapping ( std::string  conf_file_name )

explicit

Construct and immediately load a calibration file.

Parameters

conf_file_name

Path to a TOML calibration file containing pdu_xy_position, pdu_rotation, and device_chip_to_pdu_matrix tables.

Member Function Documentation

assign_position()

void mapping::assign_position

(

alcor_finedata_struct &

entry

)

Fill the hit_x / hit_y fields of a fine-data struct in-place.

Sets the fields to -99.f as a sentinel when the channel is not mapped.

Parameters

entry

Fine-data struct to annotate; modified in-place.

build_index_to_position_cache()

void mapping::build_index_to_position_cache

(

float

origin_cut = 5.f

)

Build the index → position cache.

Iterates over all valid global TDC indices (step 4, covering 2048 chips × 4 EO-channel groups) and resolves each to a physical position. Channels that are unmapped or whose position falls within a 5 mm radius of the origin (used as a sentinel for absent/dead pixels) are skipped.

After this call, the cache can be queried with get_cached_position().

Note

The 5 mm origin cut mirrors the filter applied in the standard event-loop snippet; adjust origin_cut if the geometry changes.

Parameters

origin_cut

Radius threshold in mm below which a hit is considered invalid (default: 5.0 mm, applied independently on x and y via fabs).

build_position_to_index_cache()

void mapping::build_position_to_index_cache

(

std::string

collision_policy = "first"

)

Build the position → index reverse cache.

Inverts the index→position cache. Must be called after build_index_to_position_cache() (or will build it implicitly if not yet done).

Because two distinct channels can in principle share the same nominal position (e.g. dead-pixel replacements), a collision_policy argument controls the behaviour:

• "first" – keep the first index seen (default, safe for typical use).
• "last" – overwrite with the last index seen.
• "warn" – keep first and emit a warning for every collision.

After this call, the cache can be queried with get_cached_index().

Parameters

collision_policy

One of "first", "last", "warn".

get_cached_index()

std::optional< int > mapping::get_cached_index	(	float	x,
		float	y
	)		const

Query the position→index cache built by build_position_to_index_cache().

Parameters

x	X coordinate in mm.
y	Y coordinate in mm.

Returns

Cached global TDC index, or std::nullopt if not in cache.

get_cached_position()

std::optional< std::array< float, 2 > > mapping::get_cached_position

(

int

global_index

)

const

Query the index→position cache built by build_index_to_position_cache().

Parameters

global_index

Global TDC channel index to look up.

Returns

Cached {x, y} position, or std::nullopt if not in cache.

get_do_channel()

std::optional< int > mapping::get_do_channel	(	int	matrix,
		int	eo_channel
	)		const

Translate an EO (even/odd) channel index to a DO (data-out) channel index for the given matrix quadrant.

The EO→DO permutation is hard-coded per matrix (1–4) and accounts for the physical wire routing inside each ALCOR ASIC quadrant.

Parameters

matrix	Matrix index [1–4].
eo_channel	EO channel index [0–63].

Returns

DO channel index, or std::nullopt if inputs are invalid.

get_index_to_position_map()

const std::map< int, std::array< float, 2 > > & mapping::get_index_to_position_map

(

)

const

Read-only access to the full index→position cache map.

Useful for iterating over all active channels, e.g. when filling occupancy histograms or building detector response matrices.

Returns

Const reference to the internal index_to_hit_xy map.

get_pdu_matrix()

std::optional< std::array< int, 2 > > mapping::get_pdu_matrix	(	int	device,
		int	chip
	)		const

Retrieve the (PDU, matrix) pair for a given ALCOR (device, chip).

Parameters

device	ALCOR device index.
chip	ALCOR chip index within the device.

Returns

Array {pdu, matrix}, or std::nullopt if not in calibration.

get_position_from_device_chip_eoch()

std::optional< std::array< float, 2 > > mapping::get_position_from_device_chip_eoch	(	int	device,
		int	chip,
		int	eo_channel
	)		const

Compute the physical position from an ALCOR (device, chip, EO channel) triplet.

Looks up (PDU, matrix) via the calibration table, then delegates to get_position_from_pdu_matrix_eoch().

Parameters

device	ALCOR device index.
chip	ALCOR chip index.
eo_channel	EO channel index [0–63].

Returns

Physical position {x, y} in mm, or std::nullopt if unmapped.

get_position_from_finedata()

std::optional< std::array< float, 2 > > mapping::get_position_from_finedata

(

alcor_finedata

entry

)

const

Compute the physical position directly from a decoded ALCOR fine-data word.

Parameters

entry

Decoded fine-data word providing device, chip, and EO channel.

Returns

Physical position {x, y} in mm, or std::nullopt if unmapped.

get_position_from_global_index()

std::optional< std::array< float, 2 > > mapping::get_position_from_global_index

(

int

global_index

)

const

Compute the physical position from a global TDC channel index.

The global index encodes (device, chip, EO channel) into a single integer via the utility functions get_device_from_global_tdc_index() etc.

Parameters

global_index

Packed global TDC channel index.

Returns

Physical position {x, y} in mm, or std::nullopt if unmapped.

get_position_from_pdu_column_row()

std::optional< std::array< float, 2 > > mapping::get_position_from_pdu_column_row	(	int	pdu,
		int	column,
		int	row
	)		const

Compute the physical (x, y) position from a PDU grid address.

The intra-PDU coordinate is computed from the pixel pitch (3.2 mm), guard-ring offsets, and an extra 0.3 mm gap between the two halves of the 16×16 grid (columns/rows 7→8). The PDU origin is then added from pdu_xy_position.

Parameters

pdu	PDU index [1–8].
column	Column in the 16×16 PDU grid [0–15].
row	Row in the 16×16 PDU grid [0–15].

Returns

Physical position {x, y} in mm, or std::nullopt on bad input.

get_position_from_pdu_matrix_eoch()

std::optional< std::array< float, 2 > > mapping::get_position_from_pdu_matrix_eoch	(	int	pdu,
		int	matrix,
		int	eo_channel
	)		const

Compute the physical position from a (PDU, matrix, EO channel) triplet.

Internally calls get_do_channel() to resolve the column/row within the PDU grid, then applies the optional 180° rotation before delegating to get_position_from_pdu_column_row().

Parameters

pdu	PDU index [1–8].
matrix	Matrix index [1–4].
eo_channel	EO channel index [0–63].

Returns

Physical position {x, y} in mm, or std::nullopt on failure.

get_position_to_index_map()

const std::map< std::array< float, 2 >, int > & mapping::get_position_to_index_map

(

)

const

Read-only access to the full position→index cache map.

Returns

Const reference to the internal hit_xy_to_index map. The key is encoded as a pair of floats {x, y}.

load_calib()

void mapping::load_calib	(	std::string	filename,
		bool	verbose = false
	)

Load (or reload) calibration data from a TOML file.

Populates the three mutable calibration maps:

• pdu_xy_position – physical centre of each PDU in mm.
• pdu_rotation – whether the PDU is rotated 180°.
• device_chip_to_pdu_matrix – ALCOR (device, chip) → (PDU, matrix).

Any previously cached index↔position data is invalidated on reload.

Parameters

filename	Path to the TOML calibration file.
verbose	If true, emit verbose diagnostic messages (unused atm).

---

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