001 Full information on CLHEP is available on the WEB:
002
003 http://wwwinfo.cern.ch/asd/lhc++/clhep/index.html
004
005 Below is contents of the old README
006
007 -------------------------------------------------------------------------
008
009 Latest news
010 ===========
011
012 *** May 15. 1997 by Nobu Katayama ***
013
014 CLHEP is now very close to Version 1.0 as defined at the May 96 workshop.
015 We have new Random, Geometry (3D) and Units from Geant4 team. It now compiles
016 on HP, SGI, IBM(AIX), DEC(OSF1), SUN(Solaris) and PC(linux) with native and
017 GNU compilers. Tests run on all platforms, except that on DEC with cxx 5.3/4
018 the original testString gives a coredump. Randlux in testRandom gives
019 different results on different platform and testRandom goes into an infinite
020 loop on PC(linux). I am sure these Random problems will be fixed soon.
021 Another pending issue is Babar point/translateion/transformation need to be
022 merged into the new Geometry classes. I am sure we can put Babar's
023 functionalities into Evgueni's classes. The new Histogram classes will be
024 in sometime in June. That's it for now.
025
026 introduction
027 ============
028
029 This directory contains a few utility classes which represents what I
030 would like to have in a future Class Library for High Energy Physics.
031 Most of them have been taken out of a draft version of the MC++ Event
032 Generator toolkit, hence they may contain some special features which
033 are not suitable for a general class library.
034
035 The classes are to be a starting point for discussions on what should
036 be in a High Energy Physics Class Library and what should not. And I am
037 looking forward to many good discussions on the net in the near future.
038
039 This distribution also contains two subdirectories containing code
040 which for the moment isn't quite "supported". You are nevertheless
041 strongly encouraged to look at this code and send your opinions to
042 hepnet.lang.c++ as it might become a permanent part of CLHEP in a near
043 future.
044
045 The vmp sub-directory has been taken out of the CLHEP distribution. It
046 is available from the "The HEP Experimental Code Catalog"
047 (http://afal01.cern.ch/C++/Catalog/Catalog.html) or with anonymous ftp
048 from ftp://cithe501.cithep.caltech.edu/pub/sushi/vmp-2.0.tar.Z or
049 ftp://freehep.scri.fsu.edu/freehep/C++/vmp/vmp-2.0.tar.Z.
050
051 The bfast subdirectory has also been taken out of the CLHEP
052 distribution. It is available from the "The HEP Experimental
053 Code Catalog" (http://afal01.cern.ch/C++/Catalog/Catalog.html).
054
055
056 Description
057 ===========
058
059 The following classes are included in this distribution:
060
061 HepAList (AList.h) is a template-based list class developed from a
062 non-template list class written by Dag Bruck.
063
064 HepAListIterator (AIterator.h) is a template based list iterator
065 class for AList and was also developed from a non-template version
066 written by Dag Bruck.
067
068 Note that HepAList<T> is implemented as a array of pointers to T. Hence only
069 references and pointers to objects are stored - not the objects themselves.
070 It might be better to let HepAList<T> implement an array of class T, however
071 then you would loose the polymorfism when adding objects of a sub class of T.
072 I have found that I mostly want to keep the polymorfism of objects put in a
073 list, but I think this issue should be discussed carefully.
074
075 HepConstAList and HepConstAListIterator (ConstAList.h and ConstAIterrator.h)
076 are a variation of the classes above for storing pointers to const objects.
077
078 HepString (Strings.h) is a simple character string class. Again a
079 slightly modified version of a class written by Dag Bruck.
080
081 According to Dag Bruck (member of the C++ standardization committee), the
082 future standard will include a character string class, so we should adopt
083 the specifications for that class as soon as they are available.
084
085 Hep3VectorF and Hep3VectorD (ThreeVector.h) are two three-
086 vector classes with float and double components respectively. I have
087 tried to design them so that the double and float versions can be
088 intermixed freely, just as the double and float built in types.
089
090 HepRotation (Rotation.h Rotation.cc) is a 3 by 3 matrix class for
091 rotation of three-vectors. Simple rotations of three-vectors can
092 however be made without using this class to save time.
093
094 HepLorentzVectorF and HepLorentzVectorD (LorentzVector.h)
095 are two Lorentz vector classes with float and double components respectively
096 and are sub-classes of the Hep3VectorF and Hep3VectorD classes.
097
098 HepLorentzRotation (LorentzRotation.h) is a 4 by 4 matrix class for
099 Lorentz rotation of Lorentz vectors. It is a private sub-class of the
100 Rotation class for easy implementation of pure 3-d rotations but
101 preventing boosting of three-vectors with strange results.
102
103 When writing MC++ I realized the problem that some users wants double
104 precision Lorentz vectors to avoid problems with large boosts and
105 others need to have them in single precision to save space. Therefore
106 I have introduced a couple of typedefs which by default looks like this
107
108 typedef double Float;
109 typedef Hep3VectorD Hep3Vector;
110 typedef HepLorentzVectorD HepLorentzVector;
111
112 but with a #define in the CLHEP.h file they are changed to
113
114 typedef float Float;
115 typedef Hep3VectorD Hep3Vector;
116 typedef HepLorentzVectorD HepLorentzVector;
117
118 In this way it is easier to write code using the class library and
119 still allow the end user to decide whether he wants single or double
120 precision.
121
122 HepRandom (Random.h) is a random number generator class capable of
123 generating pseudo random numbers according to different distributions.
124 The actual algorithm use by HepRandom is up to the user to decide. Any
125 algorithm implemented in a sub class of the abstract HepRandomEngine
126 (RandomEngine.h) class can be assigned to a HepRandom object. By
127 default the algorithm described in F. James, Comp. Phys. Comm. 60
128 (1990) 329. which is implemented in the HepJamesRandom
129 (JamesRandom.h) class.
130
131 HepCmdLine (CmdLine.h), HepCmdArg, HepCmdArgInt, HepCmdArgFloat
132 (CmdArg.h) etc. are used to handle command line arguments. HepCmdArg
133 and its subclasses are used to represent one command line argument,
134 either optional or positional. Optional arguments are those specified
135 just after the command with a '-'. Positional arguments occur after
136 all optional arguments. A set of HepCmdArg objects corresponding to
137 the allowed arguments to be given to a program is handled by an object
138 of the HepCmdLind class which parses the command line and assign
139 values to the HepCmdArg objects.
140
141 HepLockable (Lockable.h) is intended to be a (multiply inherited) base
142 class for objects which will be handled by a combinatoric engine. It
143 maintains an integer, which is used bit-by-bit for locks. When asked
144 to lock itself, HepLockable sets the appropriate bit and then asks all
145 its children to lock themselves with the same bit. When asked to
146 unlock, it does a similar process. A HepLockable is locked if any of
147 its bits are set, or if any of its children are locked.
148
149 HepLock (Lock.h) maintains a list of objects, and on demand, locks and
150 unlocks them. The locks are turned on/off immediately. When an object
151 is added, it is immediately locked if the lock is on. When an object
152 is removed, it is first unlocked (if needed). When the HepLock object
153 is deleted (or goes out of scope), its members are first unlocked (if
154 needed).
155
156 HepChooser (Chooser.h) is a combinatoric engine which uses locks (see
157 Lockable.h). A HepChooser can take between 1 and 6 lists of
158 objects. Then, the next() method or () operator will return the next
159 set of objects, or 0 if done. The set is returned as a pointer to a
160 HepAList.
161
162 HepCombiner (Combiner.h) is essentially the same as HepChooser, except
163 the results of next() or operator() is one object. The += operator are
164 used to combine a the objects returned from HepChooser into one. Also,
165 the child list of the combined object is built using the method
166 addChild().
167
168
169 HepMatrixD is an arbitrary matrix of doubles. HepVectorD is a column
170 vector. HepSymMatrixD is a symmetric matrix, and HepDiagMatrixD is a
171 diagonal matrix. There are also float variaties of these matrices;
172 replace the final 'D' with an 'F'. All the matrices are derived from
173 HepGenMatrixD, which provides a few virtual functions, particularly
174 those to determine the size of the matrix and those to access
175 individual elements. All the obvious operators between the different
176 matrices and with normal real numbers are implemented. Two element
177 access routines are provided: m(i,j) indexes from 1..N while m[i][j]
178 indexes from 0..(N-1). N.B. most of the methods (eg. sub()) start
179 indexing from 1. Many linear algebra algorithms are implemented,
180 included those using QR decomposition (methods/functions prefixed with
181 "qr_").
182
183 The classes HepTuple and HepHistogram are intended as virtual base
184 classes for any tuple or histogram class. The HepTupleManager class
185 can serve as base class for any collection of tuples and histogram,
186 for example, a set written to a file. The classes HBookXXX are
187 examples of real implementations of the tuple/histograms, using CERN's
188 HBOOK as the actual engine. Classes using hippoplotamus as a tuple
189 collector are available with that package.
190
191 Particle classes
192 ================
193
194 I have included a suggestion for a "HepBaseParticle" class. It
195 basically only contains virtual functions to be redefined in derived
196 classes. The methods should in some way reflect the maximum amount of
197 information one would like to access from a particle. (You may want to
198 include more information or think some of it is unnecessary - in that
199 case, let us know!) If everyone derived their base particle class from
200 this it should be easy to link different toolkits and applications
201 together - either you use inheritance and work with the methods
202 declared in HepBaseParticle or, if you want functionality better
203 suited for your purposes, you make a copy of the particles -
204 preferably with a copy constructor
205
206 class MyBaseParticle: public HepBaseParticle {
207 public:
208 MyBaseParticle(const HepBaseParticle & p);
209 /* ... */
210 };
211
212 Note that the HepBaseParticle class does not have any data members and
213 there is basically no overhead in deriving a 'special purpose'
214 particle class from it. Also if a derived class does not provide all
215 information defined by the virtual methods in HepBaseParticle, there
216 is no need to write 'dummy' methods for these as HepBaseParticle will
217 return sensible default values.
218
219 In the initial presentation of this HepBaseParticle suggestion in
220 hepnet.lang.c++, the class contained methods for accessing possible
221 measurement errors. After some discussion it became clear that the way
222 this was done wasn't very well thought through. It was suggested in
223 measurement errors should be implemented with covariance
224 matrices. Anyone willing to do this?
225
226 I have also included a class called "HepInterfaceParticle". It is
227 derived from HepBaseParticle and the only extension is that it
228 actually have data members corresponding to each member function. The
229 idea is that this class is to be used for communication between
230 different applications via the persistent streams. In this way eg. an
231 analysis program doesn't need to know about the actual classes used
232 when creating the particles but all information can still be
233 transmitted.
234
235 Object Persistency
236 ==================
237
238 HepPersistentBase (PersistentBase.h) is a abstract base class to be
239 used by any class hierarchy for achieving object persistent I/O. The
240 class has no data members, but declares a number of methods which has
241 to be implemented in the classes inheriting from it. Most of these
242 methods are very simple and can be declared and implemented using
243 simple macros.
244
245 HepPOStream and HepPIStream (POStream.h and POStream.h) are two
246 abstract base classes defining the procedure of writing and reading
247 objects persistently to and from streams. The two classes have three
248 classes each derived from them, implementing the actual output of data
249 to a stream in ASCII, binary and XDR format (POCharStream.h,
250 PICharStream.h, POBinStream.h, PIBinStream.h, POXdrStream.h,
251 PIXdrStream.h).
252
253 The main idea of the classes defining the object persistent I/O is to
254 be able to read and write complicated structures of pointers to
255 objects. Some of the features may seem kind of odd, and may be rather
256 special to what we need for MC++, and certainly the topic of object
257 persistency needs to be carefully discussed.
258
259 As an example of how to use the object persistent I/O, imagine we
260 have a program like MC++, with a "Factory" containing information
261 about particles and how they decay. A sample program may then look
262 like this:
263
264 int main() {
265
266 MC_Factory theFactory;
267 // create the factory
268
269 HepPICharStream input("MC++SavedFactory");
270 // open a persistent stream of ASCII characters reading from a file
271
272 input >> theFactory;
273 // read a factory previously saved to disc.
274
275 MC_GenericParticle * p;
276 // This is the base particle class in MC++ which inherits from
277 // HepBaseParticle
278
279 HepPOXdrStream output("|eventAnalysis");
280 // open a persistent stream of XDR records which pipes things to a program
281 // called eventAnalysis
282
283 for ( int ieve = 0; ieve < 10000; ieve++ ) {
284 p = theFactory.getParticle("e+e-collision");
285 // get a collision particle from the factory
286
287 p->decayAll();
288 // perform the decay of the collision, ie. generate an event.
289
290 HepInterfaceParticle * ip = new HepInterfaceParticle(*p);
291 // Copy the event tree to objects of the HepInterfaceParticle class
292
293 output << ip << flush;
294 // write out the event
295
296 delete p;
297 delete ip;
298 //delete all the particles in the event.
299 }
300
301 }
302
303 The corresponding analysis program would look something like this
304
305 int main () {
306
307 HepPIXdrStream input(cin);
308 // create a persistent stream and associate it with the standard input.
309
310 HepInterfaceParticle * ip;
311
312 while (input >> ip) {
313 // read an event
314
315 MyAnalysisParticle * p = new MyAnalysisParticle(*ip);
316 // Copy the event tree to objects of a class suitable for my analysis
317
318 analyse(p);
319 // analyse the event
320
321 delete p;
322 delete ip;
323 }
324 }
325
326 The way it works is that the persistent output stream keeps a list of
327 all objects that has been written out. If it is told to write out a
328 pointer to an object, it first checks if this object has been written
329 out before, in which case only a number corresponding to this object
330 is written, if not, the object is written out and associated with a
331 number for further output of pointers to it.
332
333 One problem arises when writing out a lot of events as in the example
334 above. It may very well happen that the 'p' points to the same space,
335 but the object stored there is completely different. Therefore the
336 output stream must be 'flushed' between each event, so that all
337 particles in the event is written out. However the particles contains
338 some pointers to objects within the Factory (to access information
339 from eg. the particle data table) and we don't want to write the whole
340 factory for every event. Therefore we 'save' the factory from being
341 flushed, using the save and noSave manipulators.
342
343 When reading the events in the analysis program everything works the
344 same. When a pointer to an object is to be read, the input stream
345 checks if this object has been read before in which case it just reads
346 a number and returns a pointer to the corresponding object. If it
347 hasn't been read before an object of the corresponding class is
348 created and is told to read itself from the stream, and is appended to
349 a list of read objects and a pointer to it is returned to the caller.
350 The input stream of course knows itself when to 'flush' the read
351 objects and which of the objects should be saved from flushing. Note
352 btw. that flushing doesn't mean that the objects are deleted. The
353 deletion is instead up to the caller to perform.
354
355 Note that the analysis program does not have to have knowledge about
356 all the classes that are written to the stream from the generator
357 program. If the input stream is set 'tolerant' as in the example
358 above, it is possible to read objects of subclasses of HepParticle
359 that hasn't been linked to the program. Even if the sub classes
360 contains pointers to objects not present in the base class which is
361 linked, the pointer structure of the written objects are maintained in
362 a reasonable way.
363
364 To inform the input stream of which classes are available there is a
365 procedure to 'register' a persistent class with a class called
366 HepDescriptionList (DescriptionList.h) which keeps a static list of
367 objects of the HepPersistentClassDescription (ClassDescription.h)
368 class. This is done automatically with the macros defined in
369 PersistentBase.h by creating a static instance of the
370 HepDescriptionList class providing information to create a
371 HepPersistentClassDescription object. Note however that it is very
372 important that the static list of descriptions in the HepDescription
373 list is created _before_ any instances of the class. To ensure this a
374 file called HepPIOInit.o must be the first object file to be loaded in
375 a program using persistent I/O. This is guaranteed to work, at least
376 in a UNIX environment using gcc-2.4.5.
377
378 The HepPersistentClassDescription objects may also provide some
379 information on how to dynamically link object files containing classes
380 that are specified in a stream but wasn't linked to the program from
381 the beginning. I'm however not really sure on how to actually do this,
382 but I have provided some hooks through the HepGenericLoader
383 (GenericLoader.h) class for future implementations of this procedure.
384
385 The persistent streams can also handle multiple inheritance. However
386 if an class inherits virtually from another class more than once, the
387 corresponding base class object will be written out more than once.
388
389 Coding Rules
390 ============
391
392 This version of CLHEP has been written to conform somewhat to the
393 rules and recommendations described in the paper "Programming in C++ -
394 Rules and Recommendations" written by Erik Nyquist and Mats Henricson
395 (obtainable from freehep in the file
396 freehep.scri.fsu.edu:hep-projects/CLHEP/c++.rules.ps). Not all of the
397 rules are followed however.
398
399 All global names are prefixed with "Hep" and all macros (except the
400 multiple includes preventive ones) are prefixed with "HEP_". If the
401 HEP_SHORT_NAMES macro is defined, a set of aliases for the global
402 names are defined in each header file (using typedef's and
403 define's. These aliases are usually just the full name without the
404 prefix "Hep". Note that the ANSI/ISO standard will include a namespace
405 operator which will make this procedure obsolete.
406
407 The classdoc program
408 ====================
409
410 All the header files in this distribution are written to be easily
411 converted to a unix-style manual page by the classdoc program written
412 by Dag Bruck. I think that this program provides a very easy-to-use
413 class documentation - simply write the code and put in comments where
414 you usually would put them (there are of course also a few small
415 tricks you can use to get nicer output) and classdoc will do the
416 rest.
417
418 Installation
419 ============
420
421 To test and install the library, run the script 'configure', this
422 script tries to guess e.g. what compilers you are using and then it
423 creates the make files. Note that you can by-pass the choices made by
424 the configure script by setting environment variables: set CXX to the
425 C++ compiler you want, 'FC' to the fortran compiler, 'INCLUDES' to the
426 directories you want to be searched for include files and 'LIBS' to
427 the libraries you want to link. Edit the top Makefile to make further
428 changes for your system. Then do a 'make check' to compile the
429 library and to run a couple of test programs. If all the tests pass
430 you may install the library file and the header files by doing 'make
431 install'. If you want to look at the classdoc program, do 'make
432 classdoc' and try it out by eg. 'classdoc AList.h'. If you want to
433 install classdoc, do 'make install_classdoc'. You may also install
434 the classdoc-processed header files as man-pages by doing 'make
435 install_manpages'. 'make install_all' will do all the installation for
436 you in one go.
437
438 Note that if you run configure with the option
439 '--disable-persistent-streams' all usage of persistent streams is
440 disabled in CLHEP. The persistent streams rely heavily on templates
441 and some compilers therefore chokes on this code. If your compiler
442 fails to compile and test CLHEP you should re-run configure with this
443 option and try again.
444
445 The code should in principle run on any platform with gcc-2.6.1 or
446 later but has only been tested on the following platforms:
447
448 SparcStation (SunOS ans Solaris 2) with gcc-2.6.3 and libg++-2.6. No
449 problem.
450
451 Silicon Graphics iris4d with gcc-2.6.3 and libg++-2.6. No problem.
452
453 DEC alpha OSF/1 2.0 with the DEC C++ compiler. Some problems with the
454 system header files - see below.
455
456 Previous versions of the code has been compiled and may still work
457 on the following platforms:
458
459 HP 9000/730 with gcc-2.4.5 and libg++-2.4.
460
461 NeXTStation with gcc-2.3.1 and libg++-2.3.
462
463 IBM RS6000 with gcc-2.3.3 and libg++-2.3. Problems with the linker - see below
464
465 DECstation 3100 with the DEC C++ compiler. Problems with the system
466 header files - see below.
467
468 DECstation 3100 with gcc-2.5.8 and libg++-2.5.3. No problem.
469
470 Bug reports and discussions
471 ===========================
472
473 If you have any comments, suggestions etc. please post a message to the
474 hepnet.lang.c++ news group.
475
476 Problems
477 ========
478
479 * Older CFront based compilers cannot handle the persistent
480 streams. This means that some test programs will fail. In the coming
481 versions of CLHEP the persistent streams will be therefore optional.
482
483 * Older versions of libg++ (2.2 and older) doesn't seem to have the file
484 stdiostream.h included. To fix this, either get version 2.3 of libg++
485 or create a file called stdiostream.h with the following contents:
486
487 #ifndef STDIOSTREAM_H
488 #define STDIOSTREAM_H
489 #include <stdio.h>
490 #include <fstream.h>
491
492 class stdiobuf: public filebuf {
493 public:
494 inline stdiobuf(FILE * filedesc): filebuf(fileno(filedesc)) {}
495 };
496
497 #endif
498
499 This should work, at least for the persistent streams in CLHEP.
500
501 * The DEC C++ compiler has some problem finding the definition of some
502 overloaded operators. The CLHEP sources has been modified sligthly for
503 this reason. It may look kind of ugly but it seems to work now.
504
505 * The Silicin Graphics compiler can't handle the templated overloading
506
507 template <class T>
508 HepPOStream & operator>> (HepPOStream &, T *& );
509
510 If anybody has an explanation to this I'm interested to hear it.
511
512 * On some machines, the "xdr.h" does not have function prototypes. If
513 so, you have to edit this file to compile CLHEP. (No don't edit the
514 system header - edit a copy of it and make sure this copy is included
515 instead of the original one). The easiest thing to do is to insert
516 ellipsis arguments in the definition of the functions called. The
517 definitions that has to be changed should look something like this:
518
519 extern void xdrmem_create(...);
520 extern bool_t xdr_float(...);
521 extern bool_t xdr_double(...);
522 extern bool_t xdr_char(...);
523 extern bool_t xdr_u_char(...);
524 extern bool_t xdr_string(...);
525 extern bool_t xdr_int(...);
526 extern bool_t xdr_u_int(...);
527 extern bool_t xdr_long(...);
528 extern bool_t xdr_u_long(...);
529 extern bool_t xdr_short(...);
530 extern bool_t xdr_u_short(...);
531 typedef bool_t (*xdrproc_t)(...);
532
533 and in the definition of 'struct XDR' the member x_setpostn should
534 look something like:
535
536 bool_t (*x_setpostn)(...);
537
538 * On IBM RS6000 running AIX 3.2 with gcc 2.3.3, there is a problem
539 with the linker. Even if you explicitly specify an object file on the
540 command line, ld may choose to ignore it if no unresolved references
541 is found in it. This causes problem for the persistent streams as they
542 rely on that classes can be linked even if they are not directly
543 referenced in the main program so that objects that are not known to
544 the main program can be read in from a stream. I don't know how to fix
545 this yet (any suggestions are welcome), meanwhile the test programs
546 may be run and executed if you compile them with -DHEP_STRANGE_LD.
547
548
549 References
550 ==========
551
552 The HepLockable, HepLock, HepChooser, HepCombiner, HepCmdArg,
553 HepCmdArgInt, HepCmdArgFloat, HepCmdArgBoolean, HepCmdArgString,
554 HepCmdArgStringList and HepCmdLine classes was written by Paul
555 Rensing.
556
557 The methods for poissonian distributions of integers was written by
558 Irwin Sheer.
559
560 The classdoc program and the original list and string classes were
561 written by Dag Bruck, Department of Automatic Control, Lund Institute
562 of Technology, Box 118, S-221 00 Lund, Sweden. <dag@control.lth.se>
563
564 The rest of the code was mainly written by myself - Leif Lonnblad,
565 DESY (-T-), Notkestr 85, 2000 Hamburg 52, Germany.
566 <lonnblad@ips102.desy.de> and Anders Nilsson, Dept. of
567 Theoretical Physics, Lund University, Solveg. 14a, S-223 62 Lund,
568 Sweden. <anders@thep.lu.se>
569
Send problems or questions to cdfcode@fnal.gov
