Vector/doc/merge-details.doc

------------
ZOOM classes
------------

Symbol pollution:
It is undesirable to pollute the CLHEP namespace with the following symbols:
DEGREES RADIANS ETA.  So these are placed purely into the ZMpv namespace,
which is defined in the SpaceVector.h backward-compatibility header.
This has the consequence that ThreeVector.h is considerably simplified,
since the plethora of constructors is greatly reduced.

Spherical coordinate setting:
Even though the direct spherical coordinate constructors are no longer in the
main Hep3Vector class, the user can still use the set() methods in spherical
coordinates.  Except that again the keywords DERGREES RADIANS ETA are not
available.  Instead, we provide a few new methods, for example,
   setRThetaPhi(double r, double theta, double phi);
In these, alll angles are always treated as measured in RADIANS.

Spherical coordinate setting mof V in LorentzVector:
We again eliminate the keywords DEGREES RADIANS and ETA from the CLHEP class.
THe same new methods are provided.  This time, however, we feel no need to
put the old methods in the PhysicsVectors class because nobody is using them.

X_HAT Y_HAT Z_HAT:
These were in the original physicsVectors package as UnitVectors.  They remain
so.  Pure CLHEP users do have the Hep3Vectors HepXHat, HepYHat, HepZHat.
Note, by the way, that X_HAT, Y_HAT, Z_HAT are static to each code unit that
includes UnitVector.h.  This is safer from the viewpoint of subtle
order-of-initialization issues.  Coders should not use HepXHat in
initialization code that will execute prior to main() because it is not
guaranteed that they will be initialized before they are used.


--------------------
LorentzTransformation
--------------------

set from (bx,by,bz):
The merged classes have to contain a constructor from three boost components
because CLHEP does.  They must contain set taking a boost vector because
ZOOM does.  There need not, a priori, be
LorentzRotation::set(double,double,Hepdouble) but we include that to
be a bit orthogonal.

transform (Rotation r):
While CLHEP has a separate method for transform taking a HepRotation, this
is not strictly needed since HepRotation is a Hep3RotationInterface which in
turn is a Hep4RotationInterface.  If you know the argument is 3x3 you could
do 3x3 times 4x4 (in principle faster) and for transform, the original CLHEP
would do this.  On the other hand, for multiplication this "efficiency" was
not done; there is no operator* (HepRotation).   In reallity, the time needed
for 3x3 times 4x4 is not significantly less, certainly not enough to warrant
the additional complication.  So we simple provide the transform method taking
a 4 rotation interface, which will break no code.
But for pure rotations around coordinate axes and boosts along axes, we do
provide such methods as rotateZ and boostZ.  Here the efficiency difference
is marked.  Besides, CLHEP has these explicitly.
We also must keep the technically superfluous rotate(delta,axis) and
boost(3 doubles or 3-vector) methods.

Split of .cc files:
Outside the main LorentzRotation.cc is
LorentzRotationC.cc 	set(col1, col2, col3, col4) and related constructors
LorentzRotationD.cc 	all the decompose methods
			rectify
			compare
			distance2 (uses decompose)

rotateX, Y and Z:
Although these are inline in CLHEP, we make them normal now.  The reason is
that we can thus take advantage of rather big savings in algorithm (by
utilizing the fact that the rotation only involves an X rotation or whatever).

ZMxpv in LorentzRotation.cc
As a reminder, the ZMthrow macro is defined as outputting its argument and
aborting.  (ZMthrowC does not abort).  That said, should we use ZMthrow
(defined in ZMxpv.h) in the basic LorentzRotation class?  I think we have to:
the method set (double, double, double) -- which was present in CLHEP -- had
a flaw in that it would take sqrt of a negative number if the arguments
supplied had mag2 > 1.  We really should behave more sensibly here ahd ZMthrow
is the best we can do.

Physical coupling:
Currently, BoostX needs LorentzRotation.h and so forth, because the product of
a boost times an Hep4RotationInterface is a LorentzRotation.  We could
probably lessen this sort of coupling but maybe not without sacrificing
speed.  At any rate, I short-circuited design though on this issue in favor
of getting the merge done!

Efficiency of distance2 for boosts:
We can, by providing distance2(HepLorentzRotation) and the other concrete
classes, significantly speed up this computation, because we don't have to go
back and forth through HepAxisAngle for the rotation decompositin and
Hep3Vector for the boost.  However, this would add another 15 methods to each
header (assuming we would want these gains in isNear and HowNear also);
I decided it might not be worth it.

TODO:  Test rotateX, Y, Z; boostX, Y, Z -- these are I think new.  Just check
	against the equivalent form by instantiating a general Lor. Rot
   	based on a ROtationX and so forth.


--------
Rotation
--------

Classes:
ZOOM has the concepts of RotationX, RotationY, RotationZ, LorentzBoost,
LorentzBoostX, LorentzBoostY, LorentzBoostZ.  These are useful and will become
part of CLHEP.  THe boost classes may be in their own header file.

Inheritance structure:
I am telescoping a lot of thought into a few words here.
ZOOM has RotationInterface and LorentzTransformationInterface, which
provide those methods available for GETTING INFORMATION ABOUT generic
Rotations and LorentzTransformations.  We should keep these.  The proper
inheritance is that RI derives from LTI, because anything you wish to ask
about a LT you could equally well ask about a R.  From LTI, one derives
LT, and each of the boosts.  From RI, one derives Rotation and its special
cases.  We then can derive RotationX from Rotation, being careful to
supply private throwing methods when attempting to do an illegal mutation.
(Private so that the compiler will catch the error whenever possible;
but implemented so that if a RotationX is passed to a routine expecting a
Rotation &, and the user tries to change it in an illegal way, he won't
get an invalid RotationX in a continuing program.


Also, RotationAboutCoordinateAxis and BoostAlongCoordinateAxis are gone;
they were not useful enought to be worth their complexity cost.

Virtual destructor:
Since the classes have to inherit from a virtual interface (to match ZOOM
compatibility) they have Vtables anyway.  For various technical reasons,
the virtual mechanism is useful.  By the way, UNLIKE the case for 3-vectors
and 4-vectors, the overhead cost is small, and the number of distinct
Rotation objects in our key jobs is not in the millions, so the virtual
mechanism is not at all costly.

Names of interface classes:
Since CLHEP users will see these classes, and may well use them (as in the
case of passing a generic interface for a Rotation and letting the code
select the efficient operator() if it is specialized to an axial rotation),
the names should be CHLEP-like.  Thus Hep3RotationInterface and
Hep4RotationInterface.  As usual, the ZOOM names are placed in a separate
header and will be namespace-guarded.

Header file completeness:
It is necessary (so that CLHEP users can continue to rely on the header for
finding out what methods are available) that all the methods available for
HepRotation appear in that class'es definition.  No problem, since most
are pure virtual in the base class anyway (and thus had to be present anyway.)
There may be a few exceptions which we will have to be sure are present.

tolerance sharing:
It is right to use the same tolerance for RotationInterface that it gets by
inheritance from LTI.  This avoids some thorny dynamic-vs-static behavior
differences.

decompose method:
There is a method (actually a pair of signatures) to decompose a LT into a
pure rotation times a pure boost (and also boost times rotation).  This does
not really belong in the interface, even though it is a matter of getting
information about a LT, and even though they can be defined for any sort
of specialized LT.  The reason is that the interface class should not need
to know about two of its concrete descendants!  Instead, decompose(R,B) will
be a method of HepLorentzRotation (= LorentzTransformation).  This is a subtle
change from the ZOOM things but I think it VERY unlikely that anybody was
doing decompose on an anonymous LorentzTransformationInterface &.
Meanwhile, however, the compare() method really needs decompose!  And
if I take compare() out of the interface, then all the dictionary-ordering
comparisons will need to be repeated in derived classes.  Solution:  There
is an ADDITIONAL method decompose (Hep3Vector& boost, AxisAngle& rotation).
The interface does know about these, so that is fine.  And comparison is of
course just as valid using these (in fact, that is how it was being done
anyway).  Now compare() becomes inline in the base class, and decompose
is the virtual method it utilizes.

Where should the RotationX header be:
I will go with the obvious:  RotationX.h etc.

Operator() and [][]:
ZOOM did not have these.  Since these are not easy to implement with the same
semantics as in CLHEP, for an arbitrary Hep3RotationInterface, and since they
do not have to be there, we won't try to put them there.  Similarly, they are
absent from RotationX etc.  Only HepRotation has these methods.

Commonality in RotationX, RotationY, RotationZ:
We repeat a lot of trival routines like xt() for these classes.  Since they
are identical it is tempting to factor them out, having RotationX etc inherit
from RACA (RotationAboutCoordinateAxis).  However, for code simplification
and to avoid subtle using issues we have just eliminated that trick from
PhysicsVectors.  So we eat the extra code.

inverseOf:
This method, declared in the RotationInterface class as a friend, introduces
bad coupling between the interface and Rotation (which the method returns).
Instead, we put it into the concrete classes.

PhiX, thetaX, etc for RotationX, RotationY, RotationZ:
We could fairly easily avoid taking an atan2 or acos.  For example,
RotationX::thetaZ can just do return d.  In some of the other cases you have
to branch according to the qudrant of delta, but in no case do you need an
inverse trig taken.  However, for maximal safety, I just use the same
code as was in CLHEP originally.  The only mod made is that IN COMMENTS I
put some faster implementations; later we can decide to use these but I
believe the frequency of cuse of RotationX::phiX etc. will be negligible
anyway.


Equivalent methods:
In principle you don't want to repeat code.  So for example, the rotateX
method could be implemented as *this= RotationX(delta)* *this.  However,
except for absolutely trivial cases, I feel it unacceptable to take any
risk of existing CLHEP methods yielding different results (similarly for
ZOOM methods that have no exact CLHEP match.  So for instance I leave the
implementatoin of getAngleAxis(double &, Hep3Vector &) even though it
could be written as simply as
	{ HepAxisAngle z = axisAngle(); delta=a.delta; axis=a.axis; }
(Given the split into several .cc files, the total code pulled in for a
typical application will shrink, anyway.)
Careful note will be made of all such "dual-implementation" situations, and
we will take advantage by testing for equivalence in our test suites.

Private data:
ZOOM declares a rep3x3 struct which is very usreful for people who "just
want the damn matrix."  This is useful enough that we add it to CLHEP in
RotationInterfaces.h .  But also, the concrete class Rotation uses
a Rep3x3 as its private data.  In CLHEP the private data is just rxx, rxy
... rzz.  In the spirit of decided close things in favor of cooperation, we
use the CLHEP form.

To inline or not to inline:
Several inline methods of HepRotation FAR exceed sensible standards for
inlining.  I have moved these to the .cc file:
	operator==(), isIdentity(),

operator>>:
It might be nice to have an input method such that if you take the output
of operator<< you get the original.  However, that was not present in either
ZOOM or CLHEP and I am not coding it at this time.

HEP_SHORT_NAMES:
It looks like if HEP_SHORT_NAMES is defined, then Rotation will collide with
the ZOOM Rotation class.  We will (for now) just say that you can't have both.
We could do something fancier like have the ZOOM header check for and undef
HEP_SHORT_NAMES when including the CLHEP Rotation.h but I will leave that for
future consideration.


Split into code units:
Rotation.cc		Original CLHEP Rotation, plus
RotationIO.cc		IO (just put() - why pull in iomanip.h if not needed
RotationA.cc		Axis-angle routines
RotationE.cc		Euler angle routines
RotationC.cc		Long routines involving rectifying near-rotations
			(for example, constructor from 3 column vectors)
RotationL.cc		3-Rotation routines involving 4-rotation arguments,
			thus requiring linking 4-rotation code units.
RotationP.cc		All other methods originating in PhysicsVectors


"Clash-table":

operator * (v)	I unified to return operator() (v).  I use the CLHEP
		implementation of (the equivalent) operator*(v) - but
		as discussed, this is moved into the .cc, not .icc.

operator ==	I left the CLHEP code for Rotation rather than using
		the base class method which would return (compare(v)==0)
		(which is a lot more work).

getaxisAngle and getAngleAxis

Multiplicatoin in Rotation Group:
In principle one might like to have all Rotation*Rotation operations as free
methods.  However, the "double-dispatch" issue rears its ugly head, and the
bottom line is that if we do it that way then we are forced to have ambiguous
signatures.   We instead provide multiplication as a member function.  It
can't be virtual in the base Hep3RotationInterface class, however, since it is
"not good" for Hep3RotationInterface to have to know about Hep3Rotation.
In short, we are using the simplest and least sophisticated way to implement
these, so that things will compile everywhere.


- - -

operator() (LrentzVector)

HepRotation (AxisAngle) 		and corresponding set()
HepRotation (EulerAngles) 		and corresponding set()
colX, colY, colZ, rowX, rowY, rowZ
phi(), theta(), psi()
axis(), delta()
setPhi, setAxis, and so forth.
setRows()
compare, operator>, operator<, operator>=, operator<=
distance2(), howNear(), isnNear()
norm2()
rectify()
a static Rotation::IDENTITY
methods treating the Rotation as a Hep4RotationInterface:
	col1 ... col4; row1 ... row4

- - -

operator== etc inline:

Since compare() will be virtual, all these comparison operators can be
inline in the interface class.

Inlining col1 etc:

These should be inline, just like operator==, in the interface classes since
everytihing is written in terms of xx(), xy()... which are virtual.  However,
in the individual spcialized classes we may profitably override these anyway.

decompose:

You don't want the interface class to know about its derived classes.
So decompose(R,B) is not a good idea.  A right way would be

virtual void decomposeBR (  Hep4RotationInterface & b,
                            Hep4RotationInterface & r ) const = 0;
virtual void decomposeRB (  Hep4RotationInterface & r,
                            Hep4RotationInterface & b ) const = 0;

and the signatures of decompose invoving a Rotation and a boost appear
in the concrete classes.

But the decomposeRB and BR methods should NEVER be used since it does not
pay to return a whold LT when a Rotation or boost is called for.  Plus,
you get a dangerous object:  A LT with known extra properties.

I eliminate decompose from the generic interface altogether -- decompose
becomes purely a method of the concrete LorentzTransformation class.

Forbenius:
eliminate it.

Things moved from CLHEP into RotationInterfaces:

HepRotation_row:

Is R[i][j] 1 or 0 based in CLHEP?  NOte that for Hep3Vector, v[i] is
0-based.  So I can surely use the trick of returning a Hep3Vector as a row.
I should try it, but I would think I can eliminate  class HepRotation_row
and have  inline const Hep3Vector operator [] (int) const; because
a = r[i][j] would then have the same behavior -- and because nobody is
using things like HepRotation HepRotation_row myrow; myrow = ... in real
code.

We must be careful, however:  the return type of operator[] should not
be Hep3Vector, because in the Hep4RotationINterface, the same reasoning says
it should be a HepLorentzVector!!,  And at that point the 0-based choice
comes back to bite us:  X,Y,Z,T = 0,1,2,3 seems very unnatural.  Nonetheless,
that is indeed the choice made in CLHEP (see LorentzVector.h where
enum { X=0, Y=1, Z=2, T=3, NUM_COORDINATES=4, SIZE=NUM_COORDINATES };

If we do return a HepLorentzVector, how does the behavior change?
All the correct suages, e.g. r[2][2], are still correct and unchanged.
And if one does r[3][2] that does not have to change at all:  operator[]
on a HepRotation can point out an error if the argument is > 2.  However,
if somebody does r[2][3] that will come back 0 without an error, since
it is perfectly acceptable to take w[3] where w is a HepLorentzVector.

So either I should have a HepRot_row helper (as CLHEP does) or I must live
with that non-catch.  By the way, if a helper, it can be shared between
classes, but what is the best way to do that...

private data:
ZOOM uses a Rep3x3 rep_; we go with the CLHEP data instead.

setRows:
Rather than replicate all that code, I will use setCOls and then invert!

R.compare (Hep4RotationInterface & lt ):
This is very awkward because we don't wish to pull in all of the LT stuff.
But note that Rotation in ZOOM does NOT have these.  SO we can drop them
altogether.


-----------
PlaneVector
-----------

New methods when placing in CLHEP:
These are inserted just for similarity with the other Vector classes...
	Operator[]
	L-value operator() and []
	isParallel, isOrthogonal, howParallel, howOrthogonal
	compare, operator  < > <= >=
	setPolar

Physical Coupling to Hep3Vector:
We forward declare Hep3Vector, and any methods involving Hep3Vector are
implemented in the .cc file, so a user using Hep2Vector need not pull in
Hep3Vector.h.

CMATH_NAMESPACE::
This is liberally used to prepare for ISOcxx portability, which handles all
the of places where things like sqrt are found.  CLHEP has its own congfigure
mechanism, and till ISOcxx is in place, it is best to just remove this
accomodation.  (Later we may want to put it back in when ISOcxx is there.
At that point, the whole package, includeing the old CLHEP implementations,
should do have this change.)


---------
UnitVector
----------

Where does the UnitVector code go:
Main issue is the fact that though this is not in CLHEP, we will not end up
having a library in PhysicsVectors.  Fortunately, we can mkae UnitVector.h
completely self-contained:  Every routine is either trivial or casts (*this)
to a Hep3Vector and uses the implementation for that.  So the UnitVector
class leads to no library code of its own!

C-style or modern casts:
We have gone with old C-style casts for the purposes of using the Hep3Vector
implementations.  And to avoid any chance of a compiler actually copying
the object (after all, we do have operator Hep3Vector()), we cast this as
a Hep3vector* and use ->.  Thus:
	 double phi()    const {return ((Hep3Vector*)this)->phi();}
We could instead have used a static_cast <Hep3Vector*> but that is really
not any safer for us, and adds some risk of the some compilers not having
that syntax, or of some compiler using our cast operator to create a temporary
copy, which we don't want.

Name of UnitVector class:
Since UnitVector is not in CLHEP (for now) we could just retain the name
UnitVector.  However, it may eventually become part of CLHEP, so I chose
to parallel the situation for SpaceVector w.r.t. Hep3Vector.  Thus, the header
defines HepUnit3Vector in the global namespace, and inside the potential
zmpv namespace typedefes UnitVector to be that.

UnitVector as an argument:
The conversion operator to Hep3Vector makes it trivial to use UnitVector as
an argument to any routine that takes a Hep3Vector.
There will be cases where it would be beneficial to have a special method
taking advantage of the knowledge that a UnitVector need not be normalized.
For the present, we will not attempt to obtain this advantage.  In most cases
the UnitVector is originally based on a Hep3Vector; there, the work of
normalizing the vector twice can easily be avoided.

rotationOf global methods:
Since there is a conversion operator from UnitVector to Hep3Vector,
we could have omitted the global rotationOf(UnitVector, ...) methods.
But because when such a method is applied the answer is known to be a
UnitVector, we chose to provide methods with those signatures, returning
HepUnit3Vector instead of Hep3Vector.  These simply treat the UnitVector
as a Hep3Vector, perform the rotation, and return the result as a unit
vector.


--------------
LorentzVector
--------------

** Et
** Et is E Pperp/p.

** Metric selector:
** ZOOM allows the user to set metric as TimePositive or TimeNegative;
** the default is TimePositive.  CLHEP always does TimePositive.  The
** cost of the flexibility is small:   Roughly 10% in dot, diff2, and mag2
** and no other routines altered.  Because of this, I am keeping metric
** flexibility in the package.

** XYZT or TXYZ in constructor:
** ZOOM prevented ambguity by having a type Tcomponent.  The quote from
** the .h file is "We do not support forming a LorentzVector from 4
** undistiguished Scalars, which could lead to uncaught mistakes of
** putting t first.  CLHEP chose to provide this ordinary 4-doubles
** signature, with T assumed to be last.  We of course must keep all
** three.  The possibility of user error does exist but was already
** there in CLHEP and nobody was getting burnt.

** "explicit" keyword:
** ZOOM allows constcuting a LorentzVector from just p (with e = 0)
** and from just e (with p=0).  ZOOM uses the "explicit" keyword to
** protect against possible mishaps with such consturcutions.  Since
** CLHEP already uses the "explicit" keyword (in the Matrix package)
** we will retain it here.

** mag2() and m2():
** CLHEP treats mag2() as the same as restMass2().  This is the only possible
** meaning when the metric is fixed as ---+.  However, if there is flexibility
** in the sense of the metric, it is most natural to consider mag2() to be
** defined as w.dot(w).  This is how ZOOM treats it.  Since CLHEP users will
** not have altered the choice of metric, they will not be affected if the
** ZOOM definition is used, so we go that way.  On the other hand, m2() really
** sounds like it should mean the physics mass squared; what we call in ZOOM
** restMass2().  ZOOM does not have a method m2().  So we leave m2 as metric
** independant, and identical to restMass2().

** boostVector:
** In CLHEP there is no checking, either for 0 or for tachyonic
** case.  In ZOOM there is checking, which takes very little time.
** I think the zoom routine is therefore better, even though it is no longer
** appropriate to inline it.
	CHANGELOG

** Rotation methods:
** Again we should separate methods that force the load of the Rotation class.
** For practical purposes, that implies that methods like rotate() are no
** longer inline, and that as in the ThreeVector class we separate the .cc
** files.  Also, again we have the rotation methods returning
** HepLorentzVector& rather than void, so things can be chained.

** Boost methods:
** We have the rotation methods returning HepLorentzVector& rather than void,
** so things can be chained.  Also, we feel the boost methods along an axis,
** boostZ in particular, reall ought to be in the main part of the header.
** ZOOM does several checks to see that the bosot vector is not tachyonic.
** Here, we will forego these and use the CLHEP implementations.

** Methods acting on containers of LorentzVectors:
** This is present in ZOOM, for example,
** 	list<LorentzVector> s; double m = s.invariantMass();
** At least for now, we will omit this, so as not to introduce template
** complications into CLHEP.  If necessary, we can put this back in the
** LorentzVector.h file in the ZOOM area that typedefs LorentzVector from
** HepLorentzVector.

** Physical design to avoid unnecessary loading of Rotation modules:
** As per the Hep3Vector class, we split off almost all the implementations
** of the new ZOOM features so a "pure" CLHEP user gets no more code loaded
** that previously.  And as in that case, we split the ZOOM implementations
** among several .cc files. Also, we split out the implementations of features
** originally in CLHEP which would "drag in" Rotation.cc, and which would
** force loading of LorentzRotation.cc.  Thus the implementation files are:
**	LorentzVector.cc	original CLHEP
**	LorentzVectorR.cc	methods possibly involving HepRotation
**	LorentzVectorL.cc	original CLHEP involving HepLorentzRotation
**	LorentzVectorC.cc	comparison operations from ZOOM
**	LorentzVectorK.cc	relativistic kinematics from ZOOM
**	LorentzVectorB.cc	boosts and rotations from ZOOM, not involving
**				HepRotation or HepLorentzRotation

** Unit axial 4-vectors:
** We provide X_HAT4, Y_HAT4, Z_HAT4, T_HAT4 as statics, in the header.
** We use the inline constructor in original CLHEP to avoid the need to pull
** in additional code.

- - -

inline HepLorentzVector(double, const Hep3Vector &);

operator /= (Hepdouble c)
operator /  (const LorentzVector & v, Hepdouble c)

inline bool isSpacelike() const;
inline bool isTimelike() const;
inline bool isLightlike(Scalar epsilon=tolerance) const;


- - -


------------
SpaceVector
------------

** Namespace:
** Hep3Vector is not enclosed in a namespace.  SpaceVector is; but most of our
** users currently disable namespaces at this point.  I enclose the typedef
** defining SpaceVector in namespace zmpv, and leave Hep3Vector bare.  I would
** like to use that as the pattern:  Any new concept is placed in zmpv, all
** existing ones remain in ::.  That would be awkward, for example
** ZMpvDEGREES_t is used directly now in Hep3Vector.  But I do go the
** necessary distance:  Possibly conflicting symbols such as DEGREES are put
** in the zmpv namespace.

	Needs further correction:  See "ZOOM classes" above.

** R, rho confusion:
** CLHEP, --IN COMMENTS ONLY-- refers to the radius in spherical
** coordinates as rho, and the distance from the Z axis in
** cylindrical coordinates as R.  ZOOM uses the oppopsite names, and
** in fact uses these names in method names.  I have altered the CLHEP
** comments to make the nomenclature consistent; the meanings are still
** clear from the comments.  For example:
	inline double perp() const;
	// The transverse component (R in cylindrical coordinate system).
		CHANGELOG

** Use of UnitVector:
** At first, I thought that we should keep UnitVector for its efficiency
** benefits.  On further inspection, I noticed that these benefits are
** small, and that having UnitVector inherit from SpaceVector (with non-
** virtual methods) is unwise.  So I will eliminate UnitVector, which
** has the benefit of reducing interface bloat as well.  If any Fermilab
** users rely on UnitVector, I may have to add a UnitVector class; but
** Hep3Vector (and HepRotation) will not rely on UnitVector.

** The name angle and theta:
** These are synonmous.  So why not drop one?  Well, even if I said let's
** use the CLHEP form, CLHEP has theta for angle wrt z axis, and angle for
** angle wrt an arbitrary direction.

** Use of AxisAngle and EulerAngles:
** These class are very useful and simple structures for holding the result
** of a nice intuituve decomposition of a rotation:  Axis, and how far to
** rotate, or the three EUler angles.  They are worth retaining.

** EulerAngles conventions:
** ZOOM Rotations know about EulerAngles.  CLHEP does not.  We are faced with
** some options:  (1) set up a static variable to indicate choice of EA
** convention -- HORRIBLE.  (2) Change to some other convention and strand
** any existing ZOOM users -- Unacceptable.  (3) Leave things the way they
** are, and later we can provide conversion routines to go to other EA
** conventions.  (3) looks right.  Later, we could define HepAeroEAs for
** example, with conversion constructors to/from HepEulerAngles.

** Hep3Vector knows about HepRotation:
** In PhysicsVectors, there is a heirarchy in which vectors do not know about
** rotations.  The methods transform(const HepRotation &) and
** *=(const HepRotation &) break this heirarchy.  Thus ANY CLHEP PROGRAM
** THAT USES Hep3Vector MUST LINK IN hepRotation!!  This is not desirable.
** I shouldn't "fix" this by eliminating transform from CLHEP.  Instead I
** will break apart ThreeVector.cc, putting the Rotation methods in their
** own little file.  ThreeVectorR.cc If the user uses Hep3Vectors but not
** rotations, he then won't pull everything in.
		CHANGELOG

** Hep3Vector::rotate signatures:
** For equivalent rotate() methods, ZOOM takes (axis, delta) where
** CLHEP takes (delta, axis).  THere is no harm in leaving this alone.

** Return types for rotateX, rotateY, rotateZ (void in CLHEP)
** CLHEP and PhysicsVectors each have these three methods, and they are
** identical except that the ZOOM version returns a reference to *this.
** This is convenient for certain chained operations, and costs nothing;
** I don't wish to break ZOOM user code for zero reason, so I have made
** the CLHEP method conform to this convention.  There are a couple of other
** methods, rotate and rotateUz, whith the same void return type but since
** these methods or signatures don't appear in the original ZOOM classes,
** I leave the return type alone.

** Hep3Vector::rotate inefficient:
** CLHEP has implemented a rotate() method on a 3-vector in a very
** inefficent way, first forming an identity Rotation, then rotating that
** by axis and angle (in itself quite a task) then douing vector *= rotation.
** For now, I leave this alone -- people are of course free to use the ZOOM
** signature axis, delta which I believe will be much faster.  The speed
** advantage of the ZOOM routines is decreased a bit because we no longer
** provide the form where axis is a known UnitVector.

** Additional methods and physical coupling:
** Were we to merely put all the new SpaceVector methods into ThreeVector.h,
** then anybody using the class would pull in all that additional code.
** instead, we break the implementations up into several new files:
** The polar/azimuthal decomposition methods 		SpaceVectorD.cc
** All new methods involving rotation   		SpaceVectorR.cc
** Other new intrinsic and relative properties		SpaceVectorP.cc
** All other new methods (constructors, nearness, ...)	SpaceVector.cc

** operator *= with a Rotation:
** Another case where ZOOM decided it was too ambiguous, and CLHEP has
** just decided which way to read it.  Here, things are not that bad:
** C++ semantics leads you to expect v = M*v and that is what is done.  OK.
	OOPS, NOT OK.  C++ semantics leads you to expect v = v*M but the
	code does v = M*v (which is what physics would lead you to expect!!


** ZMthrow:
** PhsyicsVectors is set up for use of the Exceptions package.  Though we
** are directed not to use it wuite yet, I am not giving up on it eventually
** being in use; it has advantages.  For now, I leave the ZMthrows in, but
** substitute for ZMthrow.h and ZMxpv.h macros which turn these into cerr<<
** lines like the others in Vector.  Also, I introduce a macro ZMthrowC which
** I use wherever it seems exiting is too strong an action after reporting
** the problem, and a sensible Continuation is possible.  Once Exceptions
** are incorporated into Vector (if ever) ZMthrowC may eventually be #defined
** as ZMthrow since the Exceptions mechanism can do the ignoring for us.

** Ambiguous angles:
** CLHEP often, when faced with an ambiguous angle such as the cosing of the
** angle between vector v and a zero vector, simply returns 1.  ZOOM had
** issued a ZMthrow, and returns 1.  This was OK because a user could set
** up to ignore the ZMthorw.  We can live with the CLHEP choice on those
** routines already in CLHEP.  For some that are not originally in CLHEP,
** such as cos2Theta, we leave the ZOOM behavior intact.

** SetTheta inline:
** I disagree with setTheta and setMag() etc. being inline (too much logic)
** but I won't press the issue.

** Names of AxisAngle and EulerAngles
** Should I change these to HepAxisAngle etc?  I have decided to do so:
** the names are unique enough that I am not too worried about clashes,
** but I would have trouble getting the namespace placement right if
** there were no version in the global namespace.  The AxisAngle and
** EulerAngles classes are also placed in the zmpv namespace.


- - -


Items added to the "main" part of the interface (above the esoteric area):

set (x,y,x):  Moved into main part.
		CHANGELOG

setEta, setCylTheta, setCylEta:  NO synonyms; I put these up into main part.
		CHANGELOG

operator / (double)  :  Added to main part.
		CHANGELOG

operator /= :  Added to main part.
		CHANGELOG

isNear:	I have put isNear in the main section, because it is quite useful
	at least to our users.  I use the simplest and quickest forms for
	isNear and all related routines; contortions to account for the
	possibility of components being greater than 10**75 are silly.
	Similarly, I put HowNear and DeltaR into the main section.
		CHANGELOG

cos2Theta: against the z axis, placed in main part next to cosTheta().
		CHANGELOG


et2, et: I have included transverse energy/

- - -


Polar constructors:  We add the 8 varieties of polar and cylindrical
	constructors.  We keep the microtypes.h file to be able to
	distinguish these.

getX getY getZ:  Synonyms.

getR:  Synonym for mag.    Inline in CLHEP, and we go that way too.

getTheta getPhi:  not quite Synonnyms:  CLHEP Checks for invalid cases in
	a different way.  However, behavior of atan2 is adequate for CLHEP
	check to be OK.  Therefore make synonymous.

getRho(), rho:  Synonym for perp()

getEta, eta:  Synonym for pseuoRapidity.

setR:  Synonym for setMag().  I disagree with setR, setTHeta, etc being
	inline, but I won't press the issue.

Triple setters:  Put among the new constructors.

setCyl and setCyl using Eta:  Put into the esoteric constructors area even
	though no constructor corresponds to these.

operator+, -, scalar *:  These are done as non-friends, in the .icc file,
	utilizing the inline access methods.  That is fine, except it would
	be nice to be able to see them when looking at the header.  I
	would add those declarations, but because of the  HEP_DEBUG_INLINE
	complication that is awkward, and less necessary.

operator scalar /:  Not present; I will add to the header, as a non-inline
	only.

compare, operator>, etc:  Added to esoteric section

howNear, deltaR, get and set tolerance:  added to Esoteric section.
	I have put isNear in the main section, because it is quite useful
	at least to our users.

isParallell, howOrthogonal, etc.:  added to Esoteric section.

v1*v2:  ZOOM decided this was too ambiguous.  However, given that CLHEP
	mad a choice, we can embrace that choice.   CLHEP already has
	v1.dot(v2) so we need not add that synonym.

beta:  Synonym for mag.

gamma, collinearRapidity:
rapidity:  Put these into the section with reference direction.

angle:	Synonym for theta() in the z form.  angle(v) is already present
	in main part.  So is theta().  SpaceVector and UnitVector are
	separate in principle, bit for angle(u) the improvement in speed
	iss too small to be worth it, so we eliminate the Unit signature.

cosTheta:  against the z axis, already present in main part.

cos2Theta: against the z axis, placed in main part.

project, perp, perpPart:  Missing ones are in esoteric.
	The following already had 3-vector forms in CLHEP:
		perp(v) 	perp2(v)

polar decompostion: In the form relative to a reference direction, since the
	direction is now supplied as a 3-vector (not a UnitVector) we needed
	to modify that code.

	TODO: Modify decomposition code.

rotationOf and related friends:  These need not be friends.  Nor,
	given the time taken to rotate, need they be inline.  Move to
	global methods section.

How do I get PI?
        I use CLHEP::pi which is available in CLHEP/Units/PhysicalConstants.h

X_HAT, Y_HAT, Z_HAT:
	put as static const Hep3Vector in the .h file.


TODO:  Rotation
TODO:  LorentzTransformation