1bbeea79a197338654319c16d88d9b27bf07b0c9
[u/mrichter/AliRoot.git] / MUON / READMEshuttle.txt
1 // $Id$
2
3 /*! 
4
5 \page README_shuttle Shuttle 
6
7 How to test the Shuttle preprocessor(s) for MUON.
8
9 We will get two "logical" MUON preprocessors : one for the tracker and one for the trigger.
10 Both will manage several subtasks (e.g. the tracker one will handle pedestals,
11  gains and deadchannels, while the trigger one will handle masks and trigger lut)
12 "Physically", only one class will manage both the tracker and the trigger : AliMUONPreprocessor.
13 Depending on the subsystem and on the task to be performed (based on the run type), this class
14  will instanciate the correct set of AliMUONVSubProcessor(s) which does the actual job.
15 Output of most processors will end up in OCDB (Offine Condition DataBase). A set of helper functions
16  to peek at this OCDB are gathered in AiMUONCDB class.
17  
18
19 \section shuttle_s1 TestMUONPreprocessor.C
20
21 This is the master macro used to check the MUON part of the Shuttle.
22 Depending on what you want to test, you'll have to modify the input files 
23 (using shuttle->AddInputFile) and/or the run type (using shuttle->AddInputRunParameter())
24
25
26 \section shuttle_s2 AliMUONPreprocessor(const TString& detName)
27
28 Depending on how this one is constructed, and depending on the runtype, it will
29  perform differents tasks. Note that for the moment the runtypes are "fake", i.e.
30  put by hand in the TestMUONPreprocessor.C macro, and might not correspond to
31  the final values to be used by the DAQ.
32
33 <pre> 
34 detName   runType                     task to be done           worker class (AliMUONVSubprocessor child)
35 --------------------------------------------------------------------------------------------------------
36 MCH       PEDESTAL                    read ASCII ped files      AliMUONPedestalSubprocessor
37                                       and put them into OCDB
38                         
39 MCH       GMS                         read GMS alignment files  AliMUONGMSSubprocessor
40                                       and put them into OCDB
41
42 MCH       PHYSICS                     read DCS HV values and    AliMUONHVSubprocessor
43                                       put them into OCDB
44                                       
45 MCH       CALIBRATION                 read ASCII gain files     AliMUONGainSubprocessor
46                                       and put them into OCDB
47
48 MTR       CALIBRATION                 read date files (masks,   AliMUONTriggerSubprocessor
49                                       crates, and LUT)
50                                       and put them in OCDB           
51                                       
52 MTR       PHYSICS                     read date files as in     AliMUONTriggerDCSSubprocessor
53                                       CALIBRATION,
54                                       read DCS HV and currents
55                                       and put them in OCDB
56                                      
57 </pre>
58
59
60 \section shuttle_s3 Pedestals
61
62 Two options here. You can either use a pre-done set of ASCII pedestals files (generated as
63  explained below for the 2nd option), located at /afs/cern.ch/user/l/laphecet/public/LDC*.ped, 
64  or build you own set.
65  
66 We've written an AliMUONPedestalEventGenerator which creates fake pedestal events. The pedestal values
67 are taken from the Offline Condition DataBase (OCDB) (which is itself fakely filled
68 using the WritePedestals() method of AliMUONCDB class
69
70 So first generate a valid pedestal CDB entry by using the AliMUONCDB class. There's one
71  little trick : you should first point to the "default" OCDB (local://$ALICE_ROOT) in
72  order to get the mapping loaded, then only you can play with another OCDB. 
73  Or, alternatively, you can put the mapping stuff in the test OCDB, like this :
74  
75 <pre>
76 root[] AliMpDDLStore::ReadData(); // read mapping from ASCII files
77 root[] const char* cdbpath="local://$ALICE_ROOT/SHUTTLE/TestShuttle/TestCDB"; // where to put the CDB
78 root[] AliCDBManager::Instance()->SetDefaultStorage(cdbpath);
79 root[] AliMpCDB::WriteMpSegmentation();
80 root[] AliMpCDB::WriteDDLStore();
81 </pre>
82
83 If you've not put the mapping in the test database, then you must start with the default OCDB, load the mapping, and then only switch to the 
84  test database :
85  
86 <pre>
87 root[] AliCDBManager::Instance()->SetDefaultStorage("local://$ALICE_ROOT"); // only if you've not put the mapping in test OCDB
88 root[] AliCDBManager::Instance()->SetRun(0); // only if you've not put the mapping in test OCDB
89 root[] AliMpCDB::LoadDDLStore(); // only if you've not put the mapping in test OCDB
90 // below are lines to be executed whatever you did with the mapping...
91 root[] const char* cdbpath="local://$ALICE_ROOT/SHUTTLE/TestShuttle/TestCDB"; // where to put the CDB
92 root[] AliMUONCDB cdb(cdbpath)
93 root[] Bool_t defaultValues = kFALSE; // to generate random values instead of plain zeros...
94 root[] Int_t startRun = 80;
95 root[] Int_t endRun = 80;
96 root[] cdb.WritePedestals(defaultValues, startRun, endRun);
97 </pre>
98
99 Expected output is (don't worry about the warnings, they are harmless) :
100
101 <pre>
102 I-AliMUONCDB::ManuList: Generating ManuList...
103 I-AliMUONCDB::ManuList: Manu List generated.
104 I-AliMUONCDB::MakePedestalStore: 16828 Manus and 1064008 channels.
105 I-AliMUONCDB::WritePedestals: Ngenerated = 1064008
106 I-AliCDBManager::Init: AliEn classes enabled in Root. AliCDBGrid factory registered.
107 I-AliCDBManager::SetDefaultStorage: Setting Default storage to: local://$ALICE_ROOT/SHUTTLE/TestShuttle/TestCDB
108 I-AliCDBLocal::PutEntry: CDB object stored into file ($ALICE_ROOT)/SHUTTLE/TestShuttle/TestCDB/MUON/Calib/Pedestals/Run80_80_v0_s0.root
109 </pre>
110
111 Then use the AliMUONPedestalEventGenerator to produce simulated pedestal events.
112
113 Usage (from the Root prompt) :
114 <pre>
115 AliMpCDB::LoadDDLStore2(); // load mapping from "default" OCDB=local://$ALICE_ROOT
116 AliCDBManager::Instance()->SetDefaultStorage(cdbpath); // so you will read 
117 // back pedestals values generated in the previous step
118 const char* dateFileName = "raw.date"; // base filename for the output
119 Int_t runNumber = 80; // run number used to fetch the pedestals from the OCDB 
120 Int_t nevents = 100; // # of events to generate. 100 should be enough
121 gSystem->Load("libMUONshuttle"); // needed or not depending on whether it's already loaded or not
122 AliMUONPedestalEventGenerator ped(runNumber,nevents,dateFileName);
123 ped.Exec("");
124 </pre>
125
126 It *will* take a lot of time (mainly due to the fact that we're writing a 
127 bunch of ASCII files = DDL files), so please be patient.
128
129 The output should be the normal simulated sequence of MUON.Hits.root, MUON.SDigits.root,
130  MUON.Digits.root, raw/*.ddl files and raw.date.LDCi where i=0-3 (i.e. one DATE file
131 per LDC, as will be used in real life), the latter ones being roughly 100 MB each.
132
133 // FIXME : instructions below should be replaced with usage of MUONTRKda
134 //
135
136 The raw.date.LDC* files are then processed using the DA online program (which is not built by default, but must be made
137  explicitely using make daqDA-MCH from $ALICE_ROOT, and requires some DATE setup..., see \ref READMEmchda.txt )
138  
139 <pre>
140  MUONTRKda.exe -f raw.date.LCDi -a LDCi.ped (i=0,1,2,3)
141  
142  (repeat for each LDC)
143 </pre>
144
145 The LDCi.ped files are the input for the pedestal subprocessor,
146 which is tested using the TestMUONPreprocessor.C macro. 
147 The output of the pedestal subprocessor (upon success only) is written into the OCDB. 
148 Difference between the input and the output can be inferred using the diff() function
149 of MUONCDB.C macro.
150
151
152 \section shuttle_s4 Gains
153
154 Like pedestals, you have two options here. You can either use a pre-done set of 
155 ASCII gain files (generated as explained below for the 2nd option), 
156 located at /afs/cern.ch/user/l/laphecet/public/LDC*.gains,  or build you own set.
157  
158 We've written an AliMUONGainEventGenerator which creates fake gain events. 
159 The pedestal and gain values are taken from the Offline Condition DataBase (OCDB)
160  (which is itself fakely filled using the WritePedestals() and WriteGains() 
161  methods of AliMUONCDB class).
162
163 So first you need to generate a valid pedestal CDB entry and a valid gain CDB 
164 entry by using the AliMUONCDB class, from the Root prompt:
165
166 <pre>
167 const char* cdbpath="local://$ALICE_ROOT/SHUTTLE/TestShuttle/TestCDB"; // where to put the CDB
168 AliMUONCDB cdb(cdbpath)
169 Bool_t defaultValues = kFALSE; // to generate random values instead of plain zeros...
170 Int_t gainRun = 80;
171 Int_t pedRun = 81;
172 cdb.WritePedestals(defaultValues, pedRun, pedRun);
173 cdb.WriteGains(defaultValues, gainRun, gainRun);
174 </pre>
175
176 Expected output is (don't worry about the warnings, they are harmless) :
177
178 Then use the AliMUONGainEventGenerator to produce simulated gain events : the output 
179 will be n x 4 date files (n is the number of fake injections, currently 9, and 4
180  is the number of LDCs)
181
182 Usage (again, from the Root prompt) :
183
184 <pre>
185 const char* cdbpath="local://$ALICE_ROOT/SHUTTLE/TestShuttle/TestCDB"; // where to get the CDB
186 AliCDBManager::Instance()->SetDefaultStorage(cdbpath); // so you will read 
187 // back pedestals and gain values generated in the previous step
188 const char* dateFileName = "raw.date"; // base filename for the output
189 Int_t gainRunNumber = 80; // run number used to fetch gains from OCDB
190 Int_t pedRunNumber = 81; // run number used to fetch the pedestals from the OCDB 
191 // generated ped files will be for r = 81, 83, etc...
192 Int_t nevents = 100; // # of events to generate. 100 should be enough for testing, but 1000 would be better for prod
193 gSystem->Load("libMUONshuttle"); // needed or not depending on whether it's already loaded or not
194 AliMUONGainEventGenerator g(gainRunNumber,pedRunNumber,nevents,dateFileName);
195 g.Exec("");
196 </pre>
197
198 It *will* take a lot of time (mainly due to the fact that we're writing a 
199 bunch of ASCII files = DDL files), so please be patient.
200
201 The output should be a sequence of directories, RUN81, RUN82, etc..., each 
202 containing the normal simulated sequence of MUON.Hits.root, MUON.SDigits.root,
203  MUON.Digits.root, raw/*.ddl files and raw.date.LDCi where i=0-3 (i.e. one DATE file
204 per LDC, as will be used in real life), the latter ones being roughly 100 MB each.
205
206 <pre>
207 // FIXME
208 // Below should follow instructions on how to feed the MUONTRKda with the
209 // generated files.
210 </pre>
211
212
213 \section shuttle_s5 HV
214
215 HV DCS values are created in CreateDCSAliasMap() of TestMUONPreprocessor.C
216 You might want to modify this function to create a given set of error conditions
217  in order to test whether the HVSubprocessor is reacting properly to those errors.
218
219
220 \section shuttle_s6 GMS
221
222 The GMS alignment data for testing can be generated with
223 the macro MUONGenerateTestGMS.C:
224 The matrices of TGeoHMatrix type, with TObject::fUniqueID equal to the geometry
225 module Id, are put in a TClonesArray and saved in the Root file with a 
226 key "GMSarray".
227
228
229 \section shuttle_s7 Trigger DCS
230
231 HV and currents DCS values are created in CreateDCSAliasMap() of TestMUONPreprocessor.C
232 As done in Tracker HV, you might want to modify this function to create a given set of 
233 error conditions in order to test whether the TriggerDCSSubprocessor is reacting 
234 properly to those errors.
235
236 COMMENT: the trigger subprocessor requires trigger .dat files to be present.
237 In order to test only the DCS values when the remaining trigger files are not present, 
238 a workaround is put in the TestMUONPreprocessor.C which creates fake date files.
239 This results in some "ERROR" flags appearing in the LOG file (for masks and LUT), 
240 which are absolutely expected.
241 The fake date files are automatically removed at the end of the macro.
242
243
244 This chapter is defined in the READMEshuttle.txt file.
245
246 */
247