public abstract class CourantSnyderEstimator
extends java.lang.Object
Base class for the problem of reconstructing Courant-Snyder parameters from beam profile data at multiple locations along a beamline. This class provide common tools and attributes that child classes can share, as well as the ability to compute the zero-current solution.
Subclasses compute the covariance matrix σ from the given data at the given device
location. This is the set of second-order moments of the beam distribution. Since the
measurement data cannot show coupling between phase planes, the covariance matrix is
block diagonal where the 2×2 blocks correspond to each independent phase plane
(see
). If the measurement data is zero
for any phase plane, then the diagonal block corresponding to that phase plane is also zero.
CovarianceMatrix
The second-order moments are computed from and observation matrix which, in the zero current case, is independent of the initial state of the beam. The observation matrix relates the initial state (described by the second moments) to the observed quantities, in this case the measurement data of RMS beam sizes. For each phase plane: In the case were there are more data points than there are variables (i.e., greater than 3) then the returned solution is the least-squares solution; specifically, the set of moments that hits the most data. In the case where there are less data points than variables (i.e., less than 3) then the returned solution is the minimum norm (or "least energy") solution; specifically, the solution that has the smallest Lebesgue 2-norm. If we have 3 data points for the phase plane then the unique solution is returned.
Modifier and Type | Field and Description |
---|---|
protected boolean |
bolDebug
Toggle debugging output on/off - default is off
|
protected double |
dblConvErr
The last Convergence solution error
|
protected double |
dblResErr
The last recorded solution error
|
protected java.text.DecimalFormat |
fmtMatrix
The numeric format to use when printing out matrices to standard output
|
protected TransferMatrixGenerator |
genTransMat
Transfer matrix generation engine
|
protected CovarianceMatrix |
matCurrF
The last recorded recursion function value
|
protected CovarianceMatrix |
matCurrSigma
The last recorded moment solution
|
Constructor and Description |
---|
CourantSnyderEstimator(boolean bolDebug,
TransferMatrixGenerator genTransMat)
Creates a new
TwissObserverBase object using the given maximum iteration count,
maximum convergence error, and the given transfer matrix generator. |
CourantSnyderEstimator(TransferMatrixGenerator genTransMatrix)
Creates a new
TwissObserverBase object which uses the given transfer matrix
generator. |
Modifier and Type | Method and Description |
---|---|
protected double |
computeConvergenceError(CovarianceMatrix matSig1,
CovarianceMatrix matSig0)
Computes the norm of the distance between the given covariance solution
matrix and the last solution matrix.
|
protected Jama.Matrix |
computeObservationMatrix(PHASEPLANE plane,
java.lang.String strReconDevId,
java.util.ArrayList<Measurement> arrData)
Computes the observation matrix from the given data and accelerator node ID
of the reconstruction location.
|
Jama.Matrix |
computeObservationMatrix(java.lang.String strReconDevId,
java.util.ArrayList<Measurement> arrData)
Compute the observation matrix which yields the vector of beam moments at the given
beamline element from the set of beam size measurements provided in the argument.
|
CovarianceMatrix |
computeReconFunction(CovarianceMatrix matSig0,
double dblBnchFreq,
double dblBeamCurr,
java.lang.String strRecDevId,
java.util.ArrayList<Measurement> arrData)
Returns the recursion function for a finite current beam with the given beam charge for the
given beam state at the sequence start.
|
abstract CovarianceMatrix |
computeReconstruction(java.lang.String strRecDevId,
double dblBnchFreq,
double dblBmCurr,
java.util.ArrayList<Measurement> arrData)
Computes the covariance matrix at the given location which is most likely to produce the given
data.
|
protected Jama.Matrix |
computeReconSubFunction(PHASEPLANE plane,
java.lang.String strTargElemId,
java.util.ArrayList<Measurement> arrData)
Computes the σ vector from the observer matrix and the given data for the
given phase plane.
|
protected double |
computeResidualError(CovarianceMatrix matSigSoln,
java.lang.String strRecDevId,
java.util.ArrayList<Measurement> arrData)
Computes and returns the Lebesgue 2-norm of the error residual for
the given solution and problem data.
|
CovarianceMatrix |
computeZeroCurrReconFunction(java.lang.String strRecDevId,
java.util.ArrayList<Measurement> arrData)
Returns the recursion function for a zero-current beam at the given device location and
for the given profile measurement data.
|
double |
getReconConvergenceError()
Returns the convergence error for the last solution iteration, i.e., the distance between
the solution returned by
and the solution previous. |
double |
getReconResidualError()
Returns the residual error of the last solution, i.e., the solution returned by
. |
CovarianceMatrix |
getReconstruction()
Returns the current solution covariance matrix.
|
boolean |
isDebuggingOn()
Returns the value of the debugging flag.
|
void |
setDebug(boolean bolDebug)
Turn debugging output on or off.
|
protected boolean bolDebug
protected java.text.DecimalFormat fmtMatrix
protected final TransferMatrixGenerator genTransMat
protected double dblResErr
protected double dblConvErr
protected CovarianceMatrix matCurrSigma
protected CovarianceMatrix matCurrF
public CourantSnyderEstimator(TransferMatrixGenerator genTransMatrix)
TwissObserverBase
object which uses the given transfer matrix
generator.genTransMat
- a pre-configured transfer matrix engine used internally.public CourantSnyderEstimator(boolean bolDebug, TransferMatrixGenerator genTransMat)
Creates a new TwissObserverBase
object using the given maximum iteration count,
maximum convergence error, and the given transfer matrix generator. This constructor must
be used if Twiss parameters are to be computed in the presence of space charge
(see
).
#computeCovarianceFiniteCurrent(String, double, ArrayList)
cntMaxIter
- maximum number of allowed search iterationsdblMaxError
- maximum L2 convergence error in the solutiongenTransMat
- a pre-configured transfer matrix engine used internally.public abstract CovarianceMatrix computeReconstruction(java.lang.String strRecDevId, double dblBnchFreq, double dblBmCurr, java.util.ArrayList<Measurement> arrData) throws java.lang.Exception
Computes the covariance matrix at the given location which is most likely to produce the given data. That is, the covariance matrix is constructed at the given device location from the data provided and for the given beam current.
strRecDevId
- ID of the device where the reconstruction is to be performeddblBnchFreq
- bunch arrival frequency (in Hz)dblBmCurr
- beam current (in Amperes)arrData
- the profile measurement data used for the reconstructionjava.lang.Exception
- general error occurred during the reconstruction computationspublic void setDebug(boolean bolDebug)
bolDebug
- true
to enable debugging output or false
to turn it offpublic boolean isDebuggingOn()
true
if the class is in the debugging state,
false
no debugging information is being generatedpublic CovarianceMatrix getReconstruction()
Returns the current solution covariance matrix. This matrix is useful if an iterative solution algorithm was used (e.g., for the finite space charge) and it did not converge. The returned value is then the last value of the solution before the algorithm was terminated.
public double getReconResidualError()
Returns the residual error of the last solution, i.e., the solution returned by
. The numerical value is the Frobenius norm
of the solution residual matrix.
getReconstruction()
public double getReconConvergenceError()
Returns the convergence error for the last solution iteration, i.e., the distance between
the solution returned by
and the solution previous.
The numerical value is the Frobenius norm
of the distance between iterates.
getReconstruction()
public CovarianceMatrix computeZeroCurrReconFunction(java.lang.String strRecDevId, java.util.ArrayList<Measurement> arrData) throws ModelException
#computeReconFunction(CovarianceMatrix, double, String, ArrayList)
for zero current and undefined initial beam moments.strRecDevId
- device ID where the Courant-Snyder parameters are being reconstructedarrData
- profile measurement data along beamlineModelException
- a general error occurred while computing the transfer matriciespublic CovarianceMatrix computeReconFunction(CovarianceMatrix matSig0, double dblBnchFreq, double dblBeamCurr, java.lang.String strRecDevId, java.util.ArrayList<Measurement> arrData) throws ModelException
computeReconSubFunction(PHASEPLANE, String, ArrayList)
simultaneously for all three phase planes as a covariance matrix. In this method, the
transfer matrices are explicitly computed for the given initial covariance matrix and the
given beam current.
The returned matrix is block diagonal
(and symmetric) containing the moments in the usual locations.matSig0
- beam covariance matrix at the accelerator sequence startdblChrg
- beam chargestrRecDevId
- device ID where the Courant-Snyder parameters are being reconstructedarrData
- profile measurement data along beamlineModelException
- a general error occurred while computing the transfer matriciespublic Jama.Matrix computeObservationMatrix(java.lang.String strReconDevId, java.util.ArrayList<Measurement> arrData) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException
Compute the observation matrix which yields the vector of beam moments at the given
beamline element from the set of beam size measurements provided in the argument. The
matrix is returned as a eMatrix
object so that matrices for all three phase planes
may be returned. Currently coupling between phase planes is not consided.
Thus, the returned matrix is block-diagonal having three 3n×9
matrices on the diagonal (where n is the number of data locations),
one for each phase plane, horizontal, vertical, diagonal, respectively.
strReconDevId
- String id of reconstruction elementarrData
- list of beam size measurement dataPhaseMatrix
containing the observation matrices for all 3 phase planesjava.lang.IllegalArgumentException
- unknown phase plane or unknown devicejava.lang.IllegalStateException
- transfer matrices have not been generatedprotected Jama.Matrix computeReconSubFunction(PHASEPLANE plane, java.lang.String strTargElemId, java.util.ArrayList<Measurement> arrData)
Computes the σ vector from the observer matrix and the given data for the
given phase plane. This
is the vector of second-order moments of the beam distribution. The returned value is
a 3×1 matrix of real numbers having the form
σ = ( <x2>, <xx'>, <x'2> )T
where the moments are taken from the horizontal plane. The vertical plane computation returns an
analogous set. The three phase planes are treated independently and solutions for each plane
returned separately.
In the case were there are more data points than there are variables (i.e., greater than 3) then the returned solution is the least-squares solution; specifically, the set of moments that hits the most data. In the case where there are less data points than variables (i.e., less than 3) then the returned solution is the minimum norm (or "least energy") solution; specifically, the solution that has the smallest Lebesgue 2-norm. If we have three data points then the unique solution is returned.
arrData
- Array List of Location Dataplane
- Phase plane for which to compute the observer matrixstrTargElemId
- reconstruction locationprotected Jama.Matrix computeObservationMatrix(PHASEPLANE plane, java.lang.String strReconDevId, java.util.ArrayList<Measurement> arrData) throws java.lang.IllegalArgumentException, java.lang.IllegalStateException
Computes the observation matrix from the given data and accelerator node ID of the reconstruction location.
plane
- Phase plane to calculate to considerstrReconDevId
- String id of reconstruction elementarrData
- list of beam size datajava.lang.IllegalArgumentException
- unknown phase plane or unknown devicejava.lang.IllegalStateException
- transfer matrices have not been generatedTransferMatrixGenerator.generateWithoutSpaceCharge()
,
TransferMatrixGenerator#generateWithSpaceCharge(String, double, CovarianceMatrix)
protected double computeResidualError(CovarianceMatrix matSigSoln, java.lang.String strRecDevId, java.util.ArrayList<Measurement> arrData)
matSigSoln
- solution matrix of second-order momentsstrRecDevId
- device ID where the reconstruction is performed (location of solution)arrData
- array of problem dataprotected double computeConvergenceError(CovarianceMatrix matSig1, CovarianceMatrix matSig0)
matSig1
- current solution iterate σi+1matSig0
- previous solution iterate σi