1 package org.lcsim.recon.tracking.trflayer;
2
3 import java.util.*;
4 import org.lcsim.recon.tracking.trfutil.Assert;
5 import org.lcsim.recon.tracking.trfbase.Surface;
6 import org.lcsim.recon.tracking.trfbase.Cluster;
7 import org.lcsim.recon.tracking.trfbase.ETrack;
8 import org.lcsim.recon.tracking.trfbase.Propagator;
9
10 /**
11 * Layers describe the geometry of the detector. Each layer is
12 * composed of surfaces. The composition may be direct or via other
13 * layers.
14 *
15 * The layer provides the methods propagate which propagate a track
16 * to the next of its constituent surfaces. The propagate methods are
17 * passed a propagator which carries out the action and determines the
18 * direction.
19 *
20 * Propagation returns a list of layer tracks. A layer track is a
21 * kinematic track plus a layer status. The layer status may also
22 * contain a miss and a cluster finder. It is expected that each of
23 * the returned tracks will be updated with the miss and clusters
24 * and then propagated through the layer again until the status indicates
25 * the track has reached a layer exit.
26 *
27 * There are two methods of propagation: both are passed the track and
28 * the propagator but in the second the track is wrapped in the layer
29 * track. The first is used when entering the layer and the second
30 * for all calls within the layer.
31 *
32 * Both of these propagate methods are implemented here. Subclasses
33 * do not override these but must provide the method _propagate which is
34 * used by these. Its interface is described below.
35 *
36 * If there are a lists of clusters associated layer, the method
37 * get_clusters may be used to access them.
38 *
39 *
40 * NOTICE for subclass developers:
41 *
42 * The major method that subclasses must implement is
43 * LTracklist _propagate(const LTrack& trl, const Propagator& prop) const .
44 * The input is a layer track and a propagator and the output is a list
45 * of layer tracks. The output layer tracks would typically be created
46 * by copying from the input layer track and then modifying it two
47 * components: the kinematic track and the layer status chain.
48 *
49 * The layer chain includes a list of layer status objects and two pointers
50 * to this list: one for the current layer postion and one for the
51 * status which contains the list of clusters and the miss.
52 *
53 * When a layer is nested (i.e. composed of other layers), the chain must
54 * be advanced to that layer before calling the propagate method of a
55 * sublayer. The current status should be set to that same position when
56 * layer when returning from propagation.
57 *
58 * The cluster pointer is not set automatically. The layer class
59 * contributing the status containing a cluster list or miss should
60 * call LTrack::set_cluster_status() to set this pointer.
61 *
62 *
63 * still needs work to implement multiple surface layers...
64 **/
65
66
67 public abstract class Layer
68 {
69
70 // Assertion arguments.
71 // Set false to enable assertions.
72 static boolean GET_CLUSTERS_HAS_NO_CLUSTERS = false;
73 static boolean GET_CLUSTERS_SURFACE_HAS_NO_CLUSTERS = false;
74 static boolean ADD_CLUSTER_HAS_NO_CLUSTERS = false;
75 static boolean ADD_CLUSTER_SURFACE_HAS_NO_CLUSTERS = false;
76 static boolean DROP_CLUSTERS_HAS_NO_CLUSTERS = false;
77
78 // static methods
79
80 //
81
82 /**
83 *Return the type name.
84 *
85 * @return String representation of this class type
86 *Included for completeness with C++ version
87 */
88 public static String typeName()
89 { return "Layer"; }
90
91 //
92
93 /**
94 *Return the type.
95 *
96 * @return String representation of this class type
97 *Included for completeness with C++ version
98 */
99 public static String staticType()
100 { return typeName(); }
101
102 // methods
103
104 // Subclasses call this method if they are passed an invalid
105 // surface.
106 protected void reportInvalidSurface(Surface srf)
107 {
108 }
109
110 // methods implemented here
111
112 //
113
114 /**
115 *constructor
116 *
117 */
118 public Layer()
119 {
120 }
121 //
122
123 /**
124 *Return the generic type of this class.
125 * Subclasses must not override.
126 *
127 * @return String representation of this class type
128 *Included for completeness with C++ version
129 */
130 public String genericType()
131 { return staticType(); }
132
133 //
134
135 /**
136 *Propagate a track to the first surface in this layer.
137 * This simply constructs a status and calls the virtual method.
138 *
139 * @param tre ETrack
140 * @param prop Propagator
141 * @return List of LayerStats
142 */
143 public List propagate( ETrack tre, Propagator prop)
144 {
145 LayerStat lstat = new LayerStat(this);
146 LTrack trl = new LTrack(tre,lstat);
147 return propagate(trl, prop);
148 }
149
150 //
151
152 /**
153 *Propagate a track to the next surface in this layer.
154 * The status is that from the previous surface in the layer.
155 *
156 * @param trl LTrack
157 * @param prop Propagator
158 * @return List of LayerStats
159 */
160 public List propagate(LTrack trl, Propagator prop)
161 {
162
163 // Check that the status corresponds to this layer.
164 // If not, crash or return an empty list.
165 Layer lyr = trl.status().layer();
166 Assert.assertTrue( lyr.equals(this) );
167 if ( !lyr.equals(this) ) return new ArrayList();
168
169 // propagate
170 List ltracks = _propagate(trl, prop);
171
172 // Check status still points to this layer.
173 // If not, crash or return an empty list.
174 lyr = trl.status().layer();
175 Assert.assertTrue( lyr.equals(this) );
176 if ( !lyr.equals(this) ) return new ArrayList();
177
178 return ltracks;
179 }
180
181 //
182
183 /**
184 *Return whether this layer or its descendants contains clusters.
185 * Returns false if get_cluster_surfaces() returns an empty list.
186 *
187 * @return true if surface has clusters
188 */
189 public boolean hasClusters()
190 { return !(clusterSurfaces().size()==0); }
191
192 // methods to be implemented in subclasses
193
194
195 // Propagate a track to the next surface in this layer.
196 // The list of succesful propagations is returned.
197 // When layers are nested, this method in the parent will typically
198 // invoke the same method for each of its children.
199 protected abstract List
200 _propagate( LTrack trl, Propagator prop);
201
202 /* //This needs to be replaced with the above!
203 protected abstract List
204 _propagate( ETrack trl, Propagator prop);
205 */
206 // methods to be implemented in subclasses
207
208 //
209
210 /**
211 *Return the list of active surfaces -- i.e. surfaces associated
212 * with clusters. These should include surfaces in sublayers.
213 * Default method reports no surfaces.
214 *
215 * @return List of surfaces
216 */
217 public List clusterSurfaces()
218 {
219 return new ArrayList();
220 }
221
222 //
223
224 /**
225 *Return all the clusters associated with the current layer
226 * or its descendants.
227 * Default here is to return an empty list.
228 *
229 * @return list of clusters
230 */
231 public List clusters()
232 {
233 Assert.assertTrue( GET_CLUSTERS_HAS_NO_CLUSTERS );
234 return new ArrayList();
235 }
236
237 //
238
239 /**
240 *Return all the clusters associated with a particular surface
241 * in this layer.
242 * This method should call report_invalid_surface(SurfacePtr)
243 * if it does not recognize the argument.
244 * Default is to return an empty list.
245 *
246 * @param srf Surface
247 * @return List of clusters associated with Surface srf
248 */
249 public List clusters(Surface srf)
250 {
251 reportInvalidSurface(srf);
252 Assert.assertTrue( GET_CLUSTERS_SURFACE_HAS_NO_CLUSTERS );
253 return new ArrayList();
254 }
255
256 //
257
258 /**
259 *Add a cluster to the layer.
260 * Default here is to return an error.
261 *
262 * @param clu Cluster to add
263 * @return 0 if successful
264 */
265 public int addCluster( Cluster clu)
266 {
267 Assert.assertTrue( ADD_CLUSTER_HAS_NO_CLUSTERS );
268 return -1;
269 }
270
271 //
272 /**
273 *Add a cluster to a particular surface in the layer.
274 * Default here is to return an error.
275 *
276 * @param clu Cluster to add
277 * @param srf Surface to which to add
278 * @return 0 if successful
279 */
280
281 public int addCluster( Cluster clu, Surface srf)
282 {
283 reportInvalidSurface(srf);
284 Assert.assertTrue( ADD_CLUSTER_SURFACE_HAS_NO_CLUSTERS );
285 return -1;
286 }
287
288 //
289
290 /**
291 *Drop all clusters from this layer.
292 * // Default here is to return an error.
293 *
294 */
295 public void dropClusters()
296 {
297 if ( hasClusters() ) Assert.assertTrue( DROP_CLUSTERS_HAS_NO_CLUSTERS );
298 }
299 }