Hi Hiro et al, This mail is rather long, but I strongly encourage people to read it through, since it outlines the BRAT design, and being familiar with that, you/we may avoid major headaches in the long run. On Wed, 14 Mar 2001 13:29:25 -0600 (CST) Hironori Ito <hito@students.phsx.ukans.edu> wrote concerning ": Convention": > Hello. I have a question and a request to BRAT authority people. > > What are the clear definitions of Rdo and Module??? Is this > mentioned somewhere in Brahms software page??? If not, can you write this > in the web page with very clear example? (The statement like "See > BrRdoModuleBB" is not a "Clear" example.) I want BrRdo and BrRdoMoudle > for Dummies if possible. Let me try and answer this is some general terms, however a bit brief. In BRAT, we have 4 groups of classes: * Data classes * Modules * Managers * Utilities Data classes: ============= This contain nothing but data, and have methods to retrive and set that data (Getters and Setters). In other words, they should not have methods that maniplulate the internal data members (exceptions being something like calculating the length of a vector and the like). We have, with varying success, tried to split this into further sub types: * Digits - Representation of raw data. * Rdo - Reduced data object, essentially calibrated digits. * Calibrations - gains, pedestals, etc. * Geometry - dimensions, positions, etc. * Containers - These are collections of any of the above. In case of detector data (digits and Rdo's) this are the classes BrEventNode (_not_ BrEvent) and BrDataTable (BrClonesArray is depreciated for now). Other kinds of data is usually managed by some manager, and the internal containers my be any ROOT TCollection. I may have left out something here, but I hope you get the general picture. Streamers and class version: ---------------------------- Data classes _must_ have a class version greater than zero. Also, when specifing the linkage for CINT (in LinkDef.h file), it should have byte-counting enabled (append a "+" to the class name), so that we may use ROOT's automatic schema evolution. Modules: ======== These classes are the work-horses of BRAT. They manipulate data, that is, they map one data set into another in some way. For example we have some modules that map digits into Rdo's (generally known as Rdo modules). Modules does not in themselves have any data what so ever, except internal parameters for the algorithms to work. They depend entirely on input and external managers for thier input. Therefore, if a given module must have some input data, say a primary vertex z--coordinate, it should look for that in the input (the BrEventNode it is passed in the Event method). Such data _may_not_be_set_by_auxilary_methods_!!! So a module may have some parameter like Int_t fMaxIterations, but should _never_ have a member like BrDataTable* fTracks. Also, modules _must_ conform to the interface defined by BrModule, that is it can define the methods: DefineHistograms() Init() Begin() Event(BrEventNode* , BrEventNode*) End() Finish() Print(Option_t* option="B") and Setters for internal algorithm parameters e.g., SetMaxIterations(Int_t) Other public methods are _not_ allowed. If, for logical reasons, one of the methods above should be split into more methods, these methods should be in protected scope and virtual ofcourse. For example protected: virtual void FirstThingsFirst(...); virtual void DoOurThing(...); virtual void CheckHowWeAreDoing(...); public: virtual Event(BrEventNode*, BrEventNode*) { FirstThingsFirst(...); DoOurThing(...); CheckHowWeAreDoing(...); Making the submethods protected insures that the casual user doesn't try to use them, and that they can still be overloaded by derived classes. Special Modules: ---------------- There are special kinds of modules: * Filters - selects specific events * Contianers - Container of modules. A container will recursively send apropiate messages to contained module _in_the_order_they_were_added_ * Packages - Specialised containers. A package will contain a specific set of modules appropiate for a set of tasks. For example, I've made a package called GlbPackage, which makes Rdo data from digit data for all (almost) global detectors. You can find it in my "brahms_app" area in subdirectory "jobs". Another example of apackage, could be a tracking package for a TPC, which would contain a cluster, deconvelution, and tracking module. Streamers and class version: ---------------------------- Modules _must_ have a class version of ZERO. They are not meant to be persistent (stored on disk), and providing that service is a breach of concept and will lead to many headaches (as experience have shown). Managers: ========= Managers manages data that is used by many modules to insure referential integrity (the modules use the same values). Managers are always singletons, that is, there may only exist one instance of a given manager. It's hard to give a generic interface to managers, but it should provide a "global" methods to get a hold of the instance. The convention is to use a static Instance() returning the static member fgInstance. class BrMyManager { private: static BrMyManager* fgInstance; ... public: static BrMyManager* Instance() { return fgInstance; } ... }; Examples of managers in BRAT includes: BrParameterElementManager BrRunInfoManager BrAppOptionManager BrGeometryDbManager Streamers and class version: ---------------------------- Managers _must_ have a class version of ZERO. They are not meant to be persistent (stored on disk), and providing that service is a breach of concept and will lead to many headaches (as experience have shown). Utility classes: ================ These classes provide a number of services that doesn't naturally fall into any of the above groups. This should be the smallest of all of the groups!!! Currently, it includes classes like BrMaths BrUnits BrVector BrPlane BrLine Naming Conventions: =================== Class named should always start with Br (Not KO, or something like that), followed by the fully qualified data type, and then ending in which group it belongs to. A fully qualified data type name consist of the detector system name followed by the data subtype. Group name is one of the the four listed above, with the exception that "Data" is never appended in case of the first group. So if I want to make a class that contains Rdo data for the TMA, then I should start with Br Then append the detector system BrTile Then the data sub-type BrTileRdo and since this is a data class I do not append "Data". If I want to make a module that makes BrTileRdo objects, I'll append Module to the above and get BrTileRdoModule Similarly, I can build other class names, to get for example BrTpcHit BrTpcHitModule BrTpcTrack BrTpcTrackModule BrBbRdo BrBbRdoModule If I wanr to make a vertex filter, I start with Br append Vertex (The data type) and then Filter (group), to get BrVertexFilter If I want to make a package for TPC tracking I get BrTpcTrackPackage A manager for calibration data would be named BrCalibrationManager and a calibration class for the hodoscopes would be named BrTofCalibration and so on. To be a bit more precise, I provide the following BNF: <class name> ::= Br<type><qualifed data type><qualifed group> <type> ::= <detector> | /* special: In case it a base class */ <qualifed data type> ::= <data type> | Db <data type> <data type> ::= Rdo | Digit | Calibrations | Geometry | Hit | Track <qualifed group> ::= Cal <group> | <group> <group> ::= Module | Package | Filter | ModuleContainer /* special */ | /* special: data is not appended for data classes */ I hope that answers Hiro's question. For some time now, I've had a draft of a TDR for BRAT lying around, but it'll take some time before it hits the general collaboration - sorry, so much to do so little time. Yours, Christian ----------------------------------------------------------- Holm Christensen Phone: (+45) 35 35 96 91 Sankt Hansgade 23, 1. th. Office: (+45) 353 25 305 DK-2200 Copenhagen N Web: www.nbi.dk/~cholm Denmark Email: cholm@nbi.dk
This archive was generated by hypermail 2b29 : Thu Mar 15 2001 - 07:42:18 EST