include/Api/PandoraContentApiImpl.h

0001 /**
0002  *  @file   PandoraSDK/include/Api/PandoraContentApiImpl.h
0003  *
0004  *  @brief  Header file for the pandora content api implementation class.
0005  *
0006  *  $Log: $
0007  */
0008 #ifndef PANDORA_CONTENT_API_IMPL_H
0009 #define PANDORA_CONTENT_API_IMPL_H 1
0010
0011 #include "Api/PandoraContentApi.h"
0012
0013 #include "Pandora/ObjectCreation.h"
0014 #include "Pandora/StatusCodes.h"
0015
0016 namespace pandora
0017 {
0018
0019 class Pandora;
0020
0021 //------------------------------------------------------------------------------------------------------------------------------------------
0022
0023 /**
0024  *    @brief PandoraContentApiImpl class
0025  */
0026 class PandoraContentApiImpl
0027 {
0028 private:
0029     /**
0030      *  @brief  Return type adaptor
0031      */
0032     template<class T>
0033     class ReturnType
0034     {
0035     public:
0036         typedef T Type;
0037     };
0038
0039     /**
0040      *  @brief  Manager type adaptor
0041      *
0042      *  @return the address of the manager
0043      */
0044     template<typename T>
0045     typename ReturnType<T>::Type *GetManager() const;
0046
0047
0048     /* Object-metadata manipulation */
0049
0050     /**
0051      *  @brief  Alter the metadata information stored in an object
0052      *
0053      *  @param  algorithm the algorithm calling this function
0054      *  @param  pObject address of the object to modify
0055      *  @param  metaData the metadata (only populated metadata fields will be propagated to the object)
0056      */
0057     template <typename OBJECT, typename METADATA>
0058     StatusCode AlterMetadata(const OBJECT *const pObject, const METADATA &metadata) const;
0059
0060
0061     /* Object-creation functions */
0062
0063     /**
0064      *  @brief  Create an object for pandora
0065      *
0066      *  @param  parameters the object parameters
0067      *  @param  pObject to receive the address of the object created
0068      *  @param  factory the factory that performs the object allocation
0069      */
0070     template <typename PARAMETERS, typename OBJECT>
0071     StatusCode Create(const PARAMETERS &parameters, const OBJECT *&pObject, const ObjectFactory<PARAMETERS, OBJECT> &factory) const;
0072
0073
0074     /* Accessors for plugins and global settings */
0075
0076     /**
0077      *  @brief  Get the pandora event context instance
0078      *
0079      *  @param  key the key associated with the desired event context object
0080      *
0081      *  @return the address of the pandora event context object instance
0082      */
0083     const EventContextObject *GetEventContextObject(const std::string &key) const;
0084
0085     /**
0086      *  @brief  Adds an EventContextObject object to this event context.
0087      *
0088      *  @param  key the key to associate with the event context object
0089      *  @param  pObject the object to be stored
0090      */
0091     void AddEventContextObject(const std::string &key, const EventContextObject *const pObject) const;
0092
0093     /**
0094      *  @brief  Replaces an EventContextObject object within this event context.
0095      *
0096      *  @param  key the key of the event context object to replace
0097      *  @param  pObject the new object to be stored
0098      */
0099     void ReplaceEventContextObject(const std::string &key, const EventContextObject *const pObject) const;
0100
0101     /**
0102      *  @brief  Remove an EventContextObject object from this event context.
0103      *
0104      *  @param  key the key of the event context object to be removed
0105      */
0106     void RemoveEventContextObject(const std::string &key) const;
0107
0108     /**
0109      *  @brief  Get the pandora settings instance
0110      *
0111      *  @return the address of the pandora settings instance
0112      */
0113     const PandoraSettings *GetSettings() const;
0114
0115     /**
0116      *  @brief  Get the pandora geometry instance
0117      *
0118      *  @return the address of the pandora geometry instance
0119      */
0120     const GeometryManager *GetGeometry() const;
0121
0122     /**
0123      *  @brief  Get the pandora plugin instance, providing access to user registered functions and calculators
0124      *
0125      *  @return the address of the pandora plugin instance
0126      */
0127     const PluginManager *GetPlugins() const;
0128
0129
0130     /* High-level steering functions */
0131
0132     /**
0133      *  @brief  Repeat the event preparation stages, which are used to calculate properties of input objects for later use in algorithms
0134      */
0135     StatusCode RepeatEventPreparation() const;
0136
0137     /**
0138      *  @brief  Create an algorithm tool instance, via one of the algorithm tool factories registered with pandora.
0139      *          This function is expected to be called whilst reading the settings for a parent algorithm.
0140      *
0141      *  @param  pXmlElement address of the xml element describing the algorithm tool type and settings
0142      *  @param  pAlgorithmTool to receive the address of the algorithm tool instance
0143      */
0144     StatusCode CreateAlgorithmTool(TiXmlElement *const pXmlElement, AlgorithmTool *&pAlgorithmTool) const;
0145
0146     /**
0147      *  @brief  Create an algorithm instance, via one of the algorithm factories registered with pandora.
0148      *          This function is expected to be called whilst reading the settings for a parent algorithm.
0149      *
0150      *  @param  pXmlElement address of the xml element describing the daughter algorithm type and settings
0151      *  @param  daughterAlgorithmName to receive the name of the daughter algorithm instance
0152      */
0153     StatusCode CreateDaughterAlgorithm(TiXmlElement *const pXmlElement, std::string &daughterAlgorithmName) const;
0154
0155     /**
0156      *  @brief  Run an algorithm registered with pandora
0157      *
0158      *  @param  algorithmName the algorithm name
0159      */
0160     StatusCode RunAlgorithm(const std::string &algorithmName) const;
0161
0162     /**
0163      *  @brief  Run a clustering algorithm (an algorithm that will create new cluster objects)
0164      *
0165      *  @param  algorithm the algorithm calling this function
0166      *  @param  clusteringAlgorithmName the name of the clustering algorithm to run
0167      *  @param  pNewClusterList the address of the new cluster list populated
0168      *  @param  newClusterListName the name of the new cluster list populated
0169      */
0170      StatusCode RunClusteringAlgorithm(const Algorithm &algorithm, const std::string &clusteringAlgorithmName,
0171         const ClusterList *&pNewClusterList, std::string &newClusterListName) const;
0172
0173
0174     /* List-manipulation functions */
0175
0176     /**
0177      *  @brief  Get the current list
0178      *
0179      *  @param  pT to receive the address of the current list
0180      *  @param  listName to receive the current list name
0181      */
0182     template <typename T>
0183     StatusCode GetCurrentList(const T *&pT, std::string &listName) const;
0184
0185     /**
0186      *  @brief  Get the current list name
0187      *
0188      *  @param  listName to receive the current list name
0189      */
0190     template <typename T>
0191     StatusCode GetCurrentListName(std::string &listName) const;
0192
0193     /**
0194      *  @brief  Replace the current list with a pre-saved list; use this new list as a permanent replacement
0195      *          for the current list (will persist outside the current algorithm)
0196      *
0197      *  @param  algorithm the algorithm calling this function
0198      *  @param  newListName the name of the replacement list
0199      */
0200     template <typename T>
0201     StatusCode ReplaceCurrentList(const Algorithm &algorithm, const std::string &newListName) const;
0202
0203     /**
0204      *  @brief  Drop the current list, returning the current list to its default empty/null state
0205      *
0206      *  @param  algorithm the algorithm calling this function
0207      */
0208     template <typename T>
0209     StatusCode DropCurrentList(const Algorithm &algorithm) const;
0210
0211     /**
0212      *  @brief  Get a named list
0213      *
0214      *  @param  listName the name of the list
0215      *  @param  pT to receive the address of the list
0216      */
0217     template <typename T>
0218     StatusCode GetList(const std::string &listName, const T *&pT) const;
0219
0220     /**
0221      *  @brief  Rename a saved list, altering its saved name from a specified old list name to a specified new list name
0222      *
0223      *  @param  oldListName the old list name
0224      *  @param  newListName the new list name
0225      */
0226     template <typename T>
0227     StatusCode RenameList(const std::string &oldListName, const std::string &newListName) const;
0228
0229
0230     /* List-manipulation functions: input objects only (CaloHits, Tracks, MCParticles) */
0231
0232     /**
0233      *  @brief  Save a provided input object list under a new name
0234      *
0235      *  @param  t the provided input object list
0236      *  @param  newListName the new list name
0237      */
0238     template <typename T>
0239     StatusCode SaveList(const T &t, const std::string &newListName) const;
0240
0241
0242     /* List-manipulation functions: algorithm objects only (Clusters, Pfos, Vertices) */
0243
0244     /**
0245      *  @brief  Save the current list in a list with the specified new name. Note that this will empty the list; the objects
0246      *          will all be moved to the new named list.
0247      *
0248      *  @param  newListName the new list name
0249      */
0250     template <typename T>
0251     StatusCode SaveList(const std::string &newListName) const;
0252
0253     /**
0254      *  @brief  Save a named list in a list with the specified new name. Note that this will empty the old list; the objects
0255      *          will all be moved to the new named list.
0256      *
0257      *  @param  oldListName the old list name
0258      *  @param  newListName the new list name
0259      */
0260     template <typename T>
0261     StatusCode SaveList(const std::string &oldListName, const std::string &newListName) const;
0262
0263     /**
0264      *  @brief  Save elements of the current list in a list with the specified new name. If all the objects in the current
0265      *          list are saved, this will empty the current list; the objects will all be moved to the new named list.
0266      *
0267      *  @param  newListName the new list name
0268      *  @param  t a subset of the current object list - only objects in both this and the current list will be saved
0269      */
0270     template <typename T>
0271     StatusCode SaveList(const std::string &newListName, const T &t) const;
0272
0273     /**
0274      *  @brief  Save elements of a named list in a list with the specified new name. If all the objects in the old
0275      *          list are saved, this will empty the old list; the objects will all be moved to the new named list.
0276      *
0277      *  @param  oldClusterListName the old cluster list name
0278      *  @param  newClusterListName the new cluster list name
0279      *  @param  t a subset of the old object list - only objects in both this and the old list will be saved
0280      */
0281     template <typename T>
0282     StatusCode SaveList(const std::string &oldListName, const std::string &newListName, const T &t) const;
0283
0284     /**
0285      *  @brief  Temporarily replace the current list with another list, which may only be a temporary list. This switch
0286      *          will persist only for the duration of the algorithm and its daughters; unless otherwise specified, the current list
0287      *          will revert to the algorithm input list upon algorithm completion.
0288      *
0289      *  @param  newListName the name of the replacement list
0290      */
0291     template <typename T>
0292     StatusCode TemporarilyReplaceCurrentList(const std::string &newListName) const;
0293
0294     /**
0295      *  @brief  Create a temporary list and set it to be the current list, enabling object creation
0296      *
0297      *  @param  algorithm the algorithm calling this function
0298      *  @param  pT to receive the address of the temporary list
0299      *  @param  temporaryListName to receive the temporary list name
0300      */
0301     template <typename T>
0302     StatusCode CreateTemporaryListAndSetCurrent(const Algorithm &algorithm, const T *&pT, std::string &temporaryListName) const;
0303
0304
0305     /* Object-related functions */
0306
0307     /**
0308      *  @brief  Is object, or a list of objects, available as a building block
0309      *
0310      *  @param  pT address of the object
0311      *
0312      *  @return boolean
0313      */
0314     template <typename T>
0315     bool IsAvailable(const T *const pT) const;
0316
0317
0318     /* Object-related functions: algorithm objects only (Clusters, Pfos, Vertices) */
0319
0320     /**
0321      *  @brief  Delete an object from the current list
0322      *
0323      *  @param  pT address of the object, or a list of objects, to delete
0324      */
0325     template <typename T>
0326     StatusCode Delete(const T *const pT) const;
0327
0328     /**
0329      *  @brief  Delete an object from a specified list
0330      *
0331      *  @param  pT address of the object, or a list of objects, to delete
0332      *  @param  listName name of the list containing the object
0333      */
0334     template <typename T>
0335     StatusCode Delete(const T *const pT, const std::string &listName) const;
0336
0337
0338     /* CaloHit-related functions */
0339
0340     /**
0341      *  @brief  Add a calo hit, or a list of calo hits, to a cluster
0342      *
0343      *  @param  pCluster address of the cluster to modify
0344      *  @param  pT address of the calo hit, or list of calo hits, to add
0345      */
0346     template <typename T>
0347     StatusCode AddToCluster(const Cluster *const pCluster, const T *const pT) const;
0348
0349     /**
0350      *  @brief  Remove a calo hit from a cluster. Note this function will not remove the final calo hit from a cluster, and
0351      *          will instead return status code "not allowed" as a prompt to delete the cluster
0352      *
0353      *  @param  pCluster address of the cluster to modify
0354      *  @param  pCaloHit address of the hit to remove
0355      */
0356     StatusCode RemoveFromCluster(const Cluster *const pCluster, const CaloHit *const pCaloHit) const;
0357
0358     /**
0359      *  @brief  Add an isolated calo hit, or a list of isolated calo hits, to a cluster. An isolated calo hit is not counted as a
0360      *          regular calo hit: it contributes only towards the cluster energy and does not affect any other cluster properties.
0361      *
0362      *  @param  pCluster address of the cluster to modify
0363      *  @param  pT address of the isolated calo hit, or list of isolated calo hits, to add
0364      */
0365     template <typename T>
0366     StatusCode AddIsolatedToCluster(const Cluster *const pCluster, const T *const pT) const;
0367
0368     /**
0369      *  @brief  Remove an isolated calo hit from a cluster. Note this function will not remove the final calo hit from a cluster, and
0370      *          will instead return status code "not allowed" as a prompt to delete the cluster
0371      *
0372      *  @param  pCluster address of the cluster to modify
0373      *  @param  pCaloHit address of the isolated hit to remove
0374      */
0375     StatusCode RemoveIsolatedFromCluster(const Cluster *const pCluster, const CaloHit *const pCaloHit) const;
0376
0377     /**
0378      *  @brief  Fragment a calo hit into two daughter calo hits, with a specified energy division
0379      *
0380      *  @param  pOriginalCaloHit address of the original calo hit, which will be deleted
0381      *  @param  fraction1 the fraction of energy to be assigned to daughter fragment 1
0382      *  @param  pDaughterCaloHit1 to receive the address of daughter fragment 1
0383      *  @param  pDaughterCaloHit2 to receive the address of daughter fragment 2
0384      *  @param  factory to create the fragmented calo hits
0385      */
0386     StatusCode Fragment(const CaloHit *const pOriginalCaloHit, const float fraction1, const CaloHit *&pDaughterCaloHit1,
0387         const CaloHit *&pDaughterCaloHit2, const ObjectFactory<object_creation::CaloHitFragment::Parameters, object_creation::CaloHitFragment::Object> &factory) const;
0388
0389     /**
0390      *  @brief  Merge two calo hit fragments, originally from the same parent hit, to form a new calo hit
0391      *
0392      *  @param  pFragmentCaloHit1 address of calo hit fragment 1, which will be deleted
0393      *  @param  pFragmentCaloHit2 address of calo hit fragment 2, which will be deleted
0394      *  @param  pMergedCaloHit to receive the address of the merged calo hit
0395      *  @param  factory to create the merged calo hit fragment
0396      */
0397     StatusCode MergeFragments(const CaloHit *const pFragmentCaloHit1, const CaloHit *const pFragmentCaloHit2,
0398         const CaloHit *&pMergedCaloHit, const ObjectFactory<object_creation::CaloHitFragment::Parameters, object_creation::CaloHitFragment::Object> &factory) const;
0399
0400
0401     /* Track-related functions */
0402
0403     /**
0404      *  @brief  Add an association between a track and a cluster
0405      *
0406      *  @param  pTrack address of the track
0407      *  @param  pCluster address of the cluster
0408      */
0409     StatusCode AddTrackClusterAssociation(const Track *const pTrack, const Cluster *const pCluster) const;
0410
0411     /**
0412      *  @brief  Remove an association between a track and a cluster
0413      *
0414      *  @param  pTrack address of the track
0415      *  @param  pCluster address of the cluster
0416      */
0417     StatusCode RemoveTrackClusterAssociation(const Track *const pTrack, const Cluster *const pCluster) const;
0418
0419     /**
0420      *  @brief  Remove all track-cluster associations from objects in the current track and cluster lists
0421      */
0422     StatusCode RemoveCurrentTrackClusterAssociations() const;
0423
0424     /**
0425      *  @brief  Remove all associations between tracks and clusters
0426      */
0427     StatusCode RemoveAllTrackClusterAssociations() const;
0428
0429
0430     /* MCParticle-related functions */
0431
0432     /**
0433      *  @brief  Repeat the mc particle preparation, performing pfo target identification and forming relationships with tracks/calo hits
0434      */
0435     StatusCode RepeatMCParticlePreparation() const;
0436
0437     /**
0438      *  @brief  Remove all mc particle relationships previously registered with the mc manager and linked to tracks/calo hits
0439      */
0440     StatusCode RemoveAllMCParticleRelationships() const;
0441
0442
0443     /* Cluster-related functions */
0444
0445     /**
0446      *  @brief  Merge two clusters in the current list, enlarging one cluster and deleting the second
0447      *
0448      *  @param  pClusterToEnlarge address of the cluster to enlarge
0449      *  @param  pClusterToDelete address of the cluster to delete
0450      */
0451     StatusCode MergeAndDeleteClusters(const Cluster *const pClusterToEnlarge, const Cluster *const pClusterToDelete) const;
0452
0453     /**
0454      *  @brief  Merge two clusters from two specified lists, enlarging one cluster and deleting the second
0455      *
0456      *  @param  pClusterToEnlarge address of the cluster to enlarge
0457      *  @param  pClusterToDelete address of the cluster to delete
0458      *  @param  enlargeListName name of the list containing the cluster to enlarge
0459      *  @param  deleteListName name of the list containing the cluster to delete
0460      */
0461     StatusCode MergeAndDeleteClusters(const Cluster *const pClusterToEnlarge, const Cluster *const pClusterToDelete, const std::string &enlargeListName,
0462         const std::string &deleteListName) const;
0463
0464
0465     /* Pfo-related functions */
0466
0467     /**
0468      *  @brief  Add a cluster to a particle flow object
0469      *
0470      *  @param  pPfo address of the particle flow object to modify
0471      *  @param  pCluster address of the cluster to add
0472      */
0473     template <typename T>
0474     StatusCode AddToPfo(const ParticleFlowObject *const pPfo, const T *const pT) const;
0475
0476     /**
0477      *  @brief  Remove a cluster from a particle flow object. Note this function will not remove the final object (track or cluster)
0478      *          from a particle flow object, and will instead return status code "not allowed" as a prompt to delete the cluster
0479      *
0480      *  @param  pPfo address of the particle flow object to modify
0481      *  @param  pCluster address of the cluster to remove
0482      */
0483     template <typename T>
0484     StatusCode RemoveFromPfo(const ParticleFlowObject *const pPfo, const T *const pT) const;
0485
0486     /**
0487      *  @brief  Set parent-daughter particle flow object relationship
0488      *
0489      *  @param  pParentPfo address of parent particle flow object
0490      *  @param  pDaughterPfo address of daughter particle flow object
0491      */
0492     StatusCode SetPfoParentDaughterRelationship(const ParticleFlowObject *const pParentPfo, const ParticleFlowObject *const pDaughterPfo) const;
0493
0494     /**
0495      *  @brief  Remove parent-daughter particle flow object relationship
0496      *
0497      *  @param  pParentPfo address of parent particle flow object
0498      *  @param  pDaughterPfo address of daughter particle flow object
0499      */
0500     StatusCode RemovePfoParentDaughterRelationship(const ParticleFlowObject *const pParentPfo, const ParticleFlowObject *const pDaughterPfo) const;
0501
0502
0503     /* Reclustering functions */
0504
0505     /**
0506      *  @brief  Initialize cluster fragmentation operations on clusters in the algorithm input list. This allows hits in a list
0507      *          of clusters (a subset of the algorithm input list) to be redistributed.
0508      *
0509      *  @param  algorithm the algorithm calling this function
0510      *  @param  inputClusterList the input cluster list
0511      *  @param  originalClustersListName to receive the name of the list in which the original clusters are stored
0512      *  @param  fragmentClustersListName to receive the name of the list in which the fragment clusters are stored
0513      */
0514     StatusCode InitializeFragmentation(const Algorithm &algorithm, const ClusterList &inputClusterList,
0515         std::string &originalClustersListName, std::string &fragmentClustersListName) const;
0516
0517     /**
0518      *  @brief  End cluster fragmentation operations on clusters in the algorithm input list
0519      *
0520      *  @param  algorithm the algorithm calling this function
0521      *  @param  clusterListToSaveName the name of the list containing the clusters chosen to be saved (original or fragments)
0522      *  @param  clusterListToDeleteName the name of the list containing the clusters chosen to be deleted (original or fragments)
0523      */
0524     StatusCode EndFragmentation(const Algorithm &algorithm, const std::string &clusterListToSaveName,
0525         const std::string &clusterListToDeleteName) const;
0526
0527     /**
0528      *  @brief  Initialize reclustering operations on clusters in the algorithm input list. This allows hits in a list
0529      *          of clusters (a subset of the algorithm input list) to be redistributed.
0530      *
0531      *  @param  algorithm the algorithm calling this function
0532      *  @param  inputTrackList the input track list
0533      *  @param  inputClusterList the input cluster list
0534      *  @param  originalClustersListName to receive the name of the list in which the original clusters are stored
0535      */
0536     StatusCode InitializeReclustering(const Algorithm &algorithm, const TrackList &inputTrackList,
0537         const ClusterList &inputClusterList, std::string &originalClustersListName) const;
0538
0539     /**
0540      *  @brief  End reclustering operations on clusters in the algorithm input list
0541      *
0542      *  @param  algorithm the algorithm calling this function
0543      *  @param  selectedClusterListName the name of the list containing the chosen recluster candidates (or the original candidates)
0544      */
0545     StatusCode EndReclustering(const Algorithm &algorithm, const std::string &selectedClusterListName) const;
0546
0547 private:
0548     /**
0549      *  @brief  Constructor
0550      *
0551      *  @param  pPandora address of the pandora object to interface
0552      */
0553     PandoraContentApiImpl(Pandora *const pPandora);
0554
0555     /**
0556      *  @brief  Whether a proposed addition to a cluster is allowed
0557      *
0558      *  @param  pCluster address of the cluster to modify
0559      *  @param  pCaloHit address of the hit to add
0560      *
0561      *  @return boolean
0562      */
0563     bool IsAddToClusterAllowed(const Cluster *const pCluster, const CaloHit *const pCaloHit) const;
0564
0565     /**
0566      *  @brief  Prepare an object, or a list of objects, for deletion
0567      *
0568      *  @param  pT address of the object, or list of objects, to prepare for deletion
0569      */
0570     template <typename T>
0571     StatusCode PrepareForDeletion(const T *const pT) const;
0572
0573     /**
0574      *  @brief  Prepare an object, or a list of objects, (formed as recluster candidates) for deletion
0575      *
0576      *  @param  pT address of the object, or list of objects, to prepare for deletion
0577      */
0578     template <typename T>
0579     StatusCode PrepareForReclusteringDeletion(const T *const pT) const;
0580
0581     /**
0582      *  @brief  Perform necessary operations prior to algorithm execution, e.g. algorithm to manager handshakes
0583      *
0584      *  @param  pAlgorithm address of the algorithm
0585      */
0586     StatusCode PreRunAlgorithm(Algorithm *const pAlgorithm) const;
0587
0588     /**
0589      *  @brief  Perform necessary operations after algorithm execution, e.g. preparing temporaries for deletion
0590      *
0591      *  @param  pAlgorithm address of the algorithm
0592      */
0593     StatusCode PostRunAlgorithm(Algorithm *const pAlgorithm) const;
0594
0595     Pandora    *m_pPandora;    ///< The pandora object to provide an interface to
0596
0597     friend class Pandora;
0598     friend class PandoraImpl;
0599     friend class ::PandoraContentApi;
0600     template<typename PARAMETERS, typename METADATA, typename OBJECT> friend class ::object_creation::ObjectCreationHelper;
0601 };
0602
0603 } // namespace pandora
0604
0605 #endif // #ifndef PANDORA_CONTENT_API_IMPL_H