![[PukiWiki]](image/pukiwiki.png "[PukiWiki]")
With MAP elements, ExternalMap defines a user-defined map of particles. It also allows a user to do anything (doing statistics, etc.) at any point of a beam line during a tracking.
Usage: First define a MAP element at MAIN level:
MAP name=(L=leng);
Right now L is the only keyword. Insert it at the location(s) where you want to use it.
1) Tracking In FFS, define the function ExternalMap as
ExternalMap["TRACK",n,nt_,x_]:=body;
The second argument n is the position of MAP couting from the beginning, which can be obtained using LINE["POSITION","name.m"]. The third argument nt_ is used to receive the number of turns which is incremented by the tracking. The last argument x_ is used to receive the coordinates of particles. It is a (7, np) list of real numbers. The elements (1..6, i) are (x, px ,y ,py ,z ,dp/p0) of the i-th particle. The (7, i) element is True(==1) if the i-th particle has been survived, and False(==0) if it has been lost.
You can define ExternalMap to change the coordinates of each particle as you like by returning a new x in the same format as above. If you do not return it or you return in a different format, the tracking routine does not change the particle coordinates. You can neither rebirth a lost particle nor kill a surviving particle.
After defined ExternalMap, tracking calls it in every turn.
Example:
MAP P1=();
....
LINE A=(... P1 ... P1 ...);
....
FFS USE=A;
ExternalMap["TRACK",LINE["POSITION","P1.2"],nt_,x_]:=
(Print[x];x*2);
....
TRACK USE=A ....;
This example defines ExternalMap to print out the coordinates of all particles at the second P1 in the line A. It also makes all coordinates of all particles twice in every turn.
2) Emittance In FFS, define the function ExternalMap as
ExternalMap["EMIT",n,cod_]:=body;
The second argument n is the position of MAP couting from the beginning, which can be obtained using LINE["POSITION","name.m"]. The last argument cod_ is used to receive the orbit at the entrance of the element, as a list of 6 real numbers. ExternalMap must return a list, either {cod1, trans} or {cod1, trans, dtrans, dbeam}, where cod1 is the orbit at the exit, trans is the 6 by 6 transfer matrix of this element, dtrans is the radiation damping part of the transfer matrix (6 by 6), and dbeam is the radiation excitation of the beam matrix (6 by 6). Only j >= i parts of dbeam[ [i, j] ] are taken into account.
Example:
ExternalMap["EMIT",LINE["POSITION","P1"],cod_]:=(
Print[cod];
{cod+{0,0.001,0,0,0,0},IdentityMatrix[6]});
3) Optics In FFS, define the function ExternalMap as
ExternalMap["OPTICS",n,cod_]:=body;
The second argument n is the position of MAP couting from the beginning, which can be obtained using LINE["POSITION","name.m"]. The last argument cod_ is used to receive the orbit at the entrance of the element, as a list of 6 real numbers. ExternalMap must return a list {cod1, trans}, where cod1 is the orbit at the exit and trans is the 6 by 6 transfer matrix of this element. So far only the 4 by 5 transfer matrix is effective.
Example:
ExternalMap["OPTICS",LINE["POSITION","P1"],cod_]:=(
Print[cod];
{cod+{0,0.001,0,0,0,0},IdentityMatrix[6]});
4) Geometry In FFS, define the function ExternalMap as
ExternalMap["GEO",n,geo_,pos_]:=body;
The second argument n is the position of MAP couting from the beginning, which can be obtained using LINE["POSITION","name.m"]. The argument geo_ receives the geometry of the beam line at the MAP element, in the same format as LINE["GEO",n], i.e., {{GX,GY,GZ},{CHI1,CHI2,CHI3}}.The last argument pos_ receives the orbit length S at the element. ExternalMap must return an updated list {geo1, pos1}, as { {{GX,GY,GZ},{CHI1,CHI2,CHI3}}, S} as the values at the exit of the element.
Example:
ExternalMap["GEO",LINE["POSITION","P1"],geo_,pos_]:=(
Print[cod];
{ {geo[[1]]+{1,0,0}, geo[[2]]}, pos+0.1})
