	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<DecayChannelProduct> 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<PT> &)
    . addEvtGenParticles(istream&, TableBuilder<PT> &)
    . addQQParticles    (istream&, TableBuilder<PT> &)
    . addPDGParticles   (istream&, TableBuilder<PT> &)

  Declared in ParticleDataTableT.h:
    . writePythiaStream(ostream&, const ParticleDataTable<PT> &)
    . writeEvtGenStream(ostream&, const ParticleDataTable<PT> &)
    . writeQQStream    (ostream&, const ParticleDataTable<PT> &)
    . writePDGStream   (ostream&, const ParticleDataTable<PT> &)

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

