Project

General

Profile

Product Mixing » History » Version 3

Christopher Green, 10/26/2011 08:26 PM

1 1 Christopher Green
h1. Product Mixing
2 1 Christopher Green
3 1 Christopher Green
h2. Overview.
4 1 Christopher Green
5 1 Christopher Green
*Product Mixing* is our label for the ability to take a feed from a source of secondary events, and combine the products (usually collections) from multiple events into a single product or collection to be placed in the primary event. The motivation is of course obvious: background (eg cosmic) events or pile-up.
6 1 Christopher Green
7 1 Christopher Green
This feature is implemented by providing a module template, @MixFilter@ as a skeleton to handle the low-level interaction with the primary event and secondary files, including the collection of multiple products from different secondary events and the registration of outgoing products. The user must provide a "detail" class implementation which has some mandatory and some optional members in order to register necessary products at the right time and mix the prepared groups of incoming products. The @MixFilter@ will take care of reading the secondary data, either sequentially or randomly and cycling through multiple secondary input files as necessary.
8 1 Christopher Green
9 1 Christopher Green
In order to make the mixing task easier, we have provided several auxiliary utilities which will be described later.
10 1 Christopher Green
11 1 Christopher Green
In summary, the MixFilter module will do the following tasks:
12 1 Christopher Green
13 1 Christopher Green
# Construct a @MixHelper@ object for use by the user's detail class, hereafter referred to as @Detail@ (class) or @detail@ (object).
14 1 Christopher Green
# Construct @detail@, passing the helper and the module's parameter set. At this point, @detail@ should register any mix operations (one per product to be mixed) using @MixHelper::declareMixOp<>()@, and any non-mixing products to go in to the event (e.g. bookkeeping objects) using @MixHelper::produces<>()@.
15 1 Christopher Green
# For each primary event:
16 1 Christopher Green
## Call the optional @Detail::startEvent()@ function if it exists so @detail@ can position itself for the coming event.
17 1 Christopher Green
## Call @Detail::nSecondaries()@ to decide how many secondary events to read.
18 1 Christopher Green
## Decide which secondary events are to be read.
19 1 Christopher Green
## Call the optional @Detail::processEventIDs()@ function in case the Detail class is interested in the sequence of event IDs (e.g. for bookkeeping purposes).
20 1 Christopher Green
## Call the registered mixing operation for each product to be mixed, providing the secondary data to be mixed and putting the resultant mixed product into the primary event.
21 1 Christopher Green
## Call the optional @Detail::finalizeEvent()@ function to tidy up and possibly put any bookkeeping products (registered with @MixHelper::produces<>()@) into the primary event.
22 1 Christopher Green
23 1 Christopher Green
The @MixFilter@ module will take care of opening new secondary files as necessary, and will additionally call an optional function @Detail::eventsToSkip()@ as each file is opened (in sequential mode only) if it is desired to have a particular offset into each file to insure against coherent backgrounds in events.
24 1 Christopher Green
25 2 Christopher Green
h2. Mix operations: what are they and what do they need to do?
26 2 Christopher Green
27 3 Christopher Green
A mix operation is a function provided by the user which returns a @bool@ and expects three arguments:
28 3 Christopher Green
29 3 Christopher Green
* @vector<PROD const *> const &@ containing the secondary products to be mixed;
30 3 Christopher Green
* @PROD &@, the output product to be filled by the mix function; and
31 3 Christopher Green
* @PtrRemapper const &@, a helper for use remapping @Ptr@ and friends (see below).
32 3 Christopher Green
33 3 Christopher Green
It may be a free function, a member function of @Detail@ or some other user class, or a function object ("functor") whose @operator()@ has the correct signature. It is supposed to use the information contained in the secondary products to fill the output product, using the @PtrRemapper@ if necessary, and return a @bool@ indicating whether the output product should be placed in the event.
34 3 Christopher Green
35 3 Christopher Green
All mix operations must be declared _at construction time_ by @detail@, using the @MixHelper@ provided as a constructor argument.
36 3 Christopher Green
37 1 Christopher Green
h2. Mandatory interface for @Detail@.
38 1 Christopher Green
39 3 Christopher Green
h3. Constructor.
40 3 Christopher Green
41 3 Christopher Green
<pre><code class="cplusplus">Detail(fhicl::ParameterSet const & ps, art::MixHelper & helper);</code></pre>
42 3 Christopher Green
43 3 Christopher Green
h3. @nSecondaries()@.
44 3 Christopher Green
45 3 Christopher Green
<pre><code class="cplusplus">size_t nSecondaries();</code></pre>
46 3 Christopher Green
47 1 Christopher Green
h2. Optional interface for @Detail@.
48 3 Christopher Green
49 3 Christopher Green
h3. @startEvent()@.
50 3 Christopher Green
51 3 Christopher Green
<pre><code class="cplusplus">void startEvent(art::Event const & evt);</code></pre>
52 3 Christopher Green
53 3 Christopher Green
h3. @eventsToSkip()@.
54 3 Christopher Green
55 3 Christopher Green
<pre><code class="cplusplus">size_t eventsToSkip();</code></pre>
56 3 Christopher Green
57 3 Christopher Green
h3. @processEventIDs()@.
58 3 Christopher Green
59 3 Christopher Green
<pre><code class="cplusplus">void processEventIDs(art::EventIDSequence const & seq);</code></pre>
60 3 Christopher Green
61 3 Christopher Green
h3. @finalizeEvent()@.
62 3 Christopher Green
63 3 Christopher Green
<pre><code class="cplusplus">void finalizeEvent(art::Event & evt);</code></pre>
64 1 Christopher Green
65 1 Christopher Green
h2. Helper utilities.
66 1 Christopher Green
67 1 Christopher Green
h3. @MixHelper@.
68 1 Christopher Green
69 1 Christopher Green
h3. @CollectionUtilities.h@: @concatContainers()@ and @flattenCollections()@.
70 1 Christopher Green
71 1 Christopher Green
h3. @PtrRemapper@.