sddsemitmeas

• description:

  sddsemitmeas analyzes quadrupole scan emittance measurement data. It accepts a file containing the transport matrix for each data point and measured beam sizes. Because sddsemitmeas uses the matrix rather than a thin-lens model, it can analyze data from arbitrarily complex scans, involving, for example, multiple thick-lens quadrupoles.

  The matrix data can be prepared using elegant. For example, the vary_element command can be used to vary one or more quadrupoles. In addition, the beam size data may be prepared using elegant, to allow simulation of emittance measurements.

  sddsemitmeas will perform error analysis using a Monte Carlo technique. A user-specified number of random error sets are generated and added to all measurements. Analysis is performed for each error set. Statistics over all the error sets provide most likely values and error bars.

• examples:
  elegant quadScan.ele sddscollapse quadScan.fin -pipe=out
  | sddsxref -pipe=in quadScan.data -take=SigmaX,SigmaY
  | sddsemitmeas -pipe=in emitResults.sdds

• synopsis:
  sddsemitmeas [inputfile] [outputfile] [-pipe=[input][,output]] [-sigmaData=xName,yName] [-energySpread=fractionalRMSValue] [-errorLevel=valueInm,[{gaussian,nSigmas | uniform}]] [-nErrorSets=number] [-seed=integer] [-limitMode=resolution | zero[,reject] [-deviationLimit=xLevelm,yLevelm] [-resolution=xResolutionm,yResolutionm] [-uncertaintyFraction=xValue,yValue] [-fixedUncertainty=xValuem,yValuem] [-findUncertainties] [-minimumUncertainty=xValuem,yValuem] [-constantWeighting] [-verbosity=level]

• files:
  • inputfile -- An SDDS file containing one or more pages with columns named Rij, where ij is 11, 12, 33, and 34. These give elements of the horizontal and vertical transport matrices from the beginning of a system to the observation point. The sigma matrix inferred will be that for the beginning of the system. Typically, one starts with the final file from the run_setup command in elegant, and collapses it using sddscollapse. Each page of inputfile corresponds to a different emittance measurement.

    If energy spread is included (-energySpread option), the file must also contain columns named etax and etay, giving the horizontal and vertical dispersion at the observation point. These may be added to the final file using sddsprocess (to get the final values as parameters) and sddsxref (to transfer the parameters), prior to using sddscollapse.

    In addition to this data, inputfile must also contain columns giving the rms beam sizes in x and y. The user supplies the names of the columns using the -sigmaData option. These columns may be from elegant (e.g., Sx and Sy), if one wants to simulate an emittance measurement. Note that the theory behind the emittance measurement is strictly correct only for true RMS beamsize measurements. Use of FWHM or some other measure will give unreliable results.

  • outputfile -- A file containing one page for each page of inputfile. The parameters of outputfile give the measured geometric rms emittance, sigma matrix, and Twiss parameters of the beam in the horizontal and vertical planes. If error sets were requested (using -nErrorSets), then there are also parameters giving the error bars (``sigma's'') of the measured values.

    The columns of outputfile contain various quantities depending on the mode. For files generated with elegant and no error sets, it contains the measured and fit beam size data, along with the strength of one of the varied quadrupoles. In other cases, less data may be present.

• switches:
  • -sigmaData=xName,yName -- Supplies the names of the columns in inputfile from which the x and y rms beam sizes are to be taken. Default values are Sx and Sy, which are the data provided by elegant.
  • -energySpread=fractionalRMSValue -- Supplies the fractional rms energy spread of the beam. If given, the inputfile must contain dispersion data, as described above.
  • -errorLevel=valueInm,[gaussian,nSigmas | uniform] -- Supplies the standard deviation of random errors to be added to the measured beam sizes for Monte Carlo error analysis. This control should not be confused with the controls over the individual data point uncertainties; the latter are used for purposes of weighting the fits only. Supposedly, the error levels and the uncertainties would be the same, however.
  • -nErrorSets=number -- The number of sets of random errors to generate and add to the measurements. Each error set is used to perturb the original measurement data. The results are analyzed separately for each error set, then combined to give means and error bars.
  • -seed=integer -- Seed for the random number generator. Recommend a large, positive, odd integer less than $2^31$. If no seed is given or if the given seed is negative, then a seed is generated from the system clock.
  • -resolution=xResolutionm,yResolutionm -- The resolution of the beam size measurements, in meters. These values are subtracted in quadrature from the measured beam sizes to obtain the true beam sizes.
  • -limitMode=resolution | zero[,reject] -- If measured or perturbed beam sizes are less than the resolution or less than zero, then errors will result. One can use this option to limit minimum beam size values or reject points. In general, if you have to do this your measurement is probably bad.
  • -deviationLimit=xLevelm,yLevelm -- Specifies the maximum deviation, in meters, from the fit that data points may have and still be included. An initial fit is performed for each randomized set or the raw data, as appropriate. Outliers are then removed and the fit is repeated.
  • -uncertaintyFraction=xValue,yValue -- Specifies that uncertainties in individual measurements should determined as the given fractions of the measured values. Generally not realistic.
  • -fixedUncertainty=xValuem,yValuem -- Specifies that uncertainties in individual measurements should be identical, at the values given (in meters).
  • -findUncertainties -- Specifies that uncertainties in individual measurements should be deduced from an initial unweighted fit.
  • -minimumUncertainty=xValuem,yValuem -- Specifies that uncertainties may not be smaller than the given values, in meters.
  • -constantWeighting -- Specifies uncertainties such that all points are given equal weight in the fit.
  • -verbosity=level -- Higher values of level result in more informational printouts as the program runs.

• author: M. Borland, ANL/APS.