CMS 3D CMS Logo
Public Types | Public Member Functions | Private Member Functions | Private Attributes

MuonDetLayerMeasurements Class Reference

#include <MuonDetLayerMeasurements.h>

List of all members.

Public Types

typedef
MuonTransientTrackingRecHit::MuonRecHitContainer 		MuonRecHitContainer

Public Member Functions

MeasurementContainer fastMeasurements (const DetLayer *layer, const TrajectoryStateOnSurface &theStateOnDet, const TrajectoryStateOnSurface &startingState, const Propagator &prop, const MeasurementEstimator &est, const edm::Event &iEvent)
 faster version in case the TrajectoryState on the surface of the GeomDet is already available
MeasurementContainer fastMeasurements (const DetLayer *layer, const TrajectoryStateOnSurface &theStateOnDet, const TrajectoryStateOnSurface &startingState, const Propagator &prop, const MeasurementEstimator &est)
 faster version in case the TrajectoryState on the surface of the GeomDet is already available
std::vector
< TrajectoryMeasurementGroup > 		groupedMeasurements (const DetLayer *layer, const TrajectoryStateOnSurface &startingState, const Propagator &prop, const MeasurementEstimator &est, const edm::Event &iEvent)
std::vector
< TrajectoryMeasurementGroup > 		groupedMeasurements (const DetLayer *layer, const TrajectoryStateOnSurface &startingState, const Propagator &prop, const MeasurementEstimator &est)
MeasurementContainer measurements (const DetLayer *layer, const GeomDet *det, const TrajectoryStateOnSurface &stateOnDet, const MeasurementEstimator &est, const edm::Event &iEvent)
MeasurementContainer measurements (const DetLayer *layer, const TrajectoryStateOnSurface &startingState, const Propagator &prop, const MeasurementEstimator &est, const edm::Event &iEvent)
 returns TMeasurements in a DetLayer compatible with the TSOS.
MeasurementContainer measurements (const DetLayer *layer, const TrajectoryStateOnSurface &startingState, const Propagator &prop, const MeasurementEstimator &est)
 returns TMeasurements in a DetLayer compatible with the TSOS.
 MuonDetLayerMeasurements (edm::InputTag dtlabel, edm::InputTag csclabel, edm::InputTag rpclabel, bool enableDT=true, bool enableCSC=true, bool enableRPC=true)
MuonRecHitContainer recHits (const DetLayer *layer, const edm::Event &iEvent)
 returns the rechits which are on the layer
MuonRecHitContainer recHits (const DetLayer *layer)
 returns the rechits which are on the layer
void setEvent (const edm::Event &)
 set event
virtual ~MuonDetLayerMeasurements ()

Private Member Functions

void checkCSCRecHits ()
void checkDTRecHits ()
void checkEvent () const
 check that the event is set, and throw otherwise
void checkRPCRecHits ()
MuonRecHitContainer recHits (const GeomDet *, const edm::Event &iEvent)
 obtain TrackingRecHits from a DetLayer

Private Attributes

bool enableCSCMeasurement
bool enableDTMeasurement
bool enableRPCMeasurement
std::string theCSCCheckName
edm::EventID theCSCEventID
edm::InputTag theCSCRecHitLabel
edm::Handle< CSCSegmentCollection > theCSCRecHits
std::string theDTCheckName
edm::EventID theDTEventID
edm::InputTag theDTRecHitLabel
edm::Handle
< DTRecSegment4DCollection > 		theDTRecHits
const edm::Event * theEvent
std::string theRPCCheckName
edm::EventID theRPCEventID
edm::InputTag theRPCRecHitLabel
edm::Handle< RPCRecHitCollection > theRPCRecHits

Detailed Description

The class to access recHits and TrajectoryMeasurements from DetLayer.

Date:
2012/05/29 08:23:55
Revision:
1.21
Author:
C. Liu, R. Bellan, N. Amapane

The class to access recHits and TrajectoryMeasurements from DetLayer.

Date:
2010/05/12 23:01:23
Revision:
1.31
Author:
C. Liu, R. Bellan, N. Amapane

Definition at line 38 of file MuonDetLayerMeasurements.h.

Member Typedef Documentation

typedef MuonTransientTrackingRecHit::MuonRecHitContainer MuonDetLayerMeasurements::MuonRecHitContainer

Definition at line 40 of file MuonDetLayerMeasurements.h.

Constructor & Destructor Documentation

MuonDetLayerMeasurements::MuonDetLayerMeasurements ( edm::InputTag  dtlabel,
edm::InputTag  csclabel,
edm::InputTag  rpclabel,
bool  enableDT = true,
bool  enableCSC = true,
bool  enableRPC = true 
)

Definition at line 26 of file MuonDetLayerMeasurements.cc.

References theCSCCheckName, theDTCheckName, and theRPCCheckName.

                                                                                                 : 
  theDTRecHitLabel(dtlabel),
  theCSCRecHitLabel(csclabel),
  theRPCRecHitLabel(rpclabel),
  enableDTMeasurement(enableDT),
  enableCSCMeasurement(enableCSC),
  enableRPCMeasurement(enableRPC),
  theDTRecHits(),
  theCSCRecHits(),
  theRPCRecHits(),
  theDTEventID(),
  theCSCEventID(),
  theRPCEventID(),
  theEvent(0){
  static int procInstance(0);
  std::ostringstream sDT;
  sDT<<"MuonDetLayerMeasurements::checkDTRecHits::" << procInstance;
  theDTCheckName = sDT.str();
  std::ostringstream sRPC;
  sRPC<<"MuonDetLayerMeasurements::checkRPCRecHits::" << procInstance;
  theRPCCheckName = sRPC.str();
  std::ostringstream sCSC;
  sCSC<<"MuonDetLayerMeasurements::checkCSCRecHits::" << procInstance;
  theCSCCheckName = sCSC.str();
  procInstance++;
}
MuonDetLayerMeasurements::~MuonDetLayerMeasurements ( ) [virtual]

Definition at line 56 of file MuonDetLayerMeasurements.cc.

{}

Member Function Documentation

void MuonDetLayerMeasurements::checkCSCRecHits ( ) [private]

Definition at line 145 of file MuonDetLayerMeasurements.cc.

References checkEvent(), Exception, edm::Event::getByLabel(), edm::EventBase::id(), edm::HandleBase::isValid(), theCSCCheckName, theCSCEventID, theCSCRecHitLabel, theCSCRecHits, and theEvent.

Referenced by recHits().

{
  checkEvent();
  if (!edm::Service<UpdaterService>()->checkOnce(theCSCCheckName)) return;

  {
    theCSCEventID = theEvent->id();
    theEvent->getByLabel(theCSCRecHitLabel, theCSCRecHits);
  }
  if(!theCSCRecHits.isValid())
  {
    throw cms::Exception("MuonDetLayerMeasurements") << "Cannot get CSC RecHits";
  }
}
void MuonDetLayerMeasurements::checkDTRecHits ( ) [private]

Definition at line 129 of file MuonDetLayerMeasurements.cc.

References checkEvent(), Exception, edm::Event::getByLabel(), edm::EventBase::id(), edm::HandleBase::isValid(), theDTCheckName, theDTEventID, theDTRecHitLabel, theDTRecHits, and theEvent.

Referenced by recHits().

{
  checkEvent();
  if (!edm::Service<UpdaterService>()->checkOnce(theDTCheckName)) return;

  {
    theDTEventID = theEvent->id();
    theEvent->getByLabel(theDTRecHitLabel, theDTRecHits);
  }
  if(!theDTRecHits.isValid())
  {
    throw cms::Exception("MuonDetLayerMeasurements") << "Cannot get DT RecHits";
  }
}
void MuonDetLayerMeasurements::checkEvent ( ) const [private]

check that the event is set, and throw otherwise

Definition at line 335 of file MuonDetLayerMeasurements.cc.

References Exception, and theEvent.

Referenced by checkCSCRecHits(), checkDTRecHits(), checkRPCRecHits(), fastMeasurements(), groupedMeasurements(), measurements(), and recHits().

                                                {
  if(!theEvent)
    throw cms::Exception("MuonDetLayerMeasurements") << "The event has not been set";
}
void MuonDetLayerMeasurements::checkRPCRecHits ( ) [private]

Definition at line 161 of file MuonDetLayerMeasurements.cc.

References checkEvent(), Exception, edm::Event::getByLabel(), edm::EventBase::id(), edm::HandleBase::isValid(), theEvent, theRPCCheckName, theRPCEventID, theRPCRecHitLabel, and theRPCRecHits.

Referenced by recHits().

{
  checkEvent();
  if (!edm::Service<UpdaterService>()->checkOnce(theRPCCheckName)) return;

  {
    theRPCEventID = theEvent->id();
    theEvent->getByLabel(theRPCRecHitLabel, theRPCRecHits);
  }
  if(!theRPCRecHits.isValid())
  {
    throw cms::Exception("MuonDetLayerMeasurements") << "Cannot get RPC RecHits";
  }
}
MeasurementContainer MuonDetLayerMeasurements::fastMeasurements ( const DetLayer *  layer,
const TrajectoryStateOnSurface &  theStateOnDet,
const TrajectoryStateOnSurface &  startingState,
const Propagator &  prop,
const MeasurementEstimator &  est 
)

faster version in case the TrajectoryState on the surface of the GeomDet is already available

fastMeasurements method if already got the Event

Definition at line 273 of file MuonDetLayerMeasurements.cc.

References checkEvent(), fastMeasurements(), and theEvent.

                                                                            {
  checkEvent();
  return fastMeasurements(layer, theStateOnDet, startingState, prop, est, *theEvent); 
}
MeasurementContainer MuonDetLayerMeasurements::fastMeasurements ( const DetLayer *  layer,
const TrajectoryStateOnSurface &  theStateOnDet,
const TrajectoryStateOnSurface &  startingState,
const Propagator &  prop,
const MeasurementEstimator &  est,
const edm::Event &  iEvent 
)

faster version in case the TrajectoryState on the surface of the GeomDet is already available

Definition at line 247 of file MuonDetLayerMeasurements.cc.

References MeasurementEstimator::estimate(), recHits(), query::result, and python::multivaluedict::sort().

Referenced by fastMeasurements().

                                                                    {
  MeasurementContainer result;
  MuonRecHitContainer rhs = recHits(layer, iEvent);
  for (MuonRecHitContainer::const_iterator irh = rhs.begin(); irh!=rhs.end(); irh++) {
    MeasurementEstimator::HitReturnType estimate = est.estimate(theStateOnDet, (**irh));
    if (estimate.first)
    {
      result.push_back(TrajectoryMeasurement(theStateOnDet,(*irh).get(),
                                             estimate.second,layer));
    }
  }

  if (!result.empty()) {
    sort( result.begin(), result.end(), TrajMeasLessEstim());
  }

  return result;
}
std::vector< TrajectoryMeasurementGroup > MuonDetLayerMeasurements::groupedMeasurements ( const DetLayer *  layer,
const TrajectoryStateOnSurface &  startingState,
const Propagator &  prop,
const MeasurementEstimator &  est,
const edm::Event &  iEvent 
)

Definition at line 294 of file MuonDetLayerMeasurements.cc.

References GeometricSearchDet::groupedCompatibleDets(), iEvent, measurements(), query::result, and python::multivaluedict::sort().

Referenced by StandAloneMuonFilter::findBestMeasurements(), CosmicMuonTrajectoryBuilder::findBestMeasurements(), and groupedMeasurements().

                                                                      {
  
  std::vector<TrajectoryMeasurementGroup> result;
  // if we want to use the concept of InvalidRecHits,
  // we can reuse LayerMeasurements from TrackingTools/MeasurementDet
  std::vector<DetGroup> groups(layer->groupedCompatibleDets(startingState, prop, est));

  // this should be fixed either in RecoMuon/MeasurementDet/MuonDetLayerMeasurements or
  // RecoMuon/DetLayers/MuRingForwardDoubleLayer
  // and removed the reverse operation in StandAloneMuonFilter::findBestMeasurements

  for (std::vector<DetGroup>::const_iterator grp=groups.begin(); grp!=groups.end(); ++grp) {
    
    std::vector<TrajectoryMeasurement> groupMeasurements;
    for (DetGroup::const_iterator detAndStateItr=grp->begin();
         detAndStateItr !=grp->end(); ++detAndStateItr) {

      std::vector<TrajectoryMeasurement> detMeasurements 
        = measurements(layer, detAndStateItr->det(), detAndStateItr->trajectoryState(), est, iEvent);
      groupMeasurements.insert(groupMeasurements.end(), detMeasurements.begin(), detMeasurements.end());
    }
    
    if (!groupMeasurements.empty()) 
      std::sort( groupMeasurements.begin(), groupMeasurements.end(), TrajMeasLessEstim());  
    
    result.push_back(TrajectoryMeasurementGroup(groupMeasurements, *grp));
  }

  return result;
}
std::vector< TrajectoryMeasurementGroup > MuonDetLayerMeasurements::groupedMeasurements ( const DetLayer *  layer,
const TrajectoryStateOnSurface &  startingState,
const Propagator &  prop,
const MeasurementEstimator &  est 
)

Definition at line 284 of file MuonDetLayerMeasurements.cc.

References checkEvent(), groupedMeasurements(), and theEvent.

                                                                               {
  checkEvent();
  return groupedMeasurements(layer, startingState, prop,  est, *theEvent);
}
MeasurementContainer MuonDetLayerMeasurements::measurements ( const DetLayer *  layer,
const GeomDet *  det,
const TrajectoryStateOnSurface &  stateOnDet,
const MeasurementEstimator &  est,
const edm::Event &  iEvent 
)

Definition at line 216 of file MuonDetLayerMeasurements.cc.

References MeasurementEstimator::estimate(), LogTrace, recHits(), query::result, and python::multivaluedict::sort().

Referenced by StandAloneMuonFilter::findBestMeasurements(), CosmicMuonTrajectoryBuilder::findBestMeasurements(), groupedMeasurements(), and measurements().

                                                                {
  MeasurementContainer result;
  
  // Get the Segments which relies on the GeomDet given by compatibleDets
  MuonRecHitContainer muonRecHits = recHits(det, iEvent);
  
  // Create the Trajectory Measurement
  for(MuonRecHitContainer::const_iterator rechit = muonRecHits.begin();
      rechit != muonRecHits.end(); ++rechit) {

    MeasurementEstimator::HitReturnType estimate = est.estimate(stateOnDet,**rechit);
    LogTrace("RecoMuon")<<"Dimension: "<<(*rechit)->dimension()
                        <<" Chi2: "<<estimate.second<<std::endl;
    if (estimate.first) {
      result.push_back(TrajectoryMeasurement(stateOnDet, rechit->get(),
                                             estimate.second,layer));
    }
  }

  if (!result.empty()) sort( result.begin(), result.end(), TrajMeasLessEstim());
   
  return result;
}
MeasurementContainer MuonDetLayerMeasurements::measurements ( const DetLayer *  layer,
const TrajectoryStateOnSurface &  startingState,
const Propagator &  prop,
const MeasurementEstimator &  est 
)

returns TMeasurements in a DetLayer compatible with the TSOS.

measurements method if already got the Event

Definition at line 179 of file MuonDetLayerMeasurements.cc.

References checkEvent(), measurements(), and theEvent.

                                                                         {
  checkEvent();
  return measurements(layer, startingState, prop, est, *theEvent);
}
MeasurementContainer MuonDetLayerMeasurements::measurements ( const DetLayer *  layer,
const TrajectoryStateOnSurface &  startingState,
const Propagator &  prop,
const MeasurementEstimator &  est,
const edm::Event &  iEvent 
)

returns TMeasurements in a DetLayer compatible with the TSOS.

Definition at line 189 of file MuonDetLayerMeasurements.cc.

References GeometricSearchDet::compatibleDets(), LogTrace, measurements(), query::result, and python::multivaluedict::sort().

                                                               {
  
  MeasurementContainer result;
  
  std::vector<DetWithState> dss = layer->compatibleDets(startingState, prop, est);
  LogTrace("RecoMuon")<<"compatibleDets: "<<dss.size()<<std::endl;
  
  for(std::vector<DetWithState>::const_iterator detWithStateItr = dss.begin();
      detWithStateItr != dss.end(); ++detWithStateItr){

    MeasurementContainer detMeasurements 
      = measurements(layer, detWithStateItr->first, 
                     detWithStateItr->second, est, iEvent);
    result.insert(result.end(), detMeasurements.begin(), detMeasurements.end());
  }
  
  if (!result.empty()) sort( result.begin(), result.end(), TrajMeasLessEstim());
  
  return result;
}
MuonRecHitContainer MuonDetLayerMeasurements::recHits ( const DetLayer *  layer)

returns the rechits which are on the layer

Definition at line 354 of file MuonDetLayerMeasurements.cc.

References checkEvent(), recHits(), and theEvent.

{
  checkEvent();
  return recHits(layer, *theEvent);
}
MuonRecHitContainer MuonDetLayerMeasurements::recHits ( const GeomDet *  geomDet,
const edm::Event &  iEvent 
) [private]

obtain TrackingRecHits from a DetLayer

Definition at line 58 of file MuonDetLayerMeasurements.cc.

References checkCSCRecHits(), checkDTRecHits(), checkRPCRecHits(), CSC(), DetId::det(), GeomDetEnumerators::DT, enableCSCMeasurement, enableDTMeasurement, enableRPCMeasurement, Exception, GeomDet::geographicalId(), iEvent, DetId::rawId(), query::result, dedefs::RPC, MuonTransientTrackingRecHit::specificBuild(), DetId::subdetId(), theCSCRecHits, theDTRecHits, theEvent, and theRPCRecHits.

{
  DetId geoId = geomDet->geographicalId();
  theEvent = &iEvent;
  MuonRecHitContainer result;

  if (geoId.subdetId()  == MuonSubdetId::DT) {
    if(enableDTMeasurement) 
    {
      checkDTRecHits();
    
      // Create the ChamberId
      DTChamberId chamberId(geoId.rawId());
      // LogTrace("Muon|RecoMuon|MuonDetLayerMeasurements") << "(DT): "<<chamberId<<std::endl;
    
      // Get the DT-Segment which relies on this chamber
      DTRecSegment4DCollection::range range = theDTRecHits->get(chamberId);
    
      // Create the MuonTransientTrackingRechit
      for (DTRecSegment4DCollection::const_iterator rechit = range.first; 
           rechit!=range.second;++rechit)
        result.push_back(MuonTransientTrackingRecHit::specificBuild(geomDet,&*rechit));
    }
  }
  
  else if (geoId.subdetId()  == MuonSubdetId::CSC) {
    if(enableCSCMeasurement)
    {
      checkCSCRecHits();

      // Create the chamber Id
      CSCDetId chamberId(geoId.rawId());
      //    LogTrace("Muon|RecoMuon|MuonDetLayerMeasurements") << "(CSC): "<<chamberId<<std::endl;

      // Get the CSC-Segment which relies on this chamber
      CSCSegmentCollection::range range = theCSCRecHits->get(chamberId);
    
      // Create the MuonTransientTrackingRecHit
      for (CSCSegmentCollection::const_iterator rechit = range.first; 
           rechit!=range.second; ++rechit)
        result.push_back(MuonTransientTrackingRecHit::specificBuild(geomDet,&*rechit)); 
    }
  }
  
  else if (geoId.subdetId()  == MuonSubdetId::RPC) {
    if(enableRPCMeasurement)
    {
      checkRPCRecHits(); 

      // Create the chamber Id
      RPCDetId chamberId(geoId.rawId());
      // LogTrace("Muon|RecoMuon|MuonDetLayerMeasurements") << "(RPC): "<<chamberId<<std::endl;
    
      // Get the RPC-Segment which relies on this chamber
      RPCRecHitCollection::range range = theRPCRecHits->get(chamberId);
    
      // Create the MuonTransientTrackingRecHit
      for (RPCRecHitCollection::const_iterator rechit = range.first; 
           rechit!=range.second; ++rechit)
        result.push_back(MuonTransientTrackingRecHit::specificBuild(geomDet,&*rechit));
    }
  }
  else {
    // wrong type
    throw cms::Exception("MuonDetLayerMeasurements") << "The DetLayer with det " << geoId.det() << " subdet " << geoId.subdetId() << " is not a valid Muon DetLayer. ";
  }
  return result;
}
MuonRecHitContainer MuonDetLayerMeasurements::recHits ( const DetLayer *  layer,
const edm::Event &  iEvent 
)

returns the rechits which are on the layer

Definition at line 340 of file MuonDetLayerMeasurements.cc.

References GeometricSearchDet::basicComponents().

Referenced by MuonSeedBuilder::build(), fastMeasurements(), measurements(), RPCSeedGenerator::produce(), CosmicMuonSeedGenerator::produce(), recHits(), CosmicMuonTrajectoryBuilder::trajectories(), and CosmicMuonTrajectoryBuilder::unusedHits().

                                                                              {
  MuonRecHitContainer rhs;
  
  std::vector <const GeomDet*> gds = layer->basicComponents();

  for (std::vector<const GeomDet*>::const_iterator igd = gds.begin(); 
       igd != gds.end(); igd++) {
    MuonRecHitContainer detHits = recHits(*igd, iEvent);
    rhs.insert(rhs.end(), detHits.begin(), detHits.end());
  }
  return rhs;
}
void MuonDetLayerMeasurements::setEvent ( const edm::Event &  event)

set event

Definition at line 330 of file MuonDetLayerMeasurements.cc.

References event(), and theEvent.

Referenced by CosmicMuonSeedGenerator::produce(), StandAloneMuonFilter::setEvent(), and CosmicMuonTrajectoryBuilder::setEvent().

                                                             {
  theEvent = &event;
}

Member Data Documentation

bool MuonDetLayerMeasurements::enableCSCMeasurement [private]

Definition at line 127 of file MuonDetLayerMeasurements.h.

Referenced by recHits().

bool MuonDetLayerMeasurements::enableDTMeasurement [private]

Definition at line 126 of file MuonDetLayerMeasurements.h.

Referenced by recHits().

bool MuonDetLayerMeasurements::enableRPCMeasurement [private]

Definition at line 128 of file MuonDetLayerMeasurements.h.

Referenced by recHits().

std::string MuonDetLayerMeasurements::theCSCCheckName [private]

Definition at line 149 of file MuonDetLayerMeasurements.h.

Referenced by checkCSCRecHits(), and MuonDetLayerMeasurements().

edm::EventID MuonDetLayerMeasurements::theCSCEventID [private]

Definition at line 141 of file MuonDetLayerMeasurements.h.

Referenced by checkCSCRecHits().

edm::InputTag MuonDetLayerMeasurements::theCSCRecHitLabel [private]

Definition at line 123 of file MuonDetLayerMeasurements.h.

Referenced by checkCSCRecHits().

edm::Handle<CSCSegmentCollection> MuonDetLayerMeasurements::theCSCRecHits [private]

Definition at line 132 of file MuonDetLayerMeasurements.h.

Referenced by checkCSCRecHits(), and recHits().

std::string MuonDetLayerMeasurements::theDTCheckName [private]

Definition at line 147 of file MuonDetLayerMeasurements.h.

Referenced by checkDTRecHits(), and MuonDetLayerMeasurements().

edm::EventID MuonDetLayerMeasurements::theDTEventID [private]

Definition at line 140 of file MuonDetLayerMeasurements.h.

Referenced by checkDTRecHits().

edm::InputTag MuonDetLayerMeasurements::theDTRecHitLabel [private]

Definition at line 122 of file MuonDetLayerMeasurements.h.

Referenced by checkDTRecHits().

edm::Handle<DTRecSegment4DCollection> MuonDetLayerMeasurements::theDTRecHits [private]

Definition at line 131 of file MuonDetLayerMeasurements.h.

Referenced by checkDTRecHits(), and recHits().

const edm::Event* MuonDetLayerMeasurements::theEvent [private]

Definition at line 144 of file MuonDetLayerMeasurements.h.

Referenced by checkCSCRecHits(), checkDTRecHits(), checkEvent(), checkRPCRecHits(), fastMeasurements(), groupedMeasurements(), measurements(), recHits(), and setEvent().

std::string MuonDetLayerMeasurements::theRPCCheckName [private]

Definition at line 148 of file MuonDetLayerMeasurements.h.

Referenced by checkRPCRecHits(), and MuonDetLayerMeasurements().

edm::EventID MuonDetLayerMeasurements::theRPCEventID [private]

Definition at line 142 of file MuonDetLayerMeasurements.h.

Referenced by checkRPCRecHits().

edm::InputTag MuonDetLayerMeasurements::theRPCRecHitLabel [private]

Definition at line 124 of file MuonDetLayerMeasurements.h.

Referenced by checkRPCRecHits().

edm::Handle<RPCRecHitCollection> MuonDetLayerMeasurements::theRPCRecHits [private]

Definition at line 133 of file MuonDetLayerMeasurements.h.

Referenced by checkRPCRecHits(), and recHits().

Generated for CMSSW Reference Manual by doxygen 1.7.3