Package xal.tools.beam

Class PhaseMap

java.lang.Object
xal.tools.beam.PhaseMap
All Implemented Interfaces:
IArchive
public class PhaseMap extends Object implements IArchive

Represents a generalized map between homogeneous phase space coordinates. Note that it does not necessarily need to be symplectic.

Currently the action of the map, denoted φ, simply consists of a linear portion plus an offset. Second order effects are to be designed and implemented in the future.

The action of the linear map φ0 : R6 × {1} → R6 × {1} on a phase vector z ∈ R6 × {1} is given by

    φ0(z) = Φ0 ⋅ (z - z0) + Δ0 ,

where Φ0 ∈ R7×7 is the linear part of the map (a matrix representation), z0 is the evaluation point or center, and Δ0 is the value or offset of the mapping. Note that φ0 : z0 → φ0, that is, z0 is the location of the linear expansion of the map φ0 and Δ0 is the value there.

The above representation is in direct correlation with the Taylor expansion of a continuous map F0 ∈ C(R6×{1} → R6×{1}). Say we wish to expand F0 about the point z0 ∈ R6. The Taylor expansion of F0 at the point z ∈ R6 is given by

    F0(z) = F(z0) + F0'(z0) ⋅ (z - z0) + O(||z - z0||2) ,

where F0'(z0) is the matrix of first partial derivatives of F evaluated at the point z0 ∈ R6×{1}. By identifying z0, Δ0, and Φ0 with z0, F0(z0), and F0'(z0), respectively, we arrive at our Taylor map representation for this class as seen by definition of φ0.

Hopefully, this interface should be general enough so that when a consensus is reached as to represent higher-order effects of the transfer map, the implementation can be supported here.

Since:
Mar 26, 2003
Version:
Nov 1, 2013
Author:
Christopher K. Allen

  • Field Details

  • Constructor Details

    • PhaseMap

      public PhaseMap()
      Creates a new instance of PhaseMap. Creates the identity map centered at 0 ∈ R6×{1}.

    • PhaseMap

      public PhaseMap(PhaseVector vecDispl)
      Create a new instance of PhaseMap which behaves as simple translation in phase space given by the specified displacement vector.
      Parameters:
      vecDispl - displacement in the range of the phase map, or Δ0

    • PhaseMap

      public PhaseMap(PhaseMatrix matTrans)
      Create a new instance of PhaseMap which behaves as a linear transform given by the specified matrix.
      Parameters:
      matTrans - linear portion of the phase map, specifically Φ0

    • PhaseMap

      public PhaseMap(PhaseVector vecCntr, PhaseVector vecDspl, PhaseMatrix matLin)
      Initializing constructor for PhaseMap class. Sets the map center z0, the map offset Δ0, and the map linear part Φ0 to the given quantities, respectively.
      Parameters:
      vecCntr - point in map domain unaffected by map action
      vecDspl - the image of the map center
      matLin - linear part of the map around the map center point
      Since:
      Nov 4, 2013

    • PhaseMap

      public PhaseMap(PhaseMap mapParent)
      Copy constructor for PhaseMap. Creates a new, deep copy of the given PhaseMap object.
      Parameters:
      mapParent - parent map to clone
      Since:
      Nov 4, 2013

  • Method Details

    • identity

      public static PhaseMap identity()
      Create an identity phase map
      Returns:
      identity map for phase space

    • copy

      public PhaseMap copy()
      Make a deep copy of this phase map.
      Returns:
      a cloned copy of this phase map

    • setFrom

      public void setFrom(PhaseMap map)
      Set this map to copy the specified map.
      Parameters:
      map - the map from which to copy this map's settings.

    • setDomainCenter

      public void setDomainCenter(PhaseVector vecDomCntr)
      Set the map's domain center, or z0 in the notation of the class documentation. The given vector is copied rather than referenced and, thus, unchanged.
      Parameters:
      vecDomCntr - the point z0 in phase space about which the map is expanded
      Since:
      Nov 4, 2013

    • setRangeDisplace

      public void setRangeDisplace(PhaseVector vecRngDspl)
      Set the map's offset in the range, this is the quantity Δ0 in the class documentation. The given vector is copied rather than referenced and, thus, unchanged.
      Parameters:
      vecRngDspl - the displacement Δ0 ∈ Rng{φ0} of the map

    • setLinearPart

      public void setLinearPart(PhaseMatrix matPhi)
      Set the linear part of the map, this is the matrix Φ0 in the notation of the class documentation. The given matrix is copied rather than referenced and, thus, left unchanged.
      Parameters:
      matPhi - linear portion Φ0 of phase map φ0

    • save

      public void save(DataAdaptor daptArchive)
      Save the value of this PhaseMatrix to a data sink represented by the DataAdaptor interface.
      Specified by:
      save in interface IArchive
      Parameters:
      daptArchive - interface to data sink
      See Also:

    • load

      public void load(DataAdaptor daptArchive) throws DataFormatException, IllegalArgumentException
      Restore the value of the this PhaseMatrix from the contents of a data archive.
      Specified by:
      load in interface IArchive
      Parameters:
      daptArchive - interface to data source
      Throws:
      DataFormatException - malformed data
      IllegalArgumentException - wrong number of string tokens
      See Also:

    • getDomainCenter

      public PhaseVector getDomainCenter()
      Returns the map center in its domain. This is the quantity z0 in the class documentation.
      Returns:
      returns the point in the domain where the map has no action (only displacement)
      Since:
      Nov 4, 2013

    • getRangeDisplace

      public PhaseVector getRangeDisplace()
      Get the map offset in the range, the vector Δ0 in the class documentation.
      Returns:
      the point Δ0 ∈ Rng{φ0} that is the image of the center z0.

    • getFirstOrder

      public PhaseMatrix getFirstOrder()
      Get the linear portion of the map, this is the quantity Φ0 in the class documentation.
      Returns:
      linear part of map φ0 given by Φ0 ≡ ∂φ0/∂z evaluated at z0 in Dom{φ0}

    • inverse

      public PhaseMap inverse()

      Compute and return the inverse map φ-1 of this map φ. By inverse map we mean that the composition φ-1 ⋅ φ is the identity map id : z → z on R6×{1}.

      Consider linear maps φ defined according to the class documentation

          φ(z) = Φ ⋅ (z - z0) + Δ0 ,

      where Φ ∈ R7×7 is the linear part of the map (a matrix representation), z0 is the evaluation point or center, and Δ0 is the value or offset of the mapping. Then the inverse map φ-1 : R6×{1} → R6×{1} is given by

          φ-1(y) = Φ0-1 ⋅ (y - Δ0) + z0 ,

      which can be derived by solving the equation φ(z) = y for y.

      Returns:
      a new map which is the inverse of this map.

    • compose

      public PhaseMap compose(PhaseMap mapRight)

      Non-destructive map composition - binary composition of two PhaseMaps. Let φ1 denote the given map and φ2 denote this map; that is, φ2 ≡ φthis. Referring to the class documentation PhaseMap, the composition φ ≡ φ2 ⋅ φ1 is determined by its action on an element z ∈ R6×{1}

          φ(z) = φ2 ⋅ φ1(z) ,

                  = φ2 [ Φ1⋅(z - z1) + Δ1 - z2] ,

                  = Φ2⋅Φ1 (z - z1) + Φ2 ⋅ (Δ1 - z2) + Δ2

      where Φ1 and Φ2 are the linear parts (matrices) of maps φ1 and φ2, respectively, Δ1 and Δ2 are the (range) offsets of maps φ1 and φ2, respectively, and z1 and z2 are the (domain) centers of maps φ1 and φ2, respectively.

      Thus, the center z3, displacement Δ3, and linear part Φ3 of the new composite map φ3 ≡ φ2 ⋅ φ1 are respectively given by

          z3 = z1 ,

          Δ3 = Φ2 ⋅ (Δ1 - z2) + Δ2 ,

          Φ3 = Φ2 ⋅ Φ1 ,

      The above equations are the formulas for the returned map.

      Parameters:
      mapRight - right argument φ1 to map composition
      Returns:
      composition φ ≡ φ2 ⋅ φ1

    • composeEquals

      public void composeEquals(PhaseMap mapRight)
      In-place map composition, binary composition of two PhaseMap objects where this map This map φ2 is replaced by

          φ2 ← φ2 ⋅ φ1

      where φ1 the argument map. See method compose(PhaseMap) for details of the computation.
      Parameters:
      mapRight - right argument φ0 of map composition

    • apply

      public PhaseVector apply(PhaseVector vecIn)
      Apply this map to the given phase vector. Denoting the given phase vector as z, currently for the linear map φ the result is

          φ(z) = Φ ⋅ (z - z0) + Δ ,

      where z0 is the center of φ, Δ is the range offset of φ, and Φ is the linear part of φ.
      Parameters:
      vecIn - phase vector z
      Returns:
      the action of φ on input phase vector z