Low-level element pass functions ***************************************************************************** Each cell in THERING cell array represents a physical element such as drift or quadrupole magnet. The i-th element data is organized as 1-by-1 MATLAB 'structure'. This structure has a field THERING{i}.PassMethod that contains the actual name of the function to be called when propagating through this element with higher level routines such as RingPass or LinePass. For example in spear2 the first element in the ring is a drift 1.3448 m long: _________________________________________________________________________ >> THERING{1} ans = FamName: 'DR01' Length: 1.34480000000000 PassMethod: 'DriftPass' _________________________________________________________________________ 'DriftPass' is the name of the actual function on the MATLAB search path and it can be called from the command line or used in an m-script: _______________________________________________________________________ >>DriftPass(THERING{2}, [0 0.001 0 0 0 0]') ans = 0.00134480000000 0.00100000000000 0 0 0 0.00000067240000 _______________________________________________________________________ Accelerator Toolbox provides a number of low-level element pass functions. Each function propagates through an element assuming some physical model of that element. In the above example 'DriftPass' used the trivial solution of Hamiltonian equations in the field-free region. It is possible to call DriftPass on any other element type and thus treat it like a drift. For example a sextupole element structure contains fields that distinquish it from a drift such as multipole expansion of the field 'PolynomA','PolynomB' and misalignment data 'R1','R2','T1','T2' ________________________________________________________________________ » THERING{15} ans = FamName: 'SF' Length: 0.23335000000000 MaxOrder: 3 NumIntSteps: 10 R1: [6x6 double] R2: [6x6 double] T1: [0 0 0 0 0 0] T2: [0 0 0 0 0 0] PolynomA: [0 0 0] PolynomB: [0 0 1.67686888860000] PassMethod: 'StrSymplectic4Pass' ________________________________________________________________________ Still the Toolbox allows to model it as a drift of the same length: ________________________________________________________________ DriftPass(THERING{15},[0.01, 0.001, 0 0 0 0]') ans = 0.01023335000000 0.00100000000000 0 0 0 0.00000011667500 ________________________________________________________________ Notice that the second component of the input vector (transverse momentum) did not change. That is the consequence of modeling a sextupole as a drift. The preferred pass function is the one with the most accurate physics model for this type of element. For sextuploe in this example 'StrMPoleSymplectic4Pass' function (fourth-order symplectic integrator described []) gives more physical answer. ______________________________________________________________ StrMPoleSymplectic4Pass (THERING{15},[0.01, 0.001, 0 0 0 0]') ans = 0.01022871381142 0.00095996232730 0 0 0 0.00000011210045 ______________________________________________________________ The user can choose the appropriate physics model for each element by setting the 'PassMethod' field to the name of the element-pass function from the Toolbox. The choice of the right pass function (besides qualitatively correct physics model) also depends on other considerations 1. Speed - accuracy tradeoff For example: StrMPoleSymplectic4Pass is a fourth-order symplectic integrator StrMPoleSymplectic2Pass is second order. 2. Different aspecsts of accelerator physics analyzed For example: To simulate classical radiation a different set of element pass functions should be used: BendLinearRadPass insted of BendLinearPass QuadLinearRadPass insted of QuadLinearPass and StrMPoleSymplectic2RadPass insted of StrMPoleSymplectic4Pass WARNING: Element type-function compatibility. As explained above, the Toolbox framework allows to use different pass functions on a particular element type. Reverse is also true: the same pass function can propagate particles through many different types of elements. THERE ARE RESTRICTIONS!!! Each element pass function searches the element data structure passed to it as an argument for specific fields. 1.Element data structure MUST have ALL the fields used by the pass function For example: if 'QuadLinearPass' is used on a drift elemet structure with fields FamName: 'DR01' Length: 1.34480000000000 PassMethod: 'DriftPass' it will not find the field 'K' needed to calculate the quadrupole matrix in the linear model. 2.Field name strings MUST MATCH EXACTLY, CASE SENSITIVE!!! 3.There MUST be a consistency of field names between different element types if they are to use the same pass function. For example: what makes DriftPass in our examples so universal is that ALL element types store the physical length in the field named 'Length' , NOT 'length' or 'L' ADD LATER!!!!!!!!!!! CONSISTENCY TABLE Making new element pass functions. *********************************************************************************** One of the most attractive features of the Toolbox framework is the user's ability to add new element-tracking routines without touching any existing code. The user creates an 'm' or 'mex' function 'NewMethodPass' and makes it visible to MATLAB by placing it into a directory on the MATLAB search path. Simply setting the 'PassMethod' field of an element to 'NewMethodPass' will tell high-level routines (RingPass) to use this function. Functionality 1.Canonical variables 2.Input-Output arguments 3.Vectorization 4.Argument types and dimensions checks 5.Internal Protection from floating point overflow 6.Error/Warning generation 7.Accompanying .m help file Naming conventions 1. ends with "pass" 2. Self-explanatory names (QuadLinearPass) Details of implementation Element tracking functions may be implemented in 3 different ways. 1. m-function. Easy to write - excellet for prototyping purposes. 2. Compiled C or FORTRAN mex-file only with command-line comapatiblility. The internal tracking function is only visible to mexFunction in that file 3. Compiled C or FORTRAN mex-file that in addition to mexFunction also exports its internal tracking function for use in other mex-files I. m-file II. mex-file, command line calling III. mex-file, command line and dynamic loading All element tracking functions must support the command line callinng syntax x_out = quadinpass(THERING{10},[0.001 0 0 0 0 0]'); This ensures that these functions will work at least in m-scripts that use 'feval' in the 'for' loop: X0 = [0.001 0 -0.001 0 0 0]'; for k=1:length(THERING) X0 = feval(RING{k}.PassMethod,RING{k-1},X0); end C mex-function Dynamic linking / loading compatibility High level pass functions ********************************************************************************** LinePass and RingPass These high level functions do not call element pass functions directly. They do it using mxCallMATLAB function. There is some overhead associated with it but the advantages are: 1. Platform independence 2. If an element function works from command line - it will work in the RingPass and LinePass 3. Element pass functions can be prototyped in m-files RingPassWin, RingPassLinux... are versions of RingPass optimized for speed on a particular platform. On Windows RingPassW is faster especially for large number of turns 10+ 1. It eliminates overhead of mxCallMATLAB 2. It uses the element pass-functions that access the element data fields by number (mxGetFieldByNumber) - which is faster than 'by name' (mxGetField)