Collection of functions to transform photon mapping data. More...

#include <IPhotonMappingTransformations.h>

Inheritance diagram for phot::IPhotonMappingTransformations:

Public Types
using	OpDetID_t = int
	Type describing a optical detector ID. More...

using	LibraryIndex_t = OpDetID_t
	Type describing a library index. FIXME former LibraryOpDetID_t. More...

using	LibraryIndexToOpDetMap = std::vector< OpDetID_t >
	Type describing the mapping of optical detectors into library indices. More...

using	OpDetToLibraryIndexMap = std::vector< LibraryIndex_t >
	Type describing the mapping of library indices into optical detectors. More...

template<typename LibDataColl >
using	MappedOpDetData_t = phot::OpDetVisibilityData< util::collection_reference_t< LibDataColl >, util::collection_reference_t< OpDetToLibraryIndexMap const > >
	Type of optical detector data collection. More...

Public Member Functions
virtual	~IPhotonMappingTransformations ()=default

template<typename Coll >
auto	applyOpDetMapping (OpDetToLibraryIndexMap const &opDetToLibraryMap, Coll &&source, util::collection_value_t< Coll > defaultValue) const -> MappedOpDetData_t< Coll >

Geometry mapping interface
virtual geo::Point_t	detectorToLibrary (geo::Point_t const &location) const =0
	Returns the representation within the library of a detector location. More...

Optical detector mapping interface
Here the mapping is provided between optical detectors (`OpDetID_t`) and library indices (`LibraryIndex_t`). Terms and roles of the various concepts involved in the mapping may be confusing: see the glossary in `phot::IPhotonMappingTransformations` class description for their definition.
virtual LibraryIndex_t	opDetToLibraryIndex (geo::Point_t const &location, OpDetID_t opDetID) const =0
	Returns the library index for the specified optical detector. More...

virtual OpDetID_t	libraryIndexToOpDet (geo::Point_t const &location, LibraryIndex_t libIndex) const =0
	Returns the optical detector ID for the specified library index. More...

virtual OpDetToLibraryIndexMap const &	opDetsToLibraryIndices (geo::Point_t const &location) const =0
	Returns a map of library indices as function of optical detectors. More...

virtual std::size_t	opDetMappingSize () const =0
	Expected number of mappings of optical detector into library index. More...

virtual LibraryIndexToOpDetMap const &	libraryIndicesToOpDets (geo::Point_t const &location) const =0
	Returns a map of optical detectors identifiers, one for each library index. More...

virtual std::size_t	libraryMappingSize (geo::Point_t const &location) const =0
	Expected size of the mapping from library to optical detectors. More...

Utility methods
template<typename Coll >
MappedOpDetData_t< Coll >	applyOpDetMapping (OpDetToLibraryIndexMap const &opDetToLibraryMap, Coll &&source, util::collection_value_t< Coll > defaultValue={}) const
	Remaps a collection indexed by library index into one indexed by optical detector IDs. More...

template<typename Coll >
auto	applyOpDetMapping (geo::Point_t const &location, Coll &&source, util::collection_value_t< Coll > defaultValue={}) const
	Remaps a collection indexed by library index into one indexed by optical detector IDs according to the mapping at `location`. More...

Static Public Attributes
static constexpr OpDetID_t	InvalidOpDetID = std::numeric_limits<OpDetID_t>::max()
	Value used to identify an invalid optical detector. More...

static constexpr LibraryIndex_t	InvalidLibraryIndex = std::numeric_limits<LibraryIndex_t>::max()
	Value used for an invalid library index. More...

Detailed Description

Collection of functions to transform photon mapping data.

If the optical detectors of an experiment sport some symmetry, it may be convenient to exploit that symmetry to reduce the actual size of the internal mapping to a basic volume, and using the symmetry rules to convert between that basic volume and the world volume where the entire detector is represented. It is common that the symmetries require also a logic rearrangement of the actual optical detectors: a hook for that type of mapping is also provided, bidirectional.

This interface expresses the following transformations:

detectorToLibrary() transform a point in the detector space to a point in the library space
opDetToLibraryIndex() transforms a optical detector ID into the corresponding library index
libraryIndexToOpDet() transforms a library index into the corresponding global optical detector ID

Glossary

In this class and its documentation the following terms are in use:

library is a source of data; our libraries mapping the real space into some parametrization, and store the data as function of the parametrization values. In particular, they usually parametrize the covered space into tiny boxes ("voxels") and they address the data with a voxel index; and for each voxel index they store a collection of data values, addressed by another independent index that we call...
detector space or world is the physical space where the whole detector is represented; in LArSoft this space is described in the global (or world) coordinate system, and the geometry description (provided by geo::GeometryCore) works in this space
library space is a representation of the physical space covered by the library; it may effectively be a subset of the world space (e.g. a single drift volume) or it may be a completely local representation, that needs a mapping with the world space in order to be of any use
library identifier or library ID or library index is the index used to access a single value of the library (after having chosen the voxel to get data for); note that the "library identifier" does not actually identify a library, but rather some specific data within the a library. This mapping class uses this concept to identify and select library data values, and uses the type LibraryIndex_t to represent it in the code
optical detector is a LArSoft concept, representing a physical detector with a presence in the real world; in LArSoft, they may be represented by...
optical detector number or optical detector ID is a unique identifier in the form of either an integral number or as a location structure, geo::OpDetID; this concept is also used, e.g., as argument of geo::GeometryCore::OpDetGeoFromOpDet(). This mapping class uses the concept and the single unique number representation to identify the optical detector, and uses the local type OpDetID_t to represent it in the code;
optical detector readout channel or just channel is a LArSoft
concept, representing a data single source from optical detectors, and associated with optical detector readout. In most detectors, there is one channel per optical detector and vice versa. It may be described in LArSoft by...
optical detector channel number or channel number or (again) channel is a unique numeric identifier for a optical detector readout channel; this is used, e.g., as argument of geo::GeometryCore::OpDetGeoFromOpDet())

Note: While optical detector and optical detector channels are different concepts, nothing this class is currently dealing with relies on any difference between the two. Nevertheless, given the nature of the library of providing visibility information based on the geometry of the detectors, using the concept of physical optical detector is more appropriate than using the one of readout channel.

Technical notes

Mapping

Currently the mapping is expressed with a specific type. If more flexibility is needed, the mapping might use run time polymorphism. This case is not supported right now. If need arose, something might be designed on top of what is here now.

Definition at line 116 of file IPhotonMappingTransformations.h.

Member Typedef Documentation

using phot::IPhotonMappingTransformations::LibraryIndex_t = OpDetID_t

Type describing a library index. FIXME former LibraryOpDetID_t.

Definition at line 126 of file IPhotonMappingTransformations.h.

using phot::IPhotonMappingTransformations::LibraryIndexToOpDetMap = std::vector<OpDetID_t>

Type describing the mapping of optical detectors into library indices.

This type of mapping allows querying data values by optical detector ID, fetching them from library data source.

This type guarantees:

operator[](OpDetID_t) to fetch the library index associated to the specified optical detector
size() to report how many optical detectors are supported

Definition at line 141 of file IPhotonMappingTransformations.h.

template<typename LibDataColl >

using phot::IPhotonMappingTransformations::MappedOpDetData_t = phot::OpDetVisibilityData < util::collection_reference_t<LibDataColl>, util::collection_reference_t<OpDetToLibraryIndexMap const> >

Type of optical detector data collection.

Template Parameters

LibDataColl type of the original library data container

This type behaves like a random access collection with as index the optical detector ID and as value the data corresponding to that optical detector.

Definition at line 174 of file IPhotonMappingTransformations.h.

using phot::IPhotonMappingTransformations::OpDetID_t = int

Type describing a optical detector ID.

Definition at line 123 of file IPhotonMappingTransformations.h.

using phot::IPhotonMappingTransformations::OpDetToLibraryIndexMap = std::vector<LibraryIndex_t>

Type describing the mapping of library indices into optical detectors.

This type of mapping allows querying data values by library index, fetching them from an optical-detector-based data source.

This type guarantees:

operator[](LibraryIndex_t) to access the optical detector ID of the specified library index
size() to report how many library optical detectors are supported
either conversion to bool, response to empty() or to std::size() to determine if the contained data is valid (actually, just response to phot::isValidLibraryData())

Definition at line 159 of file IPhotonMappingTransformations.h.

Constructor & Destructor Documentation

virtual phot::IPhotonMappingTransformations::~IPhotonMappingTransformations ( )

virtualdefault

Member Function Documentation

template<typename Coll >

MappedOpDetData_t<Coll> phot::IPhotonMappingTransformations::applyOpDetMapping	(	OpDetToLibraryIndexMap const &	opDetToLibraryMap,
		Coll &&	source,
		util::collection_value_t< Coll >	defaultValue = `{}`
	)		const

Remaps a collection indexed by library index into one indexed by optical detector IDs.

Template Parameters

Coll	type of collection of data from the library, to be mapped

Parameters

opDetToLibraryMap	the mapping to be applied
source	collection of library data to be mapped
defaultValue	value returned for unmapped optical detector IDs

Returns: a random access collection providing data by optical detector ID

This method returns a collection proxy that dynamically applies the specified mapping. The original data is not copied.

The format of the map (opDetMap) is an object with a indexing operator where the index is the one in the destination collection (i.e. the optical detector ID) and the mapped value is the index in the source collection (the libary index). Each valid optical detector ID must be mapped. If the library index mapped to an optical detector is InvalidLibraryIndex, that optical detector is not mapped anywhere and its entry in the mapped collection is assigned the value defaultValue. Otherwise, the library index must be valid (which means, up to the result of libraryMappingSize() applied to the location where opDetMap is valid).

template<typename Coll >

auto phot::IPhotonMappingTransformations::applyOpDetMapping	(	geo::Point_t const &	location,
		Coll &&	source,
		util::collection_value_t< Coll >	defaultValue = `{}`
	)		const

inline

Remaps a collection indexed by library index into one indexed by optical detector IDs according to the mapping at location.

Template Parameters

Coll	type of collection of data from the library, to be mapped

Parameters

location	a world reference point to provide global context
source	collection of library data to be mapped
defaultValue	value returned for unmapped optical detector IDs

Returns: a random access collection providing data by optical detector ID

See Also: applyOpDetMapping()

This method applies a mapping (see applyOpDetMapping(OpDetToLibraryIndexMap const&, Coll&&, util::collection_value_t<Coll>)) that is obtained via libraryIndicesToOpDets().

Definition at line 403 of file IPhotonMappingTransformations.h.

                                                   {}
       ) const
       {
         return applyOpDetMapping(
           opDetsToLibraryIndices(location), std::forward<Coll>(source),
           defaultValue
           );
       }

template<typename Coll >

auto phot::IPhotonMappingTransformations::applyOpDetMapping	(	OpDetToLibraryIndexMap const &	opDetToLibraryMap,
		Coll &&	source,
		util::collection_value_t< Coll >	defaultValue
	)		const -> MappedOpDetData_t<Coll>

Definition at line 429 of file IPhotonMappingTransformations.h.

 {
 
   using std::size;
 
   // number of available destination slots (i.e. how many optical detectors)
   auto const n = size(opDetToLibraryMap);
 
   return MappedOpDetData_t<Coll>{
       util::make_collection_reference(std::forward<Coll>(source))
     , std::cref(opDetToLibraryMap) // mapping is referenced
     , n                            // size
     , defaultValue
     };
 
 } // phot::IPhotonMappingTransformations::applyOpDetMapping()

virtual geo::Point_t phot::IPhotonMappingTransformations::detectorToLibrary ( geo::Point_t const & location ) const

pure virtual

Returns the representation within the library of a detector location.

Parameters

location position in world coordinates [cm]

Returns: a vector expressing location in the library space

Exceptions

std::domain_error if the function can't handle location

The units and meaning of the returned location are library-dependent.

Example: assuming that fVoxelDef contains the description of the voxelization of the library, the ID of the voxel at location can be obtained from a mapping as:

auto const voxelID

= fVoxelDef.GetVoxelID(mapping->detectorToLibrary(location));

where mapping points to an object implementing the phot::IPhotonMappingTransformations interface. Note that the caller here has no business with the translated location, beside propagating it to the library: caller simply is not explained the meaning of that translated location.

Implemented in phot::ICARUSPhotonMappingTransformations, phot::PhotonMappingIdentityTransformations, and phot::PhotonMappingXMirrorTransformations.

virtual OpDetID_t phot::IPhotonMappingTransformations::libraryIndexToOpDet	(	geo::Point_t const &	location,
		LibraryIndex_t	libIndex
	)		const

pure virtual

Returns the optical detector ID for the specified library index.

Parameters

location	a point in detector space to provide global context
libIndex	library index to be mapped

Returns: optical detector corresponding to libIndex, or InvalidOpDetID

Exceptions

std::out_of_range	if input index can't be handled
std::domain_error	if location can't be handled

See Also: opDetToLibraryIndex(), libraryIndicesToOpDets()

The library index libIndex is converted into a optical detector ID. If the library does not include information for this optical detector, the value InvalidLibraryIndex is returned instead.

The specified location is used to inform the conversion, and it is usually pointing to the source of scintillation.

Implemented in phot::ICARUSPhotonMappingTransformations, and phot::PhotonMappingIdentityTransformations.

virtual LibraryIndexToOpDetMap const& phot::IPhotonMappingTransformations::libraryIndicesToOpDets ( geo::Point_t const & location ) const

pure virtual

Returns a map of optical detectors identifiers, one for each library index.

Parameters

location a world reference point to provide global context

Returns: optical detector identifiers for all library indices

Exceptions

std::domain_error if location can't be handled

See Also: opDetsToLibraryIndices(), libraryIndexToOpDet()

The returned value is a mapping object (see LibraryIndexToOpDetMap documentation for the interface). If a library index does not map to any optical detector in the library at location (which is unusual!), the optical detector ID corresponding to it is InvalidOpDetID.

The specified location is used to provide context in a similar fashion as detectorToLibrary() does. It can be used to choose the correct mapping among the available ones.

Implemented in phot::ICARUSPhotonMappingTransformations, and phot::PhotonMappingIdentityTransformations.

virtual std::size_t phot::IPhotonMappingTransformations::libraryMappingSize ( geo::Point_t const & location ) const

pure virtual

Expected size of the mapping from library to optical detectors.

Parameters

location a world reference point to provide global context

Exceptions

std::domain_error if location can't be handled

Returns: the expected size of the mapping from library indices to optical detectors

See Also: libraryIndicesToOpDets()

This is effectively the size of the mapping returned by libraryIndicesToOpDets(). It represents how many library indices are provided by the library for the specified location. For example, in an implementation exploiting the modularity of a detector with N channels and made of M modules, this value might be N / M.

Implemented in phot::ICARUSPhotonMappingTransformations, and phot::PhotonMappingIdentityTransformations.

virtual std::size_t phot::IPhotonMappingTransformations::opDetMappingSize ( ) const

pure virtual

Expected number of mappings of optical detector into library index.

Returns: the expected size of the mapping of optical detectors

See Also: opDetsToLibraryIndices()

This is effectively the number of available optical detectors, as well as the size of the mapping as returned by opDetsToLibraryIndices().

Implemented in phot::ICARUSPhotonMappingTransformations, and phot::PhotonMappingIdentityTransformations.

virtual OpDetToLibraryIndexMap const& phot::IPhotonMappingTransformations::opDetsToLibraryIndices ( geo::Point_t const & location ) const

pure virtual

Returns a map of library indices as function of optical detectors.

Parameters

location a world reference point to provide global context

Returns: library indices for all optical detectors

Exceptions

std::domain_error if location can't be handled

See Also: opDetToLibraryIndex(), opDetsToLibraryIndices()

The returned value is a mapping object (see OpDetToLibraryIndexMap documentation for the interface). If an optical detector has no representation in the library at location, the index value corresponding to it is InvalidLibraryIndex.

The specified location is used to inform the conversion, and it is usually pointing to the source of scintillation. It may be left unused.

Implemented in phot::ICARUSPhotonMappingTransformations, and phot::PhotonMappingIdentityTransformations.

virtual LibraryIndex_t phot::IPhotonMappingTransformations::opDetToLibraryIndex	(	geo::Point_t const &	location,
		OpDetID_t	opDetID
	)		const

pure virtual

Returns the library index for the specified optical detector.

Parameters

location	a point in detector space to provide global context
opDetID	optical detector identifier

Returns: index corresponding to opDetID, or InvalidLibraryIndex

Exceptions

std::out_of_range	if input optical detector can't be handled
std::domain_error	if location can't be handled

See Also: libraryIndexToOpDet(), opDetsToLibraryIndices()

The specified global identifier opDetID of an optical detector is converted into an index for the library.

If the library does not include information for this optical detector, the value InvalidLibraryIndex is returned instead.

The specified location is used to inform the conversion, and it is usually pointing to the source of scintillation.

Implemented in phot::ICARUSPhotonMappingTransformations, and phot::PhotonMappingIdentityTransformations.

Member Data Documentation

constexpr LibraryIndex_t phot::IPhotonMappingTransformations::InvalidLibraryIndex = std::numeric_limits<LibraryIndex_t>::max()

static

Value used for an invalid library index.

It may be used as value of the detector-to-library mapping.

Definition at line 193 of file IPhotonMappingTransformations.h.

constexpr OpDetID_t phot::IPhotonMappingTransformations::InvalidOpDetID = std::numeric_limits<OpDetID_t>::max()

static

Value used to identify an invalid optical detector.

It may be used as value of the library-to-detector mapping.

Definition at line 185 of file IPhotonMappingTransformations.h.

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

IPhotonMappingTransformations.h

Public Types

Public Member Functions

Static Public Attributes

Detailed Description

Glossary

Technical notes

Mapping

Member Typedef Documentation

Constructor & Destructor Documentation

Member Function Documentation

Member Data Documentation