Description of the element "mag3d" for a dipole magnet with external 3D fields

  Element entry in the lattice file "sclinac.dat":

    n   mag3d  f_len  rbend  theta  airgap  width  nstep
  
    n          : number of the mag3d file to use (n=1 --> fld3d.#01)
    f_len [cm] : field length in file including fringe fields (not real dipole length)
    rbend [cm] : bending radius  
    theta [deg]: bending angle
    airgap [cm]: airgap
    width [cm] : width 
    nstep      : number of integration steps

  Example:

    1   mag3d  93.6   50.   60.  6.  12.   200

  Format of the 3D field file:

    The Z direction of the field data has an angle of "theta/2" with the incomming and 
   outgoing beam directions. So the field is a 3D box at half the bending angle from in 
   and out beam directions. The origin of the field frame is the center of the magnet 
   which corresponds to the mid-point along the central trajectory (not a real trajectory). 
   The X axis is orthogonal to the Z axis in the horizaontal plane and Y is vertical forming 
   a right-handed coordinate system.

    The field file is in ASCII and could be read in fortran as follow:     

      open(2, file=magfile, status='old')
      read(2,*) ifld
      read(2,*) isymx, isymy, isymz
      read(2,*) xmn, xmx, ngx
      read(2,*) ymn, ymx, ngy
      read(2,*) zmn, zmx, ngz
      do i = 1, ngx
        do j = 1, ngy
          do k = 1, ngz
            read(2,*) b1, b2, b3
            bx(i,j,k) = b1
            by(i,j,k) = b2
            bz(i,j,k) = b3
          enddo
        enddo
      enddo
      close(2)

    where: ifld: field type, 0:E, 1:B and 2: E&B
           isymx, isymy, isymz: symmetry flags in X, Y and Z
           ngx, ngy, ngz: number of data points in every direction
           xmn, ymn, zmn: field's lower limits in X, Y and Z
           xmx, ymx, zmx: field's upper limits in X, Y and Z
           bx , by , bz : field data arrays
    

  Reference trajectory calculation:

    TRACK is a z-based code; the integration is done with steps along the z direction, so 
   we should first determine the length of the reference trajectory. This is done using the 
   input beam energy (Win) and the reference particle mass and charge state (Adesign, Qdesign). 
   Both the field strength and the reference trajectory length are adjusted using a fit to 
   have an exit point symmetric to the entrance point for the reference trajectory.

    Once the reference trajectory length is determined, it'll be considered as the actual length
   of the magnet and will be divided into "nstep" integration steps to track the real beam
   particles.