source: MML/trunk/at/atdoc/howto_newpassmethods.txt @ 4

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)