LArSoft  v09_90_00
Liquid Argon Software toolkit - https://larsoft.org/
phot::IPhotonMappingTransformations Class Referenceabstract

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

#include "IPhotonMappingTransformations.h"

Inheritance diagram for phot::IPhotonMappingTransformations:
phot::PhotonMappingIdentityTransformations phot::PhotonMappingXMirrorTransformations

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
 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:

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 115 of file IPhotonMappingTransformations.h.

Member Typedef Documentation

Type describing a library index. FIXME former LibraryOpDetID_t.

Definition at line 124 of file IPhotonMappingTransformations.h.

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 139 of file IPhotonMappingTransformations.h.

Type of optical detector data collection.

Template Parameters
LibDataColltype 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 170 of file IPhotonMappingTransformations.h.

Type describing a optical detector ID.

Definition at line 121 of file IPhotonMappingTransformations.h.

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 157 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
Colltype of collection of data from the library, to be mapped
Parameters
opDetToLibraryMapthe mapping to be applied
sourcecollection of library data to be mapped
defaultValuevalue 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).

Referenced by applyOpDetMapping().

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
Colltype of collection of data from the library, to be mapped
Parameters
locationa world reference point to provide global context
sourcecollection of library data to be mapped
defaultValuevalue 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 391 of file IPhotonMappingTransformations.h.

References applyOpDetMapping(), and opDetsToLibraryIndices().

393  {}) const
394  {
395  return applyOpDetMapping(
396  opDetsToLibraryIndices(location), std::forward<Coll>(source), defaultValue);
397  }
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...
virtual OpDetToLibraryIndexMap const & opDetsToLibraryIndices(geo::Point_t const &location) const =0
Returns a map of library indices as function of optical detectors.
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 410 of file IPhotonMappingTransformations.h.

References util::make_collection_reference(), n, and util::size().

415 {
416 
417  using std::size;
418 
419  // number of available destination slots (i.e. how many optical detectors)
420  auto const n = size(opDetToLibraryMap);
421 
422  return MappedOpDetData_t<Coll>{util::make_collection_reference(std::forward<Coll>(source)),
423  std::cref(opDetToLibraryMap) // mapping is referenced
424  ,
425  n // size
426  ,
427  defaultValue};
428 
429 } // phot::IPhotonMappingTransformations::applyOpDetMapping()
auto make_collection_reference(Coll &&coll)
Returns an object referencing to the data contained in coll.
decltype(auto) constexpr size(T &&obj)
ADL-aware version of std::size.
Definition: StdUtils.h:101
Char_t n[5]
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
locationposition in world coordinates [cm]
Returns
a vector expressing location in the library space
Exceptions
std::domain_errorif 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::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
locationa point in detector space to provide global context
libIndexlibrary index to be mapped
Returns
optical detector corresponding to libIndex, or InvalidOpDetID
Exceptions
std::out_of_rangeif input index can't be handled
std::domain_errorif 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::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
locationa world reference point to provide global context
Returns
optical detector identifiers for all library indices
Exceptions
std::domain_errorif 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::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
locationa world reference point to provide global context
Exceptions
std::domain_errorif 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::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::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
locationa world reference point to provide global context
Returns
library indices for all optical detectors
Exceptions
std::domain_errorif 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::PhotonMappingIdentityTransformations.

Referenced by applyOpDetMapping().

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
locationa point in detector space to provide global context
opDetIDoptical detector identifier
Returns
index corresponding to opDetID, or InvalidLibraryIndex
Exceptions
std::out_of_rangeif input optical detector can't be handled
std::domain_errorif 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::PhotonMappingIdentityTransformations.

Member Data Documentation

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

Value used for an invalid library index.

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

Definition at line 186 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 179 of file IPhotonMappingTransformations.h.


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