// Propagator.h

#ifndef Propagator_H
#define Propagator_H

// This class provides the interface for propagating a track to
// a surface.  In general, there may be any number of points
// (0, 1, 2, 3, ...) where the track intersects the surface.
// This interface is intended to propagate to either the nearest 
// point in forward direction or the nearest point in the backward
// direction.  There are three options: the track may be propagated
// only in the forward direction, only the backward direction or 
// to the nearest of the two crossings.
//
// For each of the options there are two possibilities when the
// destination surface is the same as the original surface.  The
// original specification was to stay at the same position.  Now
// there are options (XXX_MOVE) to move to the next crossing.
//
// Two methods of propagation are provided.  One specifies this option.
// The other does not and it is the reponsibility of the subclass to
// make a clear and unambiguous choice.
//
// There are also separate propagation methods for tracks with and
// without error matrices.  These should behave in exactly the same
// manner except for changes to the error matrix.  The new vector
// may not depend on the error matrix.
//
// The methods to propagate a track with error are implemented here
// using the methods without error.  Typically there should be no
// need for subclasses to override the former.
//
// The original track is overwritten with the new track parameters
// if and only if the propagation is successful.  A propagation
// status is returned to indicate whether the propagation was
// was successful and, if so, the direction of propagation relative
// to the track's direction.
//
// The propagation may be called repeatedly to iterate over all the
// crossings in either the forward or backward direction.  In order
// to maintain this capability, a track that is already at the 
// surface (i.e. has the same pure surface as the destination) must
// be propagated to a new point or the propagation is not successful.
// However, if the point is on but not at the surface (i.e. it is on
// a different type of pure surface but has coordinates lying on the
// destination surface, then the transformed track should be returned
// as a successful propagation in the requested direction.
//
// When labeling or choosing the direction of propagation, forward
// should be chosen if there is an ambiguity.
//
// This clase is abstract: derived classes provide the algorithms
// for propagation.
//
// A higher level class might make use of this interface to provide
// an iterator over crossings.  It could carry out the propagation
// as needed and cache the results.
//
// The propagate methods all include an optional argument which is a
// pointer to a track derivative.  If this pointer is not null, then
// its location should be filled with the derivative of the new track
// w.r.t. the original.
//

#include "Algorithm.h"

namespace trf {

class PropStat;
class VTrack;
class ETrack;
class Surface;
class TrackDerivative;

class Propagator : public Algorithm {

public:

  // Direction to go.
  // XXX_MOVE means to go to the next crossing if the original and
  // destinataion surfaces are the same.
  enum PropDir { NEAREST, FORWARD, BACKWARD,
                 NEAREST_MOVE, FORWARD_MOVE, BACKWARD_MOVE };

public:  // static methods

  // Return the type name.
  static TypeName get_type_name() { return "Propagator"; }

  // Return the creator.
  static ObjCreator get_creator();

  // Return the type.
  static Type get_static_type() { return get_creator(); }

  // Reduce a propagation direction.
  // This drops the _MOVE from a direction and returns true
  // if the suffix was present.
  // It is used in subclasses to separate the true direction from
  // the move status in a direction.
  static bool reduce_direction(PropDir& dir);

public:

  // constructor
  Propagator();

  // destructor
  virtual ~Propagator();

  // Return the type.
  Type get_generic_type() const { return get_static_type(); }

  // Clone, i.e. create a copy on the free store.
  // Must be overriden in subclasses.
  virtual Propagator* new_propagator() const =0;

  // Propagate a track without error.
  // Must be overriden in subclasses.
  // This is implemented in PropDirected--typically subclasses
  // will inherit from that and then not override this method.
  virtual PropStat
  vec_prop(VTrack& trv, const Surface& srf,
             TrackDerivative* pder =0) const =0;

  // Propagate a track without error in the specified direction.
  // Must be overriden in subclasses.
  virtual PropStat
  vec_dir_prop(VTrack& trv, const Surface& srf, PropDir dir,
               TrackDerivative* pder =0) const =0;

  // Propagate a track with error.
  // Typically does not need to be overridden in subclasses.
  virtual PropStat
  err_prop(ETrack& tre, const Surface& srf,
           TrackDerivative* pder =0) const;

  // Propagate a track with error in the specified direction.
  // Typically does not need to be overridden in subclasses.
  virtual PropStat
  err_dir_prop(ETrack& tre, const Surface& srf, PropDir dir,
               TrackDerivative* pder =0) const;

};

}  // end namespace trf

#endif