APRICOT

Particle Tracking Module for python - Ali Can Canbay

APRICOT is a python3 module that simulates the behavior of particle beams in electromagnetic fields as they pass through various beamline elements and calculates beamline parameters at the end of the beamline.

Installing via pip:

APRICOT can be installed by running the following command in the console (all necessary modules will be installed automatically).

pip install apricotbl

Manual Installation:

APRICOT requires the numpy, scipy, and matplotlib modules. If these modules are not installed, you can install them with the following command:

pip install -r requirements.txt

requirements.txt is available on APRICOT's github page.

Then, download the latest release and extract it. Enter the extracted file and run the following command via console:

python setup.py install

By clicking the "launch binder" button above, you can use APRICOT without any installation on your computer (Tutorials created with jupyter in the examples directory can also be run with binder).

---

1. Beam Generation

APRICOT has two different beam generation methods: random beam generator and electron gun beam generator.

In both methods, before the beam generation, the information text of the parameters is printed on the console screen as follows.

Creating beam with parameters below:
        
    Particle Type           : electron
    Number of Particles     : 100000
    Beam Energy (KeV)       : 2.500e+02
    RMS x size (mm)         : 3.000e-06
    RMS y size (mm)         : 3.000e-06
    RMS z size (mm)         : 1.000e-06
    Emittance x (m.rad)     : 7.200e-10
    Emittance y (m.rad)     : 1.171e-09
    Alpha x                 : 1.169e-16
    Alpha y                 : -1.169e-16
    %Energy Spread          : 0.000e+00

1.1. Random Beam

Random beam generation is provided by the RandomBeam method in the Functions module. Here is the usage of the parameters required by the RandomBeam (in Outputs module):

ParticleTpye        # 'electron', 'proton' or 'muon'
NumberOfParticles   # Number of particles
BeamEnergy          # Beam energy (keV)
x_rms               # RMS beam size of x (m)  
y_rms               # RMS beam size of y (m) 
z_rms               # RMS beam size of y (m) (not mandatory)
Emittance_x         # Emittance x (m.rad)
Emittance_y         # Emittance y (m.rad)
Alpha_x             # Alpha x
Alpha_y             # Alpha y
dE                  # Energy Spread (not mandatory)

After these parameters are determined, random beam generation is provided as follows.

RandomBeam(ParticleTpye, NumberOfParticles, BeamEnergy, x_rms, y_rms, Emittance_x, Emittance_y, Alpha_x, Alpha_y, z_rms, dE)

The function will return the generated beam object as return value.

1.2. Electron Gun

For beam generation with the electron gun, the necessary parameters should be defined as follows:

NumberOfParticles   # Number of particles
r_Cathode           # Cathode radius (m)
Temperature         # Cathode temperature (C)
Voltage             # Gun voltage (V)

Then the egun is created with the ElectronGun class in the Gun module:

egun = ElectronGun(r_Cathode, Temperature, Voltage)

Finally, the egun's GenerateBeam method is called.

egun.GenerateBeam(NumberOfParticles)

The method will return the generated beam object as return value.

2. Beamline Elements

APRICOT currently has Drift Tube, Quadrupole Magnet, Dipole Magnet and Solenoid beamline components. In addition to these, it also allows the production of lattice.

2.1. Drift Tube

The following parameters are used to create Drift Tube:

Name    # Name of the element
Length  # Length of the element

Drift Tube object is created from the DriftTube class in the BeamLineComponent module as follows:

DriftTube(Name, Length)

2.2. Quadrupole Magnet

The following parameters are used to create Quadrupole Magnet:

Name      # Name of the element
Length    # Length of the element
Strength  # Strength of the element

Quadrupole Magnet object is created from the QuadrupoleMagnet class in the BeamLineComponent module as follows:

QuadrupoleMagnet(Name, Length, Strength)

2.3. Dipole Magnet

The following parameters are used to create Quadrupole Magnet:

Name      # Name of the element
Length    # Length of the element
Angle     # Angle expected to bend
ybend     # Enter 1 to bend in the y-axis (not mandatory)

Quadrupole Magnet object is created from the DipoleMagnet class in the BeamLineComponent module as follows:

DipoleMagnet(Name, Length, Angle, ybend)

2.4. Solenoid

The following parameters are used to create Solenoid:

Name      # Name of the element
Length    # Length of the element
Strength  # Strength of the element

Solenoid object is created from the Solenoid class in the BeamLineComponent module as follows:

Solenoid(Name, Length, Strength)

3. Beamline

After the beamline components are defined, the beamline must be aligned. The following parameters are used to create beamline:

Name      # Name of the element
Elements  # Elements in beamline (in list form, in brackets)

The beamline object is generated from the BeamLine class of the BeamLine module as follows:

Beamline(Name, Elements)

To pass the beam in the beamline, the TransportBeam method from the Functios module is used (assume that BeamLine object is named as beamline).

TransportBeam( Beam, beamline.Elements )

This proceeds by specifying the parameters of the beam at the end of each element. If the behavior inside the elements is also to be calculated, the step size (m) for the z-axis must be determined in the code.

TransportBeam( Beam, beamline.Elements, dz )

! The step length must be the exact divisor of the element lengths. It is recommended that the minimum value of step length should be in millimeters (it can be taken down to 10 microns).

3.1. FODO Lattice

The following parameters are needed to create a FODO lattice:

Name                      # Name of the element
DriftLength               # Length of the drift tubes
QuadrupoleMagnetLength    # Length of the quadrupole magnets
QuadrupoleMagnetStrength  # Strength of the quadrupole magnets

The FODO object is generated from the FODO class of the BeamLine module as follows:

FODO(Name, DriftLength, QuadrupoleMagnetLength, QuadrupoleMagnetStrength)

If step size is used for FODO: step size should be the exact divisor of half of the quadrupole magnet length and the drift tube length.

4. Outputs

Outputs module is used for outputs.

4.1. Beam Graphs

The beam graphs can be stored with the getBeam method (in Outputs module). getBeam needs the following parameters:

Beam   # Beam object
path   # File path to save graphics (not mandatory)
tag    # Name tag (not mandatory)

The default value for path is the file path of the script.

By using the getBeam method as below, beam shape and phase space graphs are created. The Beam Position graph gives the beam's length in the x and y axes relative to the z axis (not rms).

getBeam(Beam, path, tag)

Examples: 7th example

4.1. Position Graphs

The position graphs can be stored with the getBeamPositions method (in Outputs module). getBeamPositions needs the following parameters:

Beam                # Beam object
beamline.Elements   # Elements of beamline object
path                # File path to save graphics (not mandatory)
tag                 # Name tag (not mandatory)

The default value for path is the file path of the script.

By using the getBeamPositions method as below, beam position and beta function graphs are created.

getBeamPositions(Beam, beamline.Elements, path, tag)

Examples: 7th example

getBeamPositions function prints an output with the final state beam parameters as follows:

Beam parameters in the final state:
        
    RMS x size (mm)         : 2.870e-06
    RMS y size (mm)         : 3.008e-06
    Emittance x (m.rad)     : 7.208e-10
    Emittance y (m.rad)     : 1.170e-09
    Beta x (mm)             : 1.143e+01
    Beta y (mm)             : 7.730e+00

5. Plots

The Graph module can be used if the graphs are to be viewed without saving them. Plots are displayed as follows:

Beam Graphs: To look at Beam shape in the xy, yz and zx-axes.

plotBeamShape_xy(Beam)

Phase Space:

plotPhaseSpace(Beam)

Position Graph: To look at the behavior of the beam size in the beamline

plotPositionGraph( Beam, beamline.Elements )

Position Graph (RMS size): To look at the behavior of the RMS beam size in the beamline

plotPositionGraph_RMSsize( Beam, beamline.Elements )

Beta Function:

plotBetaFunctions( Beam, beamline.Elements )

---