MAD8 File Loading & Manipulation

MAD8 outputs Twiss information in their own file format. pymad8 includes a class called Output for the purpose of loading and manipulating this data.

The MAD8 format is described in the manual available from the mad8 website. The format is roughly described as a text file. The MAD8 files contain first a few lines that indicate when the file was generated and other general informations. After this, each segment of 5 lines typically represents the values of the lattice for a particular element with each new segment containing the values at a subsequent element in the lattice.

Output Class Features

  • Loading different types of MAD8 files.

  • Get a particular column.

  • Get a particular row.

  • Get elements of a particular type.

  • Get a numerical index from the name of the element.

  • Find the curvilinear S coordinate of an element by name.

  • Find the name of the nearest element at a given S coordinate.

  • Plot an optics diagram.

  • Calculate a beam size given the Twiss parameters, dispersion and emittance.

  • Make a slice of the initial lattice

Loading

MAD8 files can be of different types. Twiss files are the main ones but we can also load Rmat files, Chrom files, Envelope files or Survey files

A file may be loading by constructing an Output instance from a file name :

>>> import pymad8
>>> t = pymad8.Output("myTwissFile")
>>> r = pymad8.Output("myRmatFile", "rmat")
>>> c = pymad8.Output("myChromFile", "chrom")
>>> e = pymad8.Output("myEnvelopeFile", "envel")
>>> s = pymad8.Output("mySurveyFile", "survey")

Note

The import will be assumed from now on in examples.

Querying

The Output class can be used to query the data in various ways.

Basic Information

  • All data is stored in the data object inside the class

  • The number of elements is stored in nrec.

  • The file name is stored in filename.

  • The file type is stored in filetype.

  • A dict of each element type and corresponding properties is stored in keys_dict

  • The names of columns common to all file types is stored in colnames_common.

The data object is a pandas dataframe that can be displayed as follow :

>>> t = pymad8.Output("myTwissFile")
>>> t.data

Indexing and Slicing

The information stored in the dataframe is accessible using regular pandas syntax :

t.data.iloc[3]                      # 4th element in sequence (Pandas.Series returned)
t.data.iloc[3: 10]                  # 4th to 11th elements (Pandas.Dataframe returned)
t.data.iloc[[3, 5, 10]]             # 4th, 6th and 11th elements (Dataframe)
t.data['S']                         # column named exactly S (Series)
t.data[['S', 'L']]                  # columns named exactly S and L (Dataframe)
t.data['S'][3]                      # value of the 4th element in the column S
t.data[t.data['NAME'] == 'INITIAL'] # Row of the element with this exact name (Dataframe)

But you can also find information about elements usind built-in functions.

To get index for example

t.getIndexByNames('INITIAL')              # can have a list of names as input
t.getIndexByTypes('QUAD')                 # can have a list of types as input
t.getIndexByValues(key='S', minValue=200) # indices of elements with S value above 200
t.getIndexByNearestS(150)                 # index of element with S value closest to 150

The results are returned in the form of one value or a list of values, depending on the input given. In the case of the getIndex function, we get either an integer or a list of integers

Note

Similar functions are avaliable to find names and types of lattice elements

Rows and Columns

A row of data is an entry for a particular element. The Output class is conceptually a list of elements. Each element is represented by a row in the pandas dataframe that has a key for each column. The list of acceptable keys (i.e. names of columns) can be found in the member named ‘colums’ :

t.data.columns #prints out list of column names

A specific row or set of rows can be accessed using similar functions as those previously shown :

t.getRowsByIndex(3)                      # can have a list of indices as input
t.getRowsByNames('INITIAL')              # can have a list of names as input
t.getRowsByTypes('QUAD')                 # can have a list of types as input
t.getRowsByValues(key='S', minValue=200) # rows of elements with S value above 200
t.getRowByNearestS(150)                  # row of element with S value closest to 150

The results are return either in the form of a dataframe or serie (which is equivalent to a dataframe with only one row), depending on the input given.

A specific column or set of columns can be accessed using its keys (i.e. its names) :

t.getColumnsByKeys(['S','L'])

Beam Sizes

For convenience the beam size is calculated from the Beta amplitude functions, the emittance, dispersion and enegy spread using calcBeamSize(). The emittance is defined by ‘EmitX’ and ‘EmitY’ and the energy spread by ‘Esprd’. Those three parameters aren’t provided by MAD8 and must be manualy given to the function :

EmitX = 3e-11
EmitY = 3e-11
Esprd = 1e-6
t.calcBeamSize(EmitX, EmitY, Esprd)

In this function, the beam sizes are calculated according to :

\[\begin{split}\sigma_x &= \sqrt{ \beta_x \epsilon_x + D(S)^2 \frac{\sigma_{E}^{2}}{E_{0}^{2}}} \\ \sigma_y &= \sqrt{ \beta_y \epsilon_y + D(S)^2 \frac{\sigma_{E}^{2}}{E_{0}^{2}}}\end{split}\]