Design Summary for the Particle Data Table Classes -------------------------------------------------- ======= General ======= How does the HepPDT package fit in with the broader StdHep ---------------------------------------------------------- StdHep | | V HepMC | | V HepPDT The HepPDT package is at the base, providing information about particle properties that you could find in the RPP (Review of Particle Properties) or similar references. It does not refer to either the attributes of a specific particle of some type (like momentum) nor to organization into events, collisions, and so forth. It depends on no other packages. The HepMC package contains two very important classes: . GenParticle, which represents an actual particle including attributes like momentum, and . GenEvent (or some similar name) organizing particles into navigable events. These (and all related supporting classes such as Vertex) are portions of HepMC which CLHEP will assimilate. HepMC does not currently depend on HepPDT but a dependency will be introduced: GenParticle will have pointers to ParticleData and to DecayData, and may have methods which use ParticleData to return properties like mass, charge, and so forth. StdHep maintains all the capabilities of the classic StdHep product, including interfaces to standardized event common blocks, translations among various other physics packages, organization of events, I/O, and so forth. StdHep depends on both HepMC and on various HepPDT classes. Design Goals ------------ HepPDT's primary purpose is to provide access to particle property data such as can be found in the Review of Particle Physics. Additional goals include: . Incorporate the Particle ID numbering scheme (as described in RPP and used in the Fortran StdHep and in various event generators). . Obtain the particles' properties from a variety of formats that are available electronically. These formats include dedicated tables and generator outputs that describe the generator's internal particle property assumptions. . Include information about particle decay channels. . Provide a way to customize the decay chain of a particular particle. . Accomodate "particles" of interest to Nuclear Physicists, e.g., atomic nucleii, whose "constituents" are protons and neutrons. ============== HepPDT Classes ============== Half a dozen main classes represent key concepts of the HepPDT package. We describe these and, more briefly, several other supporting classes. The Main Classes: ----------------- ParticleDataTable | V ParticleData - - - - -> ParticleID | V DecayData | V DecayChannel | V DecayModel ParticleDataTable This is the collection of all the available ParticleData. Given a ParticleID number, this class can find the corresponding ParticleData. ParticleData This class contains the particle properties. Such properties include those found in the RPP's Particle Listings. For example, the ParticleData for a generic muon would include its mass, total width, and spin. In contrast, momentum would be a property of a specific muon and thus does not appear in the muon ParticleData. Key components of ParticleData include: . a ParticleID, . a collection of Constituents, and . a pointer to a DecayData table. In the HepMC package, a GenParticle will have a pointer to its ParticleData. ParticleID ParticleID represents the standard Monte Carlo numbering scheme (RPP, page 205). Its internal data is an encoded int; methods allow extraction of any information which can be deduced from that int. DecayData This class facilitates customized decay chains for specific particles. This has a collection of DecayChannels and provides a method to select a mode. This design allows a GenParticle to point to a custom DecayData that can override a ParticleData's DecayData. This allows chains of non-standard decays to be forced. DecayChannel A DecayChannel provides all information for one decay channel. This includes: . a branching fraction, . a vector specifying the sorts of particles produced in this decay channel, and . a pointer to a DecayModel. DecayModel This class provides the interface between the generator decay code and the particle property information for a specific DecayChannel. It is intended to be used as a base class for users to customize their decay information. DecayModel has a virtual method, decay(), to apply the DecayChannel. A class derived from DecayModel may contain additional parameters describing a decay. For example, some decay models require helicity information or partial wave amplitudes. Supporting Classes: ------------------- Constituent The class embodies the concept of a fundamental building block of a particle, for example, a quark or a lepton. It specifies a ParticleID and a multiplicity. (The multiplicity allows concise description of a nucleus, which may have tens of neutrons and protons.) DecayChannelProduct This class identifies a ParticleData for use by a DecayModel. It also provides an optional DecayData so that an application can create a chain of custom decays: if a DecayData is present, the daughter can be created with this DecayData instead of the one in its ParticleData. Measurement This simple class holds a value and an associated error. Many values in the ParticleData class are available as a measurement; thus you can get mass.value() or mass.sigma(). If you use a measurement as a double you just get its value, so you can in fact say double x = thisparticle->mass. ResonanceStructure This class describes the mass and line shape of a particle. It assumes a Breit-Wigner with some width and upper and lower cutoffs. SpinState SpinState holds spin, total spin, and orbital angular momentum numbers. Helicity Helicity describes the orientation of a DecayChannelProduct's spin. Quarks ParticleID uses this struct to return the implied quark content in the form nq1, nq2, nq3 (see RPP, page 206). SomeParticle SomeParticle is an illustrative class representing an "actual" particle. It has the requisite descriptions of a ParticleData and a DecayData, and little else. This class is used in HepPDT example programs and stands in for a more sophisticated particle class, e.g. GenParticle. TempParticleData This struct serves as a holder for input information which will eventually form a consistent ParticleData. TableBuilder TableBuilder servers as a holder for the TempParticleData instances which will eventually be turned into ParticleData to fill a ParticleDataTable. TableBuilder is inherently a temporary object: its destructor triggers consistency checking and fills the ParticleDataTable. DecayModelFactory This singleton class ties the application-specific classes expressing algorithms to do decays (these are derived from DecayModel) with input data specifying a DecayModel name and additional parameters for each DecayChannel to use. The crucial method is make(name, params) with returns an instance of the appropriate DecayModel class, instantiated using the supplied parameters. ModelRegister ModelRegister participates in the setup of the DecayModelFactory, and in fact is defined in DecayModelFactory.h. Each DecayModel class has a private static ModelRegister, which automates the installation of that class' name and make() method into the DecayModelFactory. Utilities --------- These functions input or output particle properties: Declared in TableBuilder.h: . addPythiaParticles(istream&, TableBuilder &) . addEvtGenParticles(istream&, TableBuilder &) . addQQParticles (istream&, TableBuilder &) . addPDGParticles (istream&, TableBuilder &) Declared in ParticleDataTableT.h: . writePythiaStream(ostream&, const ParticleDataTable &) . writeEvtGenStream(ostream&, const ParticleDataTable &) . writeQQStream (ostream&, const ParticleDataTable &) . writePDGStream (ostream&, const ParticleDataTable &) and others as needed. Special Issues -------------- A separate document, "Design Issues for the Particle Data Table Classes in StdHep," addresses the following issues: . Why TempParticleData? . Custom Decay Chains . Ownership, Reference Counting, and Auto_ptr's . Templates: What and Why? . DecayModelFactory and Registration