EIC code displayed by LXR master/​DD4hep/​doc/​usermanuals/​DDCond/​DDCondManual.tex	Source navigation Diff markup Identifier search General search
	Version: master test Revert   Change

Warning, /DD4hep/doc/usermanuals/DDCond/DDCondManual.tex is written in an unsupported language. File is not indexed.

 %=============================================================================
 \documentclass[10pt,a4paper]{article}
 %
 \input{./setup/DD4hep-setup.tex}
 \input{./setup/AIDA2020-setup.tex}
 %
 \pagestyle{fancyplain}{\fancyfoot[C]{\sffamily{DDCond User Manual}}}
 %
 \graphicspath{{./figs/}}
 \begin{document}   
 %
 \mytitle{DDCond}
 {
 Conditions Support for the \\
 \vspace{0.5cm}
 DD4hep Geometry Description \\
 \vspace{0.5cm}
 Toolkit
 \vspace{2cm}
 }
 {
 M. Frank \\
 {CERN, 1211 Geneva 23, Switzerland}
 }
 %
 %
 %==  Abstract  ===============================================================
 \pagestyle{plain}
 \pagenumbering{Roman}
 \setcounter{page}{1}
 \begin{abstract}
 %=============================================================================
 
 \noindent
 \normalsize
 Experimental setups in High Energy Physics are highly complex assemblies 
 consisting of various detector devices typically called {\it{subdetectors}}.
 To properly interpret the electronic signals which form the response of 
 particle collisions inside these subdetectors other auxiliary data are 
 necessary. These auxiliary data typically are time dependent - though normally
 at a much longer scale than the event data itself. The conditions part of the 
 \DDhep toolkit, called \DDC, addresses the management and the access of such
 conditions data. The Manual describes a solution, which pools groups of these
 time dependent data according to its validity. This approach firstly
 allows to quickly access all relevant data for a given particle collision.
 efficient caching mechansims and allows to quickly determine which data items
 need to be accessed from a persistent medium.
 The design is strongly driven by easy of use;
 developers of detector descriptions and applications using
 them should provide minimal information and minimal specific
 code to achieve the desired result.
 
 \end{abstract}
 
 \vspace{8cm}
 
 \begin{center}
 {\large{\bf{
 \begin{tabular} {| l | l | l |}
 \hline
 \multicolumn{3}{| c |}{} \\[0.2cm]
 \multicolumn{3}{| c |}{Document History} \\[0.2cm]
 \multicolumn{3}{| c |}{} \\[0.2cm]
 \hline
                  &      &        \\
 Document         &      &        \\
 version          & Date & Author \\[0.2cm] \hline
                  &      &        \\
 1.0              & 10/4/2014 & Markus Frank CERN/LHCb  \\
                  &      &        \\        \hline 
 \end{tabular}
 }}}
 \end{center}
 
 \clearpage
 %
 %
 %==  TOC  ====================================================================
 \tableofcontents
 \clearpage
 %
 %
 %=============================================================================
 % Manual
 %=============================================================================
 \pagenumbering{arabic}
 \setcounter{page}{1}
 
 %=============================================================================
 \section{Introduction}
 \label{sec:ddcond-user-manual-introduction}
 %=============================================================================
 \noindent
 In a high energy physics experiment the data originating from particle 
 collisions (so called $Event$-$data$) in most cases require supplementary, 
 mostly  environmental, calibration- or alignment data to extract the physics
 content from the recorded event data. These supplementary data are 
 time-dependent and  typically called $conditons$. The ability of an 
 experiment to produce correct and timely results depends on the complete 
 and efficient availability of  needed conditions for each stage of data 
 handling. This manual should introduce to the \DDC toolkit, which provides 
 access to conditions data within the \DDH data structures~\cite{bib:dd4hep-manual}.
 
 \noindent
 The \DDC extensions to the \DDH toolkit formalize both the access and 
 the management to time-dependent data necessary to process the event data.
 In this manual we will shortly describe the model used to organize and manage 
 the conditions data internally and then describe the user interface to
 actually perform the required actions.
 These conditions data typically are stored in a database. Nearly every
 high energy physics experiment has strong feelings how to efficiently
 read and store the conditions data in terms of tablespace organization 
 and data format.
 For this reason \DDC does not attempt to solve the persistency problem,
 but rather defines an interface used to load missing data items from the 
 persistent medium. Any persistent data representation, which can fulfill
 the requirements of this interface may be adopted by the \DDC 
 conditions caching and access mechanism.
 
 \noindent
 At the end of this manual a walk-through of an example is discussed to 
 illustrate, which steps have to be performed to use the \DDH conditions
 store within a client application.
 
 %=============================================================================
 \subsection{Definition of Conditions Data}
 \label{subsec:ddcond-conditions-data}
 %=============================================================================
 \noindent
 Conditions data are firstly
 \begin{itemize}\itemcompact
 \item raw data values. Raw data values are recorded from measurement 
       devices such as 
       thermometers, pressure devices or 
       geometrical parameters resulting
       from survey parameters and others.
       These data may change with time, but have one and only one version.
 \item Secondly there is the large group of data derived from the raw values.
       These derived values are transformed from one or several raw values
       into new data items with an interval of validity being the
       intersection of the intervals of validity of its ingredients.
       Effectively every raw measurement requires calibration to represent
       a useful value. Hence, nearly all raw values require such a 
       transformation. Since these data are re-calibrated, not only one version
       exists, but many e.g. as a result of different calibration algorithms. 
 \end{itemize}
 Typically one data processing application predefines for all events 
 to be processed the corresponding versions of the conditions data to be used.
 This time span typically is much larger than the intervals of validity 
 of single data value.
 The collection of all individual data item version for such a large time interval
 is called a "global tag".
 Within such a global tag, several conditions values of the same data item, but 
 with a different interval of validity may be accessed.
 
 \noindent
 Given this definition it is evident that the division between raw values 
 and derived conditions is rather fluent. Derived data as a result of
 a calibration process are technically identical to raw values in an
 analysis application using these re-calibrated constants.
 Hence, as soon as derived data enter the conditions database they are 
 technically identical to raw values.
 
 \noindent
 To support such calibration processes producing derived conditions 
 data, \DDC provides a mechanism to project new values given 
 a set of recipes provided by the user. This recipes can project a 
 set of coherent new conditions for a given event time accordingly.
 
 
 %=============================================================================
 \subsection{Conditions Slices}
 \label{subsec:ddcond-conditions-slices}
 %=============================================================================
 
 \noindent
 Conditions slices define a coherent set of conditions data valid for an event 
 recorded at a specific time. Each of the individual conditions of the slice
 has a certain interval of validity, hence the validity of the entire slice
 is defined as the intersection of these validities.
 As a corollary, the slice may be valid for more than one event as long as the
 event's time stamp is within this intersection. To maximize the flexibility,
 and to allow users to implement private slice implementations, slices have 
 a common interface, the $ConditionsMap$ (See section~\ref{subsec:ddcond-conditionsmap}). 
 For most practical purposes and to share tools between slice implementations, 
 this interface is sufficient.
 
 %=============================================================================
 \section{Generic Concepts and Design}
 \label{sec:ddcond-design-concepts}
 %=============================================================================
 
 \noindent 
 The \DDH conditions mechanism was designed to be very flexible concerning 
 back-end implementations. Most of the conditions and alignment utilities offered 
 by \DDH are available if a minimal interface is respected. This minimal interface
 includes a container called $ConditionsMap$ (See section~\ref{subsec:ddcond-conditionsmap})
 and the layout of the conditions objects (See section~\ref{subsec:ddcond-conditions-data}).
 The conditions objects contain a flexible user defined payload and a generic, 
 interface used to interact with tools and the generic container object or
 conditions slices as described in section~\ref{subsec:ddcond-conditions-slices}.
 
 %=============================================================================
 \subsection{Condition Objects and Conditions Data}
 \label{subsec:ddcond-conditions-data}
 %=============================================================================
 
 \noindent
 A conditions objects serves two purposes:
 \begin{itemize}\itemcompact
 \item Firstly, it supports the basic functionality which is generic to any 
       condition -- independent of the actual user payload. This information 
       includes access to the interval of validity and the key to uniquely identify
       the condition. 
 
 \item Secondly, the objects hosts and manages a user payload, the actual
       conditions data. These data are freely user defined. An automatic 
       parsing mechanism from a string representation is supported if the 
       payload-class can properly described using a boost::spirit
       parsing structure. Default type implementations are defined for 
       \begin{itemize}\itemcompact
         \item all primitive data types, 
         \item ROOT::Math::XYZVector, ROOT::Math::XYZPoint, ROOT::Math::PxPyPzEVector.
         \item a number of STL containers of the above basic data types:\\
                 std::vector\textless TYPE\textgreater, 
                 std::list\textless TYPE\textgreater,
                 std::set\textless TYPE\textgreater,\\
                 std::map\textless int,TYPE\textgreater,
                 std::map\textless string,TYPE\textgreater,\\
                 std::pair\textless int,TYPE\textgreater,
                 std::pair\textless string,TYPE\textgreater.
       \end{itemize}
       Additional types can easily be implemented using boost::spirit if the basic
       representation is in the form of a string. Dummy boost::spirit parsers 
       may be implemented if the conversion to and from strings is not required.
 \item Thirdly, it supports the basic functionality required by a 
       conditions management framework, which implements the $ConditionsMap$ 
       interface.
 \end{itemize}
 For completeness we include here the basic data access methods of the conditions
 class\\
 (see \detdesc{classdd4hep_1_1_condition.html}{DD4hep/Conditions.h}):
 
 \begin{unnumberedcode}
   class Condition: public Handle<detail::ConditionObject> {
     /** Interval of validity                                   */
     /// Access the IOV type
     const IOVType& iovType()  const;
     /// Access the IOV block
     const IOV& iov()  const;
  
     /** Conditions identification using integer keys.          */
     /// Hash identifier
     key_type key()  const;
     /// DetElement part of the identifier
     detkey_type  detector_key()  const;
     /// Item part of the identifier
     itemkey_type item_key()  const;
 
     /** Conditions meta-data and handling of the data binding  */
     /// Access the opaque data block
     OpaqueData& data()  const;
     /// Access to the type information
     const std::type_info& typeInfo() const;
     /// Access to the grammar type
     const BasicGrammar& descriptor() const;
     /// Check if object is already bound....
     bool is_bound()  const  {  return isValid() ? data().is_bound() : false;  }
     /// Bind the data of the conditions object to a given format.
     template <typename T> T& bind();
     /// Set and bind the data of the conditions object to a given format.
     template <typename T> T& bind(const std::string& val);
     /// Generic getter. Specify the exact type, not a polymorph type
     template <typename T> T& get();
     /// Generic getter (const version). Specify the exact type, not a polymorph type
     template <typename T> const T& get() const;
     ...
   };
 \end{unnumberedcode}
 Please be aware that the access to the IOV and the IOVType is only 
 possible if supported by the caching mechanism.
 
 \noindent
 Using the $OpaqueData$ data structure and its concrete implementation,
 the user can map any data item to the conditions object using the 
 $bind()$ method and retrieve the data back using $get()$.
 Clearly, the left should know what the right does and the types to be
 retrieved back must match be bound data types.
 
 \noindent
 The following code-snippet shows how to bind conditions data:
 \vspace{-0.2cm}
 \begin{unnumberedcode}
   Condition cond = ...;
   // Fill conditions data by hand:
   std::vector<int>& data = cond.bind<std::vector<int> >();
   data.push_back(0);
   data.push_back(1);    .....
 
   // Fill conditions data from the string representation using boost::spirit:
   std::string str = "[0,1,2]";
   std::vector<int>& data = cond.bind<std::vector<int> >(str);
   int i = data[0]; ....  
 \end{unnumberedcode}
 This is an example how to access already bound data:
 \vspace{-0.2cm}
 \begin{unnumberedcode}
   Condition cond = ...;
 
   // Fill conditions data by hand:
   std::vector<int>& data = cond.get<std::vector<int> >();
 \end{unnumberedcode}
 
 
 %=============================================================================
 \subsection{The ConditionsMap Interface}
 \label{subsec:ddcond-conditionsmap}
 %=============================================================================
 
 \noindent
 The $ConditionsMap$ interface (see 
 defines the lowest common denominator to
 allow tools or clients to interact with conditions of a given slice.
 This interface defines the interaction of clients with a conditions slice.
 These interactions cover both the data access and the data management 
 within a slice. The interface allows to
 \begin{itemize}\itemcompact
 \item access individual conditions by the detector element
 and a given item key. The interface allows
 \item to scan conditions according to the detector element or 
 \item to scan all conditions contained. Further it allows 
 \item insert conditions to the mapping and
 \item to clear the content.
 \end{itemize}
 The provision of these basic interaction mechanisms allows us to build
 very generic tools firstly for conditions, but also later for the
 management and th computation of alignment data as described in
 the \DDA manual~\cite{bib:ddalign-manual}.
 
 \noindent
 The $ConditionsMap$ interface class, which supports this basic functionality
 has the following entry points:
 \begin{unnumberedcode}
   class ConditionsMap   {
   public:
     /// Insert a new entry to the map. The detector element key and 
     /// the item key make a unique global conditions key
     virtual bool insert(DetElement         detector,
                         Condition::itemkey_type key,
                         Condition          condition) = 0;
     /// Interface to access conditions by hash value. The detector element key 
     /// and the item key make a unique global conditions key
     virtual Condition get(DetElement              detector,
                           Condition::itemkey_type key) const = 0;
     /// Interface to scan data content of the conditions mapping
     virtual void scan(const Condition::Processor& processor) const = 0;
 
     /// No ConditionsMap overload: Access all conditions within 
     /// a key range in the interval [lower,upper]
     virtual std::vector<Condition> get(DetElement              detector,
                                        Condition::itemkey_type lower,
                                        Condition::itemkey_type upper)  const;
       
     /// Interface to partially scan data content of the conditions mapping
     virtual void scan(DetElement                  detector,
                       Condition::itemkey_type     lower,
                       Condition::itemkey_type     upper,
                       const Condition::Processor& processor) const;
   };
 \end{unnumberedcode}
 Such $ConditionsMap$ implementations can easily be constructed using standard
 STL maps. The lookup key is constructed out of two elements:
 \begin{itemize}\itemcompact
 \item The detector element this condition belongs to and 
 \item an identifier of condition within this detector element.
 \end{itemize}
 An efficient implementation of a longword key would consist of the tuple:
 $$
 [ hash32(conditions\ name) , hash32(det-element\ path) ],
 $$
 which resembles to an ordered sequence of conditions according to 
 their detector element. A special implementation, which implements 
 this user interface is the $ConditionsSlice$ implemented in the 
 \DDC package (See section \ref{subsec:ddcond-conditions-store} for details).
 
 %=============================================================================
 \subsection{Common Conditions Tools}
 \label{subsec:ddcond-conditions-tools}
 %=============================================================================
 
 \noindent
 \begin{itemize}
 \item \bold{ConditionsPrinter} A tool to print conditions by scanning conditions for a 
         single $DetElement$ or the entire sub-tree. See 
         \detdesc{classdd4hep_1_1cond_1_1_conditions_printer.html}{DDCore/ConditionsPrinter.h} 
         for details).
 \item \bold{ConditionsProcessor} A wrapper to support condition functors implementing 
         the default callback:
         $$
         int\ operator()\ (Condition\ consition);
         $$
         The return value may be used to e.g. collect counters.
 \end{itemize}
 
 \newpage
 %=============================================================================
 \section{DDCond Conditions Store and Slices}
 \label{subsec:ddcond-conditions-store}
 %=============================================================================
 
 \noindent
 The $ConditionsMap$ interface allows tools to work with various conditions 
 data stores. \DDC provides an efficient implementation of such a store,
 which is described in the following chapters.
 
 %=============================================================================
 \subsection{Data Organization}
 \label{subsec:ddcond-internal-data-organization}
 %=============================================================================
 
 \noindent
 The basic assumption of the \DDC conditions store to optimize the access 
 and the management of conditions
 data can be very simply summarized: it is assumed, that groups of data items
 exist, which have a common interval of validity. In other words: given a 
 certain event, valid or invalid conditions can quickly be identified by 
 checking the so called "interval of validity" of the entire group with the
 time stamp of the event. This interval of validity defines the time span
 for which a given group of processing parameters is valid. It starts and 
 ends with a time stamp. The definition of a time stamp may be user defined 
 and not necessarily resemble to values in seconds or fractions thereof. 
 Time stamps could as well be formulated as an interval of luminosity sections,
 run numbers, fill numbers or entire years. 
 
 %=============================================================================
 \begin{figure}[t]
   \begin{center}\includegraphics[height=11cm] {DDCond-ConditionsStore}
     \caption{The graphical representation of the organisation of the
              conditions data in \DDH. }
     \label{fig:ddcond-data-organization}
   \end{center}
 \end{figure}
 
 \noindent
 Groups of parameters associated to certain intervals of validity can
 be very effectively managed if pooled together according to the 
 interval of validity. This of course assumes that each group contains
 a significant number of parameters. If each of these pools only contains
 one single value this would not be an efficient.
 
 \noindent
 This assumption is fundamental for this approach to be efficient. 
 If the data are not
 organized accordingly, the caching mechanism implemented in \DDC will 
 still work formally. However, by construction it cannot not work efficiently. 
 Resources both in CPU and memory would be wasted at run-time.
 The necessity to properly organize the conditions data becomes
 immediately evident in Figure~\ref{fig:ddcond-data-organization}:
 Users can organize data according to certain types, These types are
 independently managed and subdivided into pools. Each of these pools
 manages a set of conditions items sharing the same interval ov validity.
 
 \noindent
 The internal organization of the conditions data in \DDC is entirely 
 transparent to the user. The description here is contained for
 completeness and for the understanding of the limitations of the implemented
 approach. If different requirements or access patterns concerning the 
 access to conditions data arise, it should though be feasible to implement
 these fairly straight forward using a suited approach.
 
 %=============================================================================
 \subsection{Slice Configuration and Data Access}
 \label{subsec:ddcond-data-access}
 %=============================================================================
 
 \noindent
 As defined in section~\ref{subsec:ddcond-conditions-slices}, the conditions slice
 is the main entity to project conditions suitable to process a given particle
 collision (see \detdesc{classdd4hep_1_1cond_1_1_conditions_content.html}{DDCond/ConditionsContent.h}
 for details). Figure~\ref{fig:ddcond-slice-definition} shows the data content of a 
 conditions slice.
 As shown also in Figure~\ref{fig:ddcond-slice-usage}, there are 
 several steps to be performed before a conditions slice is ready to be used:
 \begin{enumerate}\itemcompact
 \item Create the conditions data slice.
 \item Setting up the data content of the slice by attaching an object of type
       $ConditionsContent$.
 \item Preparing the conditions data slice.
 \item Using the conditions data slice.
 \end{enumerate}
 
 %=============================================================================
 \begin{figure}[h]
   \begin{center}\includegraphics[width=12cm] {DDCond-ConditionsSlice}
     \caption{The data content of a $ConditionsSlice$ containing the 
              desired content ($ConditionsContent$), the pool to access the
              conditions data by key ($UserPool$) and optional containers
              showing the status of partial or unsuccessful load and prepare operations.}
     \label{fig:ddcond-slice-usage}
   \end{center}
 \end{figure}
 
 \noindent
 The $ConditionsContent$ 
 (see \detdesc{classdd4hep_1_1cond_1_1_conditions_slice.html}{DDCond/ConditionsSlice.h} 
 for details)  is a simple object, which contains load addresses
 to identify persistent conditions within the database/persistent schema 
 used and a set of dependency rules to compute the corresponding derived conditions.
 
 %=============================================================================
 \begin{figure}[t]
   \begin{center}\includegraphics[width=15cm] {DDCond-ConditionsAccess}
     \caption{The interaction of a user with the conditions
              data store using the $ConditionsSlice$ and the 
              $ConditionsManager$ interface to define the conditions content, 
              prepare the data and then access the loaded data from the slice
              projected according to the required interval of validity.}
     \label{fig:ddcond-slice-usage}
   \end{center}
 \end{figure}
 
 \noindent
 The $ConditionsSlice$ holds a consistent set of conditions valid for a given 
 interval of validity, which is the intersection of the intervals of 
 validity of all contained conditions. The has the following consequences 
 for the client when using a prepared $ConditionsSlice$:
 \begin{itemize}
 \item $ConditionsSlice$ objects are prepared by the client framework.
       Specific algorithms and other code fragments developed by physicist users
       should not deal with such activities. In multi-threaded applications
       the preparation of a $ConditionsSlice$ may be done in a separate thread.
 \item Once prepared, the slice nor the contained conditions may be altered.
       All contained conditions must be considered read-only.
 \item Since the slice is considered read-only, it can be used by multiple 
       clients simultaneously. In particular, multiple threads may share 
       the same slice.
 \item A $ConditionsSlice$ may only be re-used and prepared according to
       a different interval of validity once no other clients use it.
 \item At any point of time any number of $ConditionsSlice$ objects
       may be present in the client framework. There is no interference
       as long as the above mentioned requirements are fulfilled.
 \end{itemize}
 
 \noindent
 The fact that multiple instances of the conditions slices may be present 
 as well as the fact that the preparation of slices and their use is strictly
 separated makes then ideal for the usage within multi-threaded event 
 processing frameworks. As shown in 
 figure~\ref{fig:ddcond-multi-threaded-processing}, 
 the following use cases can easily be met:
 \begin{itemize}
 \item Mulitple threads may share the same slice while processing event data
       (thread 1-3) as long as the time stamp of the event data processed 
       by each thread is contained in the interval of validity of the
       slice.
 \item At the same time another thread may process event data with a different
       time stamp. The conditions for this event were prepared using another slice
       (thread 4-N).
 \end{itemize}
 
 %=============================================================================
 \begin{figure}[t]
   \begin{center}\includegraphics[width=15cm] {DDCond-ConditionsMT}
     \caption{MT.}
     \label{fig:ddcond-multi-threaded-processing}
   \end{center}
 \end{figure}
 \vspace{-0.5cm}
 
 
 %=============================================================================
 \subsection{Loading Conditions Data}
 \label{subsec:ddcond-data-loading}
 %=============================================================================
 
 \noindent
 The loading of conditions data is highly experiment specific. Different 
 access patterns and load implementations (single threaded, multi-threaded, locking etc.)
 make it close to impossible to implement any solution fitting all needs.
 For this reason the loading of conditions is deferred to an abstract implementation,
 which is invoked during the preparation phase of a conditions slice if the required
 data are not found in the conditions cache. This data loader interface
 (see \detdesc{classdd4hep_1_1cond_1_1_conditions_data_loader.html}{ConditionsDataLoader.h}
 for details), receives all relevant callbacks from the framework to resolve 
 missing conditions and pass the loaded objects to the framework for the management.
 The callback to be implemented by the framework developers are:
 \begin{unnumberedcode}
 /// Interface for a generic conditions loader
 /** 
  *  Common function for all loader.
  */
 class ConditionsDataLoader : public NamedObject, public PropertyConfigurable   {
   typedef Condition::key_type                                   key_type;
   typedef std::map<key_type,Condition>                          LoadedItems;
   typedef std::vector<std::pair<key_type,ConditionsLoadInfo*> > RequiredItems;
 public:
   ....
   /// Load a number of conditions items from the persistent medium according to the required IOV
   virtual size_t load_many(  const IOV&       req_validity,
                              RequiredItems&   work,
                              LoadedItems&     loaded,
                              IOV&             combined_validity) = 0;
 };
 \end{unnumberedcode}
 The arguments to the callback contain the necessary information to retrieve
 the requested items.
 
 \newpage
 %=============================================================================
 \section{Example Walkthrough}
 \label{sec:ddcond-example}
 %=============================================================================
 
 
 %=============================================================================
 \subsection{Example to Save Conditions to a ROOT File}
 \label{subsec:ddcond-example-saving}
 %=============================================================================
 
 \noindent
 To illustrate the usage of the \DDC package when saving conditions,
 an example is discussed here in detail.
 The full example is part of the conditions unit tests and can be found in the 
 \DDH examples.\\
 (See examples/Conditions/src/ConditionExample\_manual\_save.cpp).
 
 \noindent
 The examples uses conditions names and detector element names explicitly and
 hence requires a fixed detector description being loaded in memory.
 For simplicity we use here the Minitel example from the examples/ClientTests.
 However, the example is very generic and also the conditions are "generic",
 hence any geometry would work.
 
 
 \vspace{0.6cm}
 
 \noindent
 {\bf{Prerequisites:}} \\
 \\
 A valid compact geometry description to be loaded during the program startup.
 
 \vspace{0.6cm}
 
 \noindent
 {\bf{Plugin Invocation:}} \\
 \\
 A valid example conditions data file is required. Then use the default way
 to invoke plugins:\\
 \tw{\$ > geoPluginRun\ \textrm{-}destroy  \ \ \ \char`\\} \\
 \tw{\hspace{3cm} \textrm{-}plugin\ DD4hep\_ConditionExample\_manual\_save \ \ \ \char`\\} \\
 \tw{\hspace{3cm} \textrm{-}input\ file:\$\{DD4hep\_DIR\}/examples/AlignDet/compact/Telescope.xml
     \ \ \ \char`\\} \\
 \tw{\hspace{3cm} \textrm{-}conditions\ Conditions.root\ \textrm{-}runs\ 10}
 
 
 \vspace{0.6cm}
 
 \noindent
 {\bf{Example Code:}} \\
 
 \begin{code}
   int          num_run    = <number of condition loads>;
   const string conditions = <conditions file name>;
   const string geometry   = <geometry compact xml description";
 
   description.fromXML(geometry);
   description.apply("DD4hep_ConditionsManagerInstaller",0,(char**)0);
 
   ConditionsManager manager = ConditionsManager::from(description);
   manager["PoolType"]       = "DD4hep_ConditionsLinearPool";
   manager["UserPoolType"]   = "DD4hep_ConditionsMapUserPool";
   manager["UpdatePoolType"] = "DD4hep_ConditionsLinearUpdatePool";
   manager.initialize();
 
   shared_ptr<ConditionsContent> content(new ConditionsContent());
   shared_ptr<ConditionsSlice>   slice(new ConditionsSlice(manager,content));
 
   const IOVType*    iov_typ = manager.registerIOVType(0,"run").second;
   if ( 0 == iov_typ )
     except("ConditionsPrepare","++ Conditions IOV type registration failed!");
 
   Scanner(ConditionsKeys(*content,INFO),description.world());
   Scanner(ConditionsDependencyCreator(*content,DEBUG),description.world());
 
   // Have 10 run-slices [11,20] .... [91,100]
   for(int i=0; i<num_run; ++i)  {
     IOV iov(iov_typ, IOV::Key(1+i*10,(i+1)*10));
     ConditionsPool*   iov_pool = manager.registerIOV(*iov.iovType, iov.key());
     // Create conditions with all deltas. Use a generic creator
     Scanner(ConditionsCreator(*slice, *iov_pool, INFO),description.world(),0,true);
   }
 
 \end{code}
 
 \noindent
 {\bf{Explanation:}} \\
 \begin{tabular} {l||p{0cm}}
 \docline{Line}{}
 \docline{1-3}{Definition of processing parameters.}
 \docline{5}{Load the detector description using the compact notation.}
 \docline{6}{Install the conditions manager implementation using the plugin mechanism.}
 \docline{8}{Access conditions manager instance from the Detector interface.}
 \docline{9-11}{Configure the properties of the conditions manager.}
 \docline{12}{Initialize the conditions manager instance.}
 \docline{14-15}{Create an empty $ConditionsSlice$ instance the container with 
                 the desired conditions content.}
 \docline{17}{Register IOV type the Conditions Manager. The IOV types are part of the conditions
             persistency mechanism. They may not change with time and have to be defined 
             by the experiment once and for all!}
 \docline{18-19}{This is example specific and only a shortcut to fill the 
              required conditions content and the derivation rules.\\
              In real life this would be intrinsic to the experiment's 
              data processing framework.}
 \docline{18}{Populate the $ConditionsContent$ instance with the addresses (keys) 
              of the conditions required:
              We scan the $DetElement$ hierarchy and add a couple of conditions
              for each $DetElement$}
 \docline{19}{Add for each $DetElement$ 3 derived conditions,
              which all depend on the persistent condition derived\_data.\\
              In the real world this would be very specific derived actions.}
 
 \end{tabular}
 
 \newpage
 
 
 %=============================================================================
 \subsection{Example to Load and Prepare Conditions(Slices)}
 \label{subsec:ddcond-example-loading}
 %=============================================================================
 
 \noindent
 To illustrate the usage of the \DDC package when loading conditions,
 an example is discussed here in detail.
 The full example is part of the conditions unit tests and can be found in the 
 \DDH examples.\\
 (See examples/Conditions/src/ConditionExample\_manual\_load.cpp).
 
 \noindent
 The examples uses conditions names and detector element names explicitly and
 hence requires a fixed detector description being loaded in memory.
 For simplicity we use here the Minitel example from the examples/ClientTests.
 However, the example is very generic and also the conditions are "generic",
 hence any geometry would work.
 
 \vspace{0.6cm}
 
 \noindent
 {\bf{Prerequisites:}} \\
 \\
 A valid example conditions data file is required, since in this example we 
 load the conditions and inject them to the store from an already existing root file.
 To obtain such a file for a given geometry, execute the example plugin:\\
 \tw{\$ > geoPluginRun\ \textrm{-}destroy  \ \ \ \char`\\} \\
 \tw{\hspace{3cm} \textrm{-}plugin\ DD4hep\_ConditionExample\_manual\_save \ \ \ \char`\\} \\
 \tw{\hspace{3cm} \textrm{-}input\ file:\$\{DD4hep\_DIR\}/examples/AlignDet/compact/Telescope.xml
     \ \ \ \char`\\} \\
 \tw{\hspace{3cm} \textrm{-}conditions Conditions.root\ \textrm{-}runs\ 10}
 
 \vspace{0.6cm}
 
 \noindent
 {\bf{Plugin Invocation:}} \\
 \\
 A valid example conditions data file is required. Then use the default way
 to invoke plugins:\\
 \tw{\$ > geoPluginRun\ \textrm{-}destroy  \ \ \ \char`\\} \\
 \tw{\hspace{3cm} \textrm{-}plugin\ DD4hep\_ConditionExample\_manual\_load \ \ \ \char`\\} \\
 \tw{\hspace{3cm} \textrm{-}input\ file:\$\{DD4hep\_DIR\}/examples/AlignDet/compact/Telescope.xml
     \ \ \ \char`\\} \\
 \tw{\hspace{3cm} \textrm{-}conditions\ Conditions.root\ \textrm{-}runs\ 10}
 
 
 \vspace{0.6cm}
 
 \noindent
 {\bf{Example Code:}} \\
 
 \begin{code}
   int          num_run    = <number of condition loads>;
   const string conditions = <conditions file name>;
   const string geometry   = <geometry compact xml description";
 
   description.fromXML(geometry);
   description.apply("DD4hep_ConditionsManagerInstaller",0,(char**)0);
 
   ConditionsManager manager = ConditionsManager::from(description);
   manager["PoolType"]       = "DD4hep_ConditionsLinearPool";
   manager["UserPoolType"]   = "DD4hep_ConditionsMapUserPool";
   manager["UpdatePoolType"] = "DD4hep_ConditionsLinearUpdatePool";
   manager["LoaderType"]     = "root";
   manager.initialize();
 
   shared_ptr<ConditionsContent> content(new ConditionsContent());
   shared_ptr<ConditionsSlice>   slice(new ConditionsSlice(manager,content));
 
   Scanner(ConditionsKeys(*content,INFO),description.world());
   Scanner(ConditionsDependencyCreator(*content,DEBUG),description.world());
 
   const IOVType* iov_typ = manager.iovType("run");
   for ( int irun=0; irun < num_runs; ++irun )  {
     IOV iov(iov_typ,irun*10+5);
     ConditionsManager::Result r = manager.prepare(iov,*slice);
     if ( r.missing != 0 )  {
        except("Example", 
               "Conditions prepare step for IOV %s FAILED. There are %ld missing conditions.",
               r.missing, iov.str().c_str());
     }
     Scanner(ConditionsPrinter(slice.get(),"Example"),description.world());
   }
 \end{code}
 
 \noindent
 {\bf{Explanation:}} \\
 \begin{tabular} {l||p{0cm}}
 \docline{Line}{}
 \docline{1-3}{Definition of processing parameters.}
 \docline{5}{Load the detector description using the compact notation.}
 \docline{6}{Install the conditions manager implementation using the plugin mechanism.}
 \docline{8}{Access conditions manager instance from the Detector interface.}
 \docline{9-12}{Configure the properties of the conditions manager.}
 \docline{13}{Initialize the conditions manager instance.}
 \docline{15-16}{Create an empty $ConditionsSlice$ instance the container with 
                 the desired conditions content.}
 \docline{18-19}{This is example specific and only a shortcut to fill the 
              required conditions content and the derivation rules.\\
              In real life this would be intrinsic to the experiment's 
              data processing framework.}
 \docline{18}{Populate the $ConditionsContent$ instance with the addresses (keys) 
              of the conditions required:
              We scan the $DetElement$ hierarchy and add a couple of conditions
              for each $DetElement$}
 \docline{19}{Add for each $DetElement$ 3 derived conditions,
              which all depend on the persistent condition derived\_data.\\
              In the real world this would be very specific derived actions.}
 
 \docline{22-31}{Emulate a pseudo event loop: Our conditions are of type "run".}
 \docline{23}{This is the IOV we want to use for this "processing step". 
             The conditions filled into the slice during the prepare step will 
             satisfy this IOV requirement.}
 \docline{24}{Conditions prepare step. Select the proper set of conditions 
             from the store (or load them if needed). Attach the selected 
             conditions to the user pool.}
 \docline{25-29}{Check the result of the prepare step. If anything would be missing,
             the parameter r.missing of the return code would be non-zero.}
 \docline{30}{Emulate data processing algorithms: Here we only scan the 
             $DetElement$ tree and print all conditions.\\
             We know what we expect since we defined the content the same way!
             In the printer we can access the conditions directly from the slice,
             since the slice implements the $ConditionsMap$ interface.}
 \end{tabular}
 
 \newpage
 %=============================================================================
 \begin{thebibliography}{9}
 \bibitem{bib:dd4hep-manual}  M.Frank, \DDH manual.
 \bibitem{bib:ddalign-manual}  M.Frank, \DDA manual.
 \end{thebibliography}
 %=============================================================================
 \end{document}

This page was automatically generated by the 2.3.7 LXR engine. The LXR team