PhaseMap

java.lang.Object
- xal.tools.beam.PhaseMap

All Implemented Interfaces:

IArchive
```
public class PhaseMap
extends java.lang.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 φ₀ : R⁶ × {1} → R⁶ × {1} on a phase vector z ∈ R⁶ × {1} is given by

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

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

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

F₀(z) = F(z₀) + F₀'(z₀) ⋅ (z - z₀) + O(||z - z₀||²) ,

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

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

Field Summary

Fields
Modifier and Type	Field and Description
`static java.lang.String`	`ATTR_DATA` attribute marker for data
`static java.lang.String`	`LBL_2ND` label for second-order map component
`static java.lang.String`	`LBL_CNTR` label for the domain center component of the map
`static java.lang.String`	`LBL_DSPL` label for zero-order map component (offset)
`static java.lang.String`	`LBL_LIN` label for first-order map component
`static java.lang.String`	`LBL_THREE` label for third-order map component

Constructor Summary

Constructors
Constructor and Description
`PhaseMap()` Creates a new instance of `PhaseMap`.
`PhaseMap(PhaseMap mapParent)` Copy constructor for `PhaseMap`.
`PhaseMap(PhaseMatrix matTrans)` Create a new instance of PhaseMap which behaves as a linear transform given by the specified matrix.
`PhaseMap(PhaseVector vecDispl)` Create a new instance of `PhaseMap` which behaves as simple translation in phase space given by the specified displacement vector.
`PhaseMap(PhaseVector vecCntr, PhaseVector vecDspl, PhaseMatrix matLin)` Initializing constructor for `PhaseMap` class.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method and Description
`PhaseVector`	`apply(PhaseVector vecIn)` Apply this map to the given phase vector.
`PhaseMap`	`compose(PhaseMap mapRight)` Non-destructive map composition - binary composition of two PhaseMaps.
`void`	`composeEquals(PhaseMap mapRight)` In-place map composition, binary composition of two `PhaseMap` objects where this map This map φ₂ is replaced by φ₂ ← φ₂ ⋅ φ₁ where φ₁ the argument map.
`PhaseMap`	`copy()` Make a deep copy of this phase map.
`PhaseVector`	`getDomainCenter()` Returns the map center in its domain.
`PhaseMatrix`	`getFirstOrder()` Get the linear portion of the map, this is the quantity Φ₀ in the class documentation.
`PhaseVector`	`getRangeDisplace()` Get the map offset in the range, the vector Δ₀ in the class documentation.
`static PhaseMap`	`identity()` Create an identity phase map
`PhaseMap`	`inverse()` Compute and return the inverse map φ^-1 of this map φ.
`void`	`load(DataAdaptor daptArchive)` Restore the value of the this `PhaseMatrix` from the contents of a data archive.
`void`	`save(DataAdaptor daptArchive)` Save the value of this `PhaseMatrix` to a data sink represented by the `DataAdaptor` interface.
`void`	`setDomainCenter(PhaseVector vecDomCntr)` Set the map's domain center, or z₀ in the notation of the class documentation.
`void`	`setFrom(PhaseMap map)` Set this map to copy the specified map.
`void`	`setLinearPart(PhaseMatrix matPhi)` Set the linear part of the map, this is the matrix Φ₀ in the notation of the class documentation.
`void`	`setRangeDisplace(PhaseVector vecRngDspl)` Set the map's offset in the range, this is the quantity Δ₀ in the class documentation.

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - LBL_CNTR
```
public static final java.lang.String LBL_CNTR
```
    label for the domain center component of the map
    
    See Also:
    
    Constant Field Values
  - LBL_DSPL
```
public static final java.lang.String LBL_DSPL
```
    label for zero-order map component (offset)
    
    See Also:
    
    Constant Field Values
  - LBL_LIN
```
public static final java.lang.String LBL_LIN
```
    label for first-order map component
    
    See Also:
    
    Constant Field Values
  - LBL_2ND
```
public static final java.lang.String LBL_2ND
```
    label for second-order map component
    
    See Also:
    
    Constant Field Values
  - LBL_THREE
```
public static final java.lang.String LBL_THREE
```
    label for third-order map component
    
    See Also:
    
    Constant Field Values
  - ATTR_DATA
```
public static final java.lang.String ATTR_DATA
```
    attribute marker for data
    
    See Also:
    
    Constant Field Values
- Constructor Detail
  - PhaseMap
```
public PhaseMap()
```
    Creates a new instance of PhaseMap. Creates the identity map centered at 0 ∈ R⁶×{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 Δ₀
  - 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 Φ₀
  - PhaseMap
```
public PhaseMap(PhaseVector vecCntr,
                PhaseVector vecDspl,
                PhaseMatrix matLin)
```
    Initializing constructor for PhaseMap class. Sets the map center z₀, the map offset Δ₀, and the map linear part Φ₀ 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 Detail
  - 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 z₀ in the notation of the class documentation. The given vector is copied rather than referenced and, thus, unchanged.
    
    Parameters:
    
    vecDomCntr - the point z₀ 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 Δ₀ in the class documentation. The given vector is copied rather than referenced and, thus, unchanged.
    
    Parameters:
    
    vecRngDspl - the displacement Δ₀ ∈ Rng{φ₀} of the map
  - setLinearPart
```
public void setLinearPart(PhaseMatrix matPhi)
```
    Set the linear part of the map, this is the matrix Φ₀ in the notation of the class documentation. The given matrix is copied rather than referenced and, thus, left unchanged.
    
    Parameters:
    
    matPhi - linear portion Φ₀ of phase map φ₀
  - 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:
    
    IArchive.save(xal.tools.data.DataAdaptor)
  - load
```
public void load(DataAdaptor daptArchive)
          throws DataFormatException,
                 java.lang.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
    
    java.lang.IllegalArgumentException - wrong number of string tokens
    
    See Also:
    
    IArchive.load(xal.tools.data.DataAdaptor)
  - getDomainCenter
```
public PhaseVector getDomainCenter()
```
    Returns the map center in its domain. This is the quantity z₀ 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 Δ₀ in the class documentation.
    
    Returns:
    
    the point Δ₀ ∈ Rng{φ₀} that is the image of the center z₀.
  - getFirstOrder
```
public PhaseMatrix getFirstOrder()
```
    Get the linear portion of the map, this is the quantity Φ₀ in the class documentation.
    
    Returns:
    
    linear part of map φ₀ given by Φ₀ ≡ ∂φ₀/∂z evaluated at z₀ in Dom{φ₀}
  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 R⁶×{1}.
  
  Consider linear maps φ defined according to the class documentation
  
  φ(z) = Φ ⋅ (z - z₀) + Δ₀ ,
  
  where Φ ∈ R^7×7 is the linear part of the map (a matrix representation), z₀ is the evaluation point or center, and Δ₀ is the value or offset of the mapping. Then the inverse map φ^-1 : R⁶×{1} → R⁶×{1} is given by
  
  φ^-1(y) = Φ₀^-1 ⋅ (y - Δ₀) + z₀ ,
  
  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 φ₁ denote the given map and φ₂ denote this map; that is, φ₂ ≡ φ_this. Referring to the class documentation PhaseMap, the composition φ ≡ φ₂ ⋅ φ₁ is determined by its action on an element z ∈ R⁶×{1}
  
  φ(z) = φ₂ ⋅ φ₁(z) ,
  
  = φ₂ [ Φ₁⋅(z - z₁) + Δ₁ - z₂] ,
  
  = Φ₂⋅Φ₁ (z - z₁) + Φ₂ ⋅ (Δ₁ - z₂) + Δ₂
  
  where Φ₁ and Φ₂ are the linear parts (matrices) of maps φ₁ and φ₂, respectively, Δ₁ and Δ₂ are the (range) offsets of maps φ₁ and φ₂, respectively, and z₁ and z₂ are the (domain) centers of maps φ₁ and φ₂, respectively.
  
  Thus, the center z₃, displacement Δ₃, and linear part Φ₃ of the new composite map φ₃ ≡ φ₂ ⋅ φ₁ are respectively given by
  
  z₃ = z₁ ,
  
  Δ₃ = Φ₂ ⋅ (Δ₁ - z₂) + Δ₂ ,
  
  Φ₃ = Φ₂ ⋅ Φ₁ ,
  
  The above equations are the formulas for the returned map.
  
  Parameters:
  
  mapRight - right argument φ₁ to map composition
  
  Returns:
  
  composition φ ≡ φ₂ ⋅ φ₁
  
  composeEquals
  
  public void composeEquals(PhaseMap mapRight)
  
  In-place map composition, binary composition of two PhaseMap objects where this map This map φ₂ is replaced by
  
  φ₂ ← φ₂ ⋅ φ₁
  
  where φ₁ the argument map. See method compose(PhaseMap) for details of the computation.
  
  Parameters:
  
  mapRight - right argument φ₀ 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 - z₀) + Δ ,
  
  where z₀ 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

Class PhaseMap

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

LBL_CNTR

LBL_DSPL

LBL_LIN

LBL_2ND

LBL_THREE

ATTR_DATA

Constructor Detail

PhaseMap

PhaseMap

PhaseMap

PhaseMap

PhaseMap

Method Detail

identity

copy

setFrom

setDomainCenter

setRangeDisplace

setLinearPart

save

load

getDomainCenter

getRangeDisplace

getFirstOrder

inverse

compose

composeEquals

apply