More documentation of event data structure.

1 files changed, 72 insertions, 0 deletions

diff --git a/chroma/event.py b/chroma/event.py
index a8f5f52..334df9a 100644
--- a/chroma/event.py
+++ b/chroma/event.py
@@ -12,6 +12,28 @@ NAN_ABORT        = 0x1 << 31
 
 class Vertex(object):
     def __init__(self, particle_name, pos, dir, ke, t0=0.0, pol=None):
+        '''Create a particle vertex.
+
+           particle_name: string
+               Name of particle, following the GEANT4 convention.  
+               Examples: e-, e+, gamma, mu-, mu+, pi0
+
+           pos: array-like object, length 3
+               Position of particle vertex (mm)
+
+           dir: array-like object, length 3
+               Normalized direction vector
+
+           ke: float
+               Kinetic energy (MeV)
+
+           t0: float
+               Initial time of particle (ns)
+               
+           pol: array-like object, length 3
+               Normalized polarization vector.  By default, set to None,
+               and the particle is treated as having a random polarization.
+        '''
         self.particle_name = particle_name
         self.pos = pos
         self.dir = dir
@@ -68,6 +90,13 @@ class Photons(object):
             self.flags = flags
 
     def __add__(self, other):
+        '''Concatenate two Photons objects into one list of photons.
+
+           other: chroma.event.Photons
+              List of photons to add to self.
+
+           Returns: new instance of chroma.event.Photons containing the photons in self and other.
+        '''
         pos = np.concatenate((self.pos, other.pos))
         dir = np.concatenate((self.dir, other.dir))
         pol = np.concatenate((self.pol, other.pol))
@@ -78,20 +107,63 @@ class Photons(object):
         return Photons(pos, dir, pol, wavelengths, t, last_hit_triangles, flags)
 
     def __len__(self):
+        '''Returns the number of photons in self.'''
         return len(self.pos)
 
 class Channels(object):
     def __init__(self, hit, t, q, flags=None):
+        '''Create a list of n channels.  All channels in the detector must 
+        be included, regardless of whether they were hit.
+
+           hit: numpy.ndarray(dtype=bool, shape=n)
+             Hit state of each channel.
+
+           t: numpy.ndarray(dtype=numpy.float32, shape=n)
+             Hit time of each channel. (ns)
+
+           q: numpy.ndarray(dtype=numpy.float32, shape=n)
+             Integrated charge from hit.  (units same as charge 
+             distribution in detector definition)
+        '''
         self.hit = hit
         self.t = t
         self.q = q
         self.flags = flags
 
     def hit_channels(self):
+        '''Extract a list of hit channels.
+        
+        Returns: array of hit channel IDs, array of hit times, array of charges on hit channels
+        '''
         return self.hit.nonzero(), self.t[self.hit], self.q[self.hit]
 
 class Event(object):
     def __init__(self, id=0, primary_vertex=None, vertices=None, photons_beg=None, photons_end=None, channels=None):
+        '''Create an event.
+
+            id: int
+              ID number of this event
+
+            primary_vertex: chroma.event.Vertex
+              Vertex information for primary generating particle.
+              
+            vertices: list of chroma.event.Vertex objects
+              Starting vertices to propagate in this event.  By default
+              this is the primary vertex, but complex interactions
+              can be representing by putting vertices for the
+              outgoing products in this list.
+
+            photons_beg: chroma.event.Photons
+              Set of initial photon vertices in this event
+
+            photons_end: chroma.event.Photons
+              Set of final photon vertices in this event
+
+            channels: chroma.event.Channels
+              Electronics channel readout information.  Every channel
+              should be included, with hit or not hit status indicated
+              by the channels.hit flags.
+        '''
         self.id = id
 
         self.nphotons = None