gov.sns.xal.model.alg
Class EnvTrackerAdapt

java.lang.Object
  |
  +--gov.sns.xal.model.alg.Tracker
        |
        +--gov.sns.xal.model.alg.EnvTrackerAdapt

All Implemented Interfaces:

IAlgorithm, IArchive, java.rmi.Remote

public class EnvTrackerAdapt

extends Tracker

Tracking algorithm for EnvelopeProbe's. The EnvelopeProbe's state, which is a CorrelationMatrix object, is advanced using the linear dynamics portion of any beamline element (IElement exposing object) transfer map. The linear portion is represented as a matrix, thus, the state advance is accomplished with a transpose conjugation with this matrix. The effects of space charge are also included in the dynamics calculations. Space charge effects are also represented with a matrix transpose conjugation, however, the matrix is computated using the values of the probe's correlation matrix. The result is a nonlinear effect. The space charge forces are computed using a linear fit to the fields generated by an ellipsoidal charge distribution with the same statistics described in the probe's correlation matrix. The linear fit is weighted by the beam distribution itself, so it is more accurate in regions of higher charged density. For a complete description see the reference below. This algorithm uses a second-order accurate, adaptive step sizing algorithm where the step size is continually adjusted to maintain an given error tolerance in the residual.

See Also:

EllipsoidalCharge, Theory and Technique of Beam Envelope Simulation

Field Summary

static int	ACCUR_ERROR Error condition in integration accuracy
static int	ACCUR_ORDER1 1st order accurate integration algorithm
static int	ACCUR_ORDER2 2nd order accurate integration algorithm
static int	ACCUR_RANGE Range of avaible integration accuracies
static java.lang.String	ATTRTAG_ERRTOL attribute label for error tolerance
static java.lang.String	ATTRTAG_INITSTEP attribute label for initial step size
static java.lang.String	ATTRTAG_MAXITER attribute label for maximum iteration count
static java.lang.String	ATTRTAG_MAXSTEP attribute label for maximum step size
static java.lang.String	ATTRTAG_NORM attribute label for residual norm
static java.lang.String	ATTRTAG_ORDER attribute label for order of accuracy in algorithm
static java.lang.String	ATTRTAG_SLACK attribute label for slack tolerance
static java.lang.String	NODETAG_ADAPT data node label for EnvTrackerAdapt settings
static int	NORM_L1 l-1 norm
static int	NORM_L2 l-2 norm
static int	NORM_LINF l-infinity norm
static java.lang.Class	s_clsProbeType probe type recognized by this algorithm
static int	s_intVersion current algorithm version
static java.lang.String	s_strTypeId string type identifier for algorithm

Fields inherited from class gov.sns.xal.model.alg.Tracker

ATTRTAG_DEBUG, ATTRTAG_TYPE, ATTRTAG_UPDATE, ATTRTAG_VER, CALC_RFGAP_PHASE, NODETAG_ALG, NODETAG_TRACKER, NODETAG_TRAJ, UPDATE_ALWAYS, UPDATE_CUSTOM, UPDATE_ENTRANCE, UPDATE_ENTRANCEANDEXIT, UPDATE_EXIT

Constructor Summary

EnvTrackerAdapt()
Creates a new instance of EnvTrackerAdapt

Method Summary

void	doPropagation(IProbe ifcProbe, IElement elem) Propagates the probe through the element using a second-order accurate adaptive step size algorithm for space charge calculations.
int	getAccuracyOrder() Get the current accuracy order of the space charge stepping algorithm.
double	getErrorTolerance() Return the acceptable tolerance in the residual error between a full step and two half steps.
int	getMatrixNorm() Get the type of Lebesque norm used for matrices.
int	getMaxIterations() Return the maximum allowable number of steps to progate a probe through an element.
double	getMaxStepSize() Return the maximum allowable step size.
double	getSlackTolerance() Step size adjustment slack tolerance.
double	getStepSize() Return the current step size.
void	load(DataAdaptor daptArchive) Load the parameters of the algorithm from a data source exposing the IArchive interface.
void	save(DataAdaptor daptArchive) Save the settings particular to this subclass of Tracker.
void	setAccuracyOrder(int intOrder) Set the integration accuracy order for the underlying stepping algorithm.
void	setErrorTolerance(double dblErr) Set the acceptable error in the residual correlation matrix.
void	setMatrixNorm(int enmNorm) Set the type of Lebesque norm used in the matrix calculations.
void	setMaxIterations(int intMaxIter) Sets the maximum allowable number of steps to progate a probe through an element.
void	setMaxStepSize(double dblMaxStep) Set the maximum allowable step size.
void	setSlackTolerance(double dblSlack) Set the slack size in the adaptive step size determination.
void	setStepSize(double dblStepSize) Set the initial step size for applying space charge corrections.

Methods inherited from class gov.sns.xal.model.alg.Tracker

advanceProbe, getArchive, getDebugMode, getElemPosition, getProbeUpdatePolicy, getStartElementId, getStopElementId, getType, getVersion, initialize, propagate, registerProbeType, setDebugMode, setElemPosition, setProbeUpdatePolicy, setStartElementId, setStopElementId, unsetStartElementId, unsetStopElementId, useRfGapPhaseCalculation, validElement, validProbe

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NORM_LINF

public static final int NORM_LINF

l-infinity norm

See Also:

Constant Field Values

NORM_L1

public static final int NORM_L1

l-1 norm

See Also:

Constant Field Values

NORM_L2

public static final int NORM_L2

l-2 norm

See Also:

Constant Field Values

ACCUR_ERROR

public static final int ACCUR_ERROR

Error condition in integration accuracy

See Also:

Constant Field Values

ACCUR_ORDER1

public static final int ACCUR_ORDER1

1st order accurate integration algorithm

See Also:

Constant Field Values

ACCUR_ORDER2

public static final int ACCUR_ORDER2

2nd order accurate integration algorithm

See Also:

Constant Field Values

ACCUR_RANGE

public static final int ACCUR_RANGE

Range of avaible integration accuracies

See Also:

Constant Field Values

s_strTypeId

public static final java.lang.String s_strTypeId

string type identifier for algorithm

See Also:

Constant Field Values

s_intVersion

public static final int s_intVersion

current algorithm version

See Also:

Constant Field Values

s_clsProbeType

public static final java.lang.Class s_clsProbeType

probe type recognized by this algorithm

NODETAG_ADAPT

public static final java.lang.String NODETAG_ADAPT

data node label for EnvTrackerAdapt settings

See Also:

Constant Field Values

ATTRTAG_ORDER

public static final java.lang.String ATTRTAG_ORDER

attribute label for order of accuracy in algorithm

See Also:

Constant Field Values

ATTRTAG_MAXSTEP

public static final java.lang.String ATTRTAG_MAXSTEP

attribute label for maximum step size

See Also:

Constant Field Values

ATTRTAG_INITSTEP

public static final java.lang.String ATTRTAG_INITSTEP

attribute label for initial step size

See Also:

Constant Field Values

ATTRTAG_ERRTOL

public static final java.lang.String ATTRTAG_ERRTOL

attribute label for error tolerance

See Also:

Constant Field Values

ATTRTAG_SLACK

public static final java.lang.String ATTRTAG_SLACK

attribute label for slack tolerance

See Also:

Constant Field Values

ATTRTAG_NORM

public static final java.lang.String ATTRTAG_NORM

attribute label for residual norm

See Also:

Constant Field Values

ATTRTAG_MAXITER

public static final java.lang.String ATTRTAG_MAXITER

attribute label for maximum iteration count

See Also:

Constant Field Values

Constructor Detail

EnvTrackerAdapt

public EnvTrackerAdapt()

Creates a new instance of EnvTrackerAdapt

Method Detail

setAccuracyOrder

public void setAccuracyOrder(int intOrder)

Set the integration accuracy order for the underlying stepping algorithm. For example, when using a second-order accurate algorithm the residual error is of the order h^2 where h is the step size.

Parameters:

intOrder - integration order

setMaxStepSize

public void setMaxStepSize(double dblMaxStep)

Set the maximum allowable step size. If this value is set then the step sizing algorithm will never generate steps larger than the provided value regardless of the residual error. If this value is cleared to zero, then the step size is unbound.

Parameters:

dblMaxStep - maximum allowable step size in meters

setMaxIterations

public void setMaxIterations(int intMaxIter)

Sets the maximum allowable number of steps to progate a probe through an element. If the number of steps increases beyond this number a race condition is assumed and an exception is thrown during the propagation. If the value is zero then no maximum step count is enforced.

Parameters:

intMaxIter - maximum alllowable single-element step count

setErrorTolerance

public void setErrorTolerance(double dblErr)

Set the acceptable error in the residual correlation matrix. The residual correlation matrix is determined by going a full step, then two half step and taking the difference in the resulting correlation matrices. The step size is continually adjusted to keep the resulting residual error at or about this given tolerance value. Thus, yeild a more accurate solution however they also result in small step sizes.

Parameters:

dblErr - acceptable residual error

setSlackTolerance

public void setSlackTolerance(double dblSlack)

Set the slack size in the adaptive step size determination. That is, if the suggested new step size differs only by this percentage, then no action is taken. Explicitly, if the new step size lies in the interval [h-dblSlack, h+dblSlack], then nothing is done. This feature prevents excessive micro-management of the step size.

Parameters:

dblSlack - size of the slack region in meters

setStepSize

public void setStepSize(double dblStepSize)

Set the initial step size for applying space charge corrections. Note that the step size will be modified as the algorithm progresses according to the adaptation rule.

Parameters:

dblStepSize - initial step size in meters

setMatrixNorm

public void setMatrixNorm(int enmNorm)

Set the type of Lebesque norm used in the matrix calculations.

Parameters:

enmNorm - enumeration constant of family EnvTrackerAdapt.NORM_*

getAccuracyOrder

public int getAccuracyOrder()

Get the current accuracy order of the space charge stepping algorithm.

Returns:

order of the integration algorithm accuracy

See Also:

setAccuracyOrder(int)

getStepSize

public double getStepSize()

Return the current step size.

Returns:

the current step size in meters

getMaxStepSize

public double getMaxStepSize()

Return the maximum allowable step size. The step sizing aglorithm is bound by this value, or unbounded if zero.

Returns:

maximum allowable step size in meters

getMaxIterations

public int getMaxIterations()

Return the maximum allowable number of steps to progate a probe through an element. If the number of steps increases beyond this number a race condition is assumed and an exception is thrown during the propagation. If the value is zero then no maximum step count is enforced.

Returns:

maximum alllowable step count while propagating thru a single element

getErrorTolerance

public double getErrorTolerance()

Return the acceptable tolerance in the residual error between a full step and two half steps.

Returns:

tolerable residual error

getSlackTolerance

public double getSlackTolerance()

Step size adjustment slack tolerance. If adjustments in the step size are less than this percentage, we do nothing.

Returns:

size of the slack region in meters

getMatrixNorm

public int getMatrixNorm()

Get the type of Lebesque norm used for matrices.

Returns:

0 for l-inf norm, 1 for l-1 norm, 2 for l2 norm

doPropagation

public void doPropagation(IProbe ifcProbe,
                          IElement elem)
                   throws ModelException

Propagates the probe through the element using a second-order accurate adaptive step size algorithm for space charge calculations. The new probe state is first computed by taken a full step with the second- order accurate transfer matrix with includes space charge effect. The algorithm then computes the new probe state by taking two half-steps. The residual error (correlation matrix) between the two states is computed. If the norm of the matrix is below the error tolerance (@see #getErrorTolerance) the step may be lengthened. If the residual error is greater than tolerance the step size must be shortened and the new probe state recomputed.

Specified by:

doPropagation in class Tracker

Parameters:

elem - element acting on probe

ifcProbe - probe to propagate

Throws:

ModelException - invalid probe type or error in advancing probe

See Also:

Tracker.advanceProbe(gov.sns.xal.model.IProbe, gov.sns.xal.model.IElement, double), Tracker.validProbe(gov.sns.xal.model.IProbe)

load

public void load(DataAdaptor daptArchive)
          throws DataFormatException

Load the parameters of the algorithm from a data source exposing the IArchive interface. The superclass load method is called first, then the properties particular to EnvTrackerAdapt are loaded.

Specified by:

load in interface IArchive

Overrides:

load in class Tracker

Parameters:

daptArchive - data source containing algorithm configuration

Throws:

DataFormatException - malformatted algorithm data

See Also:

gov.sns.tools.data.IArchive#load(gov.sns.tools.data.DataAdaptor)

save

public void save(DataAdaptor daptArchive)

Save the settings particular to this subclass of Tracker. The superclass save method is called first, then the properties particular to EnvTrackerAdapt are saved.

Specified by:

save in interface IArchive

Overrides:

save in class Tracker

Parameters:

daptArchive - data sink exposing IArchive interface

See Also:

gov.sns.tools.data.IArchive#save(gov.sns.tools.data.DataAdaptor)