|
| 1 | +================================ |
| 2 | +MAD8 File Loading & Manipulation |
| 3 | +================================ |
| 4 | + |
| 5 | +MAD8 outputs Twiss information in their own file format. |
| 6 | +pymad8 includes a class called Output for the purpose of loading and manipulating this data. |
| 7 | + |
| 8 | +The MAD8 format is described in the manual available from `the mad8 website <http://mad8.web.cern.ch>`_. |
| 9 | +The format is roughly described as a text file. |
| 10 | +The MAD8 files contain first a few lines that indicate when the file was generated and other general informations. |
| 11 | +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. |
| 12 | + |
| 13 | +Output Class Features |
| 14 | +--------------------- |
| 15 | + |
| 16 | + * Loading different types of MAD8 files. |
| 17 | + * Get a particular column. |
| 18 | + * Get a particular row. |
| 19 | + * Get elements of a particular type. |
| 20 | + * Get a numerical index from the name of the element. |
| 21 | + * Find the curvilinear S coordinate of an element by name. |
| 22 | + * Find the name of the nearest element at a given S coordinate. |
| 23 | + * Plot an optics diagram. |
| 24 | + * Calculate a beam size given the Twiss parameters, dispersion and emittance. |
| 25 | + * Make a slice of the initial lattice |
| 26 | + |
| 27 | +Loading |
| 28 | +------- |
| 29 | + |
| 30 | +MAD8 files can be of different types. |
| 31 | +Twiss files are the main ones but we can also load Rmat files, Chrom files, Envelope files or Survey files |
| 32 | + |
| 33 | +A file may be loading by constructing an Output instance from a file name : |
| 34 | + |
| 35 | +>>> import pymad8 |
| 36 | +>>> t = pymad8.Output("myTwissFile") |
| 37 | +>>> r = pymad8.Output("myRmatFile", "rmat") |
| 38 | +>>> c = pymad8.Output("myChromFile", "chrom") |
| 39 | +>>> e = pymad8.Output("myEnvelopeFile", "envel") |
| 40 | +>>> s = pymad8.Output("mySurveyFile", "survey") |
| 41 | + |
| 42 | +.. note:: The import will be assumed from now on in examples. |
| 43 | + |
| 44 | +Querying |
| 45 | +-------- |
| 46 | + |
| 47 | +The Output class can be used to query the data in various ways. |
| 48 | + |
| 49 | +Basic Information |
| 50 | +***************** |
| 51 | + |
| 52 | + * All data is stored in the **data** object inside the class |
| 53 | + * The number of elements is stored in **nrec**. |
| 54 | + * The file name is stored in **filename**. |
| 55 | + * The file type is stored in **filetype**. |
| 56 | + * A dict of each element type and corresponding properties is stored in **keys_dict** |
| 57 | + * The names of columns common to all file types is stored in **colnames_common**. |
| 58 | + |
| 59 | +The **data** object is a pandas dataframe that can be displayed as follow : |
| 60 | + |
| 61 | +>>> t = pymad8.Output("myTwissFile") |
| 62 | +>>> t.data |
| 63 | + |
| 64 | +Indexing and Slicing |
| 65 | +******************** |
| 66 | + |
| 67 | +The information stored in the dataframe is accessible using regular pandas syntax : :: |
| 68 | + |
| 69 | + t.data.iloc[3] # 4th element in sequence (Pandas.Series returned) |
| 70 | + t.data.iloc[3: 10] # 4th to 11th elements (Pandas.Dataframe returned) |
| 71 | + t.data.iloc[[3, 5, 10]] # 4th, 6th and 11th elements (Dataframe) |
| 72 | + t.data['S'] # column named exactly S (Series) |
| 73 | + t.data[['S', 'L']] # columns named exactly S and L (Dataframe) |
| 74 | + t.data['S'][3] # value of the 4th element in the column S |
| 75 | + t.data[t.data['NAME'] == 'INITIAL'] # Row of the element with this exact name (Dataframe) |
| 76 | + |
| 77 | +But you can also find information about elements usind built-in functions. |
| 78 | + |
| 79 | +To get index for example :: |
| 80 | + |
| 81 | + t.getIndexByNames('INITIAL') # can have a list of names as input |
| 82 | + t.getIndexByTypes('QUAD') # can have a list of types as input |
| 83 | + t.getIndexByValues(key='S', minValue=200) # indices of elements with S value above 200 |
| 84 | + t.getIndexByNearestS(150) # index of element with S value closest to 150 |
| 85 | + |
| 86 | +The results are returned in the form of one value or a list of values, depending on the input given. |
| 87 | +In the case of the getIndex function, we get either an integer or a list of integers |
| 88 | + |
| 89 | +.. note:: Similar functions are avaliable to find names and types of lattice elements |
| 90 | + |
| 91 | +Rows and Columns |
| 92 | +**************** |
| 93 | + |
| 94 | +A row of data is an entry for a particular element. The Output class is conceptually a list of |
| 95 | +elements. Each element is represented by a row in the pandas dataframe that has a key for each column. |
| 96 | +The list of acceptable keys (i.e. names of columns) can be found in the member named 'colums' : :: |
| 97 | + |
| 98 | + t.data.columns #prints out list of column names |
| 99 | + |
| 100 | +A specific row or set of rows can be accessed using similar functions as those previously shown : :: |
| 101 | + |
| 102 | + t.getRowsByIndex(3) # can have a list of indices as input |
| 103 | + t.getRowsByNames('INITIAL') # can have a list of names as input |
| 104 | + t.getRowsByTypes('QUAD') # can have a list of types as input |
| 105 | + t.getRowsByValues(key='S', minValue=200) # rows of elements with S value above 200 |
| 106 | + t.getRowByNearestS(150) # row of element with S value closest to 150 |
| 107 | + |
| 108 | +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. |
| 109 | + |
| 110 | +A specific column or set of columns can be accessed using its keys (i.e. its names) : :: |
| 111 | + |
| 112 | + t.getColumnsByKeys(['S','L']) |
| 113 | + |
| 114 | +Beam Sizes |
| 115 | +---------- |
| 116 | + |
| 117 | +For convenience the beam size is calculated from the Beta amplitude functions, the emittance, dispersion and enegy spread using `calcBeamSize()`. |
| 118 | +The emittance is defined by 'EmitX' and 'EmitY' and the energy spread by 'Esprd'. |
| 119 | +Those three parameters aren't provided by MAD8 and must be manualy given to the function : :: |
| 120 | + |
| 121 | + EmitX = 3e-11 |
| 122 | + EmitY = 3e-11 |
| 123 | + Esprd = 1e-6 |
| 124 | + t.calcBeamSize(EmitX, EmitY, Esprd) |
| 125 | + |
| 126 | +In this function, the beam sizes are calculated according to : |
| 127 | + |
| 128 | +.. math:: |
| 129 | +
|
| 130 | + \sigma_x &= \sqrt{ \beta_x \epsilon_x + D(S)^2 \frac{\sigma_{E}^{2}}{E_{0}^{2}}} \\ |
| 131 | + \sigma_y &= \sqrt{ \beta_y \epsilon_y + D(S)^2 \frac{\sigma_{E}^{2}}{E_{0}^{2}}} |
| 132 | +
|
0 commit comments