

In [149]:

    
help(pyaccel.tracking.ringpass)









    



Help on function ringpass in module pyaccel.tracking:

ringpass(accelerator, particles, nr_turns=1, turn_by_turn=None, element_offset=0)
    Track particle(s) along a ring.
    
    Accepts one or multiple particles initial positions. In the latter case,
    a list of particles or a numpy 2D array (with particle as firts index)
    should be given as input; tracked particles positions at the end of
    the ring are output variables, as well as information on whether particles
    have been lost along the tracking and where they were lost.
    
    Keyword arguments: (accelerator, particles, nr_turns,
                        turn_by_turn, elment_offset)
    
    accelerator    -- Accelerator object
    particles      -- initial 6D particle(s) position(s).
                      Few examples
                        ex.1: particles = [rx,px,ry,py,de,dl]
                        ex.2: particles = [[0.001,0,0,0,0,0],[0.002,0,0,0,0,0]]
                        ex.3: particles = numpy.zeros((Np,6))
    nr_turns       -- number of turns around ring to track each particle.
    turn_by_turn   -- parameter indicating what turn by turn positions are to
                      be returned. If None ringpass returns particles
                      positions only at the end of the ring, at the last turn.
                      If turn_by_turn is 'closed' ringpass returns positions
                      at the end of the ring for every turn. If it is 'open'
                      than positions are returned at the beginning of every
                      turn.
    
    element_offset -- element offset (default 0) for tracking. tracking will
                      start at the element with index 'element_offset'
    
    Returns: (particles_out, lost_flag, lost_turn, lost_element, lost_plane)
    
    particles_out -- 6D position for each particle at end of ring. The structure
                     of 'particles_out' depends on inputs 'particles' and
                     'turn_by_turn'. If 'turn_by_turn' is None then only
                     tracked positions at the end 'nr_turns' are returned. There
                     are still two possibilities for the structure of
                     particles_out, depending on 'particles':
    
                    (1) if 'particles' is a single particle defined as a python
                        list of coordinates, 'particles_out' will also be a
                        simple list:
                        ex.:particles = [rx1,px1,ry1,py1,de1,dl1]
                            turn_by_turn = False
                            particles_out=numpy.array([rx2,px2,ry2,py2,de2,dl2])
    
                    (2) if 'particles' is either a python list of particles or a
                        numpy matrix then 'particles_out' will be a matrix
                        (numpy array of arrays) whose first index selects the
                        coordinate rx, px, ry, py, de or dl, in this order, and
                        the second index selects a particular particle.
                        ex.: particles = [[rx1,px1,ry1,py1,de1,dl1],
                                          [rx2,px2,ry2,py2,de2,dl2]]
                             turn_by_turn = False
                             particles_out = numpy.array(
                                 [ [rx3,px3,ry3,py3,de3,dl3],
                                   [rx4,px4,ry4,py4,de4,dl4]
                                 ])
    
                     'turn_by_turn' can also be either 'close' or 'open'. In
                     either case 'particles_out' will have tracked positions at
                     the entrances of the elements. The difference is that for
                     'closed' it will have an additional tracked position at the
                     exit of the last element, thus closing the data, in case
                     the line is a ring. The format of 'particles_out' is ...
    
                    (3) a numpy matrix, when 'particles' is a single particle
                        defined as a python list. The first index of
                        'particles_out' runs through coordinates rx, px, ry, py,
                        de or dl and the second index runs through the turn
                        number
    
                    (4) a numpy rank-3 tensor, when 'particles' is the initial
                        positions of many particles. The first index now runs
                        through particles, the second through coordinates and
                        the third through turn number.
    
    lost_flag    -- a general flag indicating whether there has been particle
                    loss.
    lost_turn    -- list of turn index where each particle was lost.
    lost_element -- list of element index where each particle was lost
                    If the particle survived the tracking through the ring its
                    corresponding element in this list is set to None. When
                    there is only one particle defined as a python list (not as
                    a numpy matrix with one column) 'lost_element' returns a
                    single number.
    lost_plane   -- list of strings representing on what plane each particle
                    was lost while being tracked. If the particle is not lost
                    then its corresponding element in the list is set to None.
                    If it is lost in the horizontal or vertical plane it is set
                    to string 'x' or 'y', correspondingly. If tracking is
                    performed with a single particle described as a python list
                    then 'lost_plane' returns a single string