flame_utils package

Subpackages

• flame_utils.core package
  • Submodules
  • flame_utils.core.element module
  • flame_utils.core.model module
  • flame_utils.core.state module
  • Module contents
• flame_utils.io package
  • Submodules
  • flame_utils.io.lattice module
  • flame_utils.io.output module
  • Module contents
• flame_utils.misc package
  • Submodules
  • flame_utils.misc.alias module
  • flame_utils.misc.confupdate module
  • flame_utils.misc.listset module
  • flame_utils.misc.machsetter module
  • flame_utils.misc.message module
  • Module contents
• flame_utils.viz package
  • Submodules
  • flame_utils.viz.plotlat module
  • Module contents

Module contents

This package contains classes/functions to serve as utils for the potential requirment of modeling accelerator with FLAME code.

class flame_utils.BeamState(s=None, **kws)

Bases: object

FLAME beam state, from which simulated results could be retrieved.

Class attributes of reference beam parameter:

pos	float: longitudinally propagating position, [m]
ref_beta	float: speed in the unit of light velocity in vacuum of reference charge state, Lorentz beta, [1]
ref_bg	float: multiplication of beta and gamma of reference charge state, [1]
ref_gamma	float: relativistic energy of reference charge state, Lorentz gamma, [1]
ref_IonEk	float: kinetic energy of reference charge state, [eV/u]
ref_IonEs	float: rest energy of reference charge state, [eV/u]
ref_IonQ	int: macro particle number of reference charge state, [1]
ref_IonW	float: total energy of reference charge state, [eV/u], i.e. \(W = E_s + E_k\).
ref_IonZ	float: reference charge to mass ratio, e.g.
ref_phis	float: absolute synchrotron phase of reference charge state, [rad]
ref_SampleIonK	float: wave-vector in cavities with different beta values of reference charge state, [rad]
ref_Brho	float: magnetic rigidity of reference charge state, [Tm]

Class attributes of actual beam parameter:

beta	Array: speed in the unit of light velocity in vacuum of all charge states, Lorentz beta, [1]
bg	Array: multiplication of beta and gamma of all charge states, [1]
gamma	Array: relativistic energy of all charge states, Lorentz gamma, [1]
IonEk	Array: kinetic energy of all charge states, [eV/u]
IonEs	Array: rest energy of all charge states, [eV/u]
IonQ	Array: macro particle number of all charge states
IonW	Array: total energy of all charge states, [eV/u], i.e. \(W = E_s + E_k\).
IonZ	Array: all charge to mass ratios
phis	Array: absolute synchrotron phase of all charge states, [rad]
SampleIonK	Array: wave-vector in cavities with different beta values of all charge states, [rad]
Brho	float: magnetic rigidity of reference charge state, [Tm]
moment0	Array: centroid for all charge states, array of [x, x', y, y', phi, dEk, 1]
moment0_rms	Array: rms beam envelope, part of statistical results from moment1.
moment0_env	Array: weight average of centroid for all charge states, array of [x, x', y, y', phi, dEk, 1], with the units of [mm, rad, mm, rad, rad, MeV/u, 1].
moment1	Array: covariance matrices of all charge states, for each charge state, the covariance matrix could be written as:
moment1_env	Array: averaged covariance matrices of all charge states
xcen	float: weight average of all charge states for \(x\), [mm]
xrms	float: general rms beam envelope for \(x\), [mm]
xpcen	float: weight average of all charge states for \(x'\), [rad]
xprms	float: general rms beam envelope for \(x'\), [rad]
ycen	float: weight average of all charge states for \(y\), [mm]
yrms	float: general rms beam envelope for \(y\), [mm]
ypcen	float: weight average of all charge states for \(y'\), [rad]
yprms	float: general rms beam envelope for \(y'\), [rad]
zcen	float: weight average of all charge states for \(\phi\), [rad]
zrms	float: general rms beam envelope for \(\phi\), [rad]
zpcen	float: weight average of all charge states for \(\delta E_k\), [MeV/u]
zprms	float: general rms beam envelope for \(\delta E_k\), [MeV/u]
xcen_all	Array: x centroid for all charge states, [mm]
xrms_all	Array: general rms beam envelope for \(x\) of all charge states, [mm]
xpcen_all	Array: x centroid divergence for all charge states, [rad]
xprms_all	Array: general rms beam envelope for \(x'\) of all charge states, [rad]
ycen_all	Array: y centroid for all charge states, [mm]
yrms_all	Array: general rms beam envelope for \(y\) of all charge states, [mm]
ypcen_all	Array: y centroid divergence for all charge states, [rad]
yprms_all	Array: general rms beam envelope for \(y'\) of all charge states, [rad]
zcen_all	Array: longitudinal beam length, measured in RF frequency for all charge states, [rad]
zrms_all	Array: general rms beam envelope for \(\phi\) of all charge states, [rad]
zpcen_all	Array: kinetic energy deviation w.r.t.
zprms_all	Array: general rms beam envelope for \(\delta E_k\) of all charge states, [MeV/u]
xemittance	float: weight average of geometrical x emittance, [mm-mrad]
xnemittance	float: weight average of normalized x emittance, [mm-mrad]
yemittance	float: weight average of geometrical y emittance, [mm-mrad]
ynemittance	float: weight average of normalized y emittance, [mm-mrad]
zemittance	float: weight average of geometrical z emittance, [rad-MeV/u]
znemittance	float: weight average of normalized z emittance, [rad-MeV/u]
xemittance_all	Array: geometrical x emittance of all charge states, [mm-mrad]
xnemittance_all	Array: normalized x emittance of all charge states, [mm-mrad]
yemittance_all	Array: geometrical y emittance of all charge states, [mm-mrad]
ynemittance_all	Array: normalized y emittance of all charge states, [mm-mrad]
zemittance_all	Array: geometrical z emittance of all charge states, [rad-MeV/u]
znemittance_all	Array: normalized z emittance of all charge states, [rad-MeV/u]
xtwiss_beta	float: weight average of twiss beta x, [m/rad]
xtwiss_alpha	float: weight average of twiss alpha x, [1]
xtwiss_gamma	float: weight average of twiss gamma x, [rad/m]
ytwiss_beta	float: weight average of twiss beta y, [m/rad]
ytwiss_alpha	float: weight average of twiss alpha y, [1]
ytwiss_gamma	float: weight average of twiss gamma y, [rad/m]
ztwiss_beta	float: weight average of twiss beta z, [rad/MeV/u]
ztwiss_alpha	float: weight average of twiss alpha z, [1]
ztwiss_gamma	float: weight average of twiss gamma z, [MeV/u/rad]
xtwiss_beta_all	Array: twiss beta x of all charge states, [m/rad]
xtwiss_alpha_all	Array: twiss alpha x of all charge states, [1]
xtwiss_gamma_all	Array: twiss gamma x of all charge states, [rad/m]
ytwiss_beta_all	Array: twiss beta y of all charge states, [m/rad]
ytwiss_alpha_all	Array: twiss alpha y of all charge states, [1]
ytwiss_gamma_all	Array: twiss gamma y of all charge states, [rad/m]
ztwiss_beta_all	Array: twiss beta z of all charge states, [rad/MeV/u]
ztwiss_alpha_all	Array: twiss alpha z of all charge states, [1]
ztwiss_gamma_all	Array: twiss gamma z of all charge states, [MeV/u/rad]
couple_xy	float: weight average of normalized x-y coupling term, [1]
couple_xpy	float: weight average of normalized xp-y coupling term, [1]
couple_xyp	float: weight average of normalized x-yp coupling term, [1]
couple_xpyp	float: weight average of normalized xp-yp coupling term, [1]
couple_xy_all	Array: normalized x-y coupling term of all charge states, [1]
couple_xpy_all	Array: normalized xp-y coupling term of all charge states, [1]
couple_xyp_all	Array: normalized x-yp coupling term of all charge states, [1]
couple_xpyp_all	Array: normalized xp-yp coupling term of all charge states, [1]
last_caviphi0	float: Last RF cavity's driven phase, [deg]
transfer_matrix	Array: Transfer matrix of the last element

Configuration methods

clone()	Return a copy of Beamstate object.
set_twiss(coor[, alpha, beta, rmssize, ...])	Set moment1 matrix by using Twiss parameter.
get_twiss(coor[, cs])	Get twiss parameters of moment1 matrix
set_couple(coor1, coor2[, value, cs])	Set normalized coupling term of moment1 matrix
get_couple(coor1, coor2[, cs])	Get normalized coupling term of moment1 matrix

Parameters

s :

FLAME state object Created by allocState()

bmstate :

BeamState object, priority: high

machine :

FLAME machine object, priority: middle

latfile :

FLAME lattice file name, priority: low

Notes

• If more than one keyword parameters are provided, the selection policy follows the priority from high to low.

• If only s is assigned with all-zeros states (usually created by allocState({}) method), then please note that this state can only propagate from the first element, i.e. SOURCE (from_element parameter of run() or propagate() should be 0), or errors happen; the better initialization should be passing one of keyword parameters of machine and latfile to initialize the state to be significant for the propagate() method.

• 1. These attributes are only valid for the case of sim_type being defined as MomentMatrix, which is de facto the exclusive option used at FRIB.

  2. If the attribute is an array, new array value should be assigned instead of by element indexing way, e.g.

  >>> bs = BeamState(s)
  >>> print(bs.moment0)
  array([[ -7.88600000e-04],
          [  1.08371000e-05],
          [  1.33734000e-02],
          [  6.67853000e-06],
          [ -1.84773000e-04],
          [  3.09995000e-04],
          [  1.00000000e+00]])
  >>> # the right way to just change the first element of the array
  >>> m_tmp = bs.moment0
  >>> m_tmp[0] = 0
  >>> bs.moment0 = m_tmp
  >>> print(bs.moment0)
  array([[  0.00000000e+00],
          [  1.08371000e-05],
          [  1.33734000e-02],
          [  6.67853000e-06],
          [ -1.84773000e-04],
          [  3.09995000e-04],
          [  1.00000000e+00]])
  >>> # while this way does not work: ms.moment0[0] = 0
  

property state

flame._internal.State: FLAME state object, also could be initialized with BeamState object

property pos

float: longitudinally propagating position, [m]

property ref_beta

float: speed in the unit of light velocity in vacuum of reference charge state, Lorentz beta, [1]

property ref_bg

float: multiplication of beta and gamma of reference charge state, [1]

property ref_gamma

float: relativistic energy of reference charge state, Lorentz gamma, [1]

property ref_IonEk

float: kinetic energy of reference charge state, [eV/u]

property ref_IonEs

float: rest energy of reference charge state, [eV/u]

property ref_IonQ

int: macro particle number of reference charge state, [1]

property ref_IonW

float: total energy of reference charge state, [eV/u], i.e. \(W = E_s + E_k\)

property ref_IonZ

float: reference charge to mass ratio, e.g. \(^{33^{+}}_{238}U: Q(33)/A(238)\), [Q/A]

property ref_phis

float: absolute synchrotron phase of reference charge state, [rad]

property ref_SampleIonK

float: wave-vector in cavities with different beta values of reference charge state, [rad]

property ref_SampleFreq

float: sampling frequency of reference charge state, [Hz]

property ref_Brho

float: magnetic rigidity of reference charge state, [Tm]

property beta

Array: speed in the unit of light velocity in vacuum of all charge states, Lorentz beta, [1]

property bg

Array: multiplication of beta and gamma of all charge states, [1]

property gamma

Array: relativistic energy of all charge states, Lorentz gamma, [1]

property IonEk

Array: kinetic energy of all charge states, [eV/u]

property IonEs

Array: rest energy of all charge states, [eV/u]

property IonQ

Array: macro particle number of all charge states

Notes

This is what NCharge means in the FLAME lattice file.

property IonW

Array: total energy of all charge states, [eV/u], i.e. \(W = E_s + E_k\)

property IonZ

Array: all charge to mass ratios

Notes

This is what IonChargeStates means in the FLAME lattice file.

property phis

Array: absolute synchrotron phase of all charge states, [rad]

property SampleIonK

Array: wave-vector in cavities with different beta values of all charge states, [rad]

property SampleFreq

Array: sampling frequency of all charge states, [Hz]

property Brho

float: magnetic rigidity of reference charge state, [Tm]

property moment0_env

Array: weight average of centroid for all charge states, array of [x, x', y, y', phi, dEk, 1], with the units of [mm, rad, mm, rad, rad, MeV/u, 1].

Notes

The physics meanings for each column are:

• x: x position in transverse plane;

• x': x divergence;

• y: y position in transverse plane;

• y': y divergence;

• phi: longitudinal beam length, measured in RF frequency;

• dEk: kinetic energy deviation w.r.t. reference charge state;

• 1: should be always 1, for the convenience of handling corrector (i.e. orbtrim element)

property moment0_rms

Array: rms beam envelope, part of statistical results from moment1.

See also

moment1

covariance matrices of all charge states

Notes

The square of moment0_rms should be equal to the diagonal elements of moment1.

property moment0

Array: centroid for all charge states, array of [x, x', y, y', phi, dEk, 1]

property moment1

Array: covariance matrices of all charge states, for each charge state, the covariance matrix could be written as:

\[\begin{split}\begin{array}{ccccccc} \color{red}{\left<x \cdot x\right>} & \left<x \cdot x'\right> & \left<x \cdot y\right> & \left<x \cdot y'\right> & \left<x \cdot \phi\right> & \left<x \cdot \delta E_k\right> & 0 \\ \left<x'\cdot x\right> & \color{red}{\left<x'\cdot x'\right>} & \left<x'\cdot y\right> & \left<x'\cdot y'\right> & \left<x'\cdot \phi\right> & \left<x'\cdot \delta E_k\right> & 0 \\ \left<y \cdot x\right> & \left<y \cdot x'\right> & \color{red}{\left<y \cdot y\right>} & \left<y \cdot y'\right> & \left<y \cdot \phi\right> & \left<y \cdot \delta E_k\right> & 0 \\ \left<y'\cdot x\right> & \left<y'\cdot x'\right> & \left<y'\cdot y\right> & \color{red}{\left<y'\cdot y'\right>} & \left<y'\cdot \phi\right> & \left<y'\cdot \delta E_k\right> & 0 \\ \left<\phi \cdot x\right> & \left<\phi \cdot x'\right> & \left<\phi \cdot y\right> & \left<\phi \cdot y'\right> & \color{red}{\left<\phi \cdot \phi\right>} & \left<\phi \cdot \delta E_k\right> & 0 \\ \left<\delta E_k \cdot x\right> & \left<\delta E_k \cdot x'\right> & \left<\delta E_k \cdot y\right> & \left<\delta E_k \cdot y'\right> & \left<\delta E_k \cdot \phi\right> & \color{red}{\left<\delta E_k \cdot \delta E_k\right>} & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 \end{array}\end{split}\]

property moment1_env

Array: averaged covariance matrices of all charge states

property x0

Array: x centroid for all charge states, [mm]

property xp0

Array: x centroid divergence for all charge states, [rad]

property y0

Array: y centroid for all charge states, [mm]

property yp0

Array: y centroid divergence for all charge states, [rad]

property phi0

Array: longitudinal beam length, measured in RF frequency for all charge states, [rad]

property dEk0

Array: kinetic energy deviation w.r.t. reference charge state, for all charge states, [MeV/u]

property x0_env

float: weight average of all charge states for \(x\), [mm]

property xp0_env

float: weight average of all charge states for \(x'\), [rad]

property y0_env

float: weight average of all charge states for \(y\), [mm]

property yp0_env

float: weight average of all charge states for \(y'\), [rad]

property phi0_env

float: weight average of all charge states for \(\phi\), [rad]

property dEk0_env

float: weight average of all charge states for \(\delta E_k\), [MeV/u]

property xrms_all

Array: general rms beam envelope for \(x\) of all charge states, [mm]

property xprms_all

Array: general rms beam envelope for \(x'\) of all charge states, [rad]

property yrms_all

Array: general rms beam envelope for \(y\) of all charge states, [mm]

property yprms_all

Array: general rms beam envelope for \(y'\) of all charge states, [rad]

property phirms_all

Array: general rms beam envelope for \(\phi\) of all charge states, [rad]

property dEkrms_all

Array: general rms beam envelope for \(\delta E_k\) of all charge states, [MeV/u]

property x0_rms

float: general rms beam envelope for \(x\), [mm]

property xp0_rms

float: general rms beam envelope for \(x'\), [rad]

property y0_rms

float: general rms beam envelope for \(y\), [mm]

property yp0_rms

float: general rms beam envelope for \(y'\), [rad]

property phi0_rms

float: general rms beam envelope for \(\phi\), [rad]

property dEk0_rms

float: general rms beam envelope for \(\delta E_k\), [MeV/u]

property last_caviphi0

float: Last RF cavity’s driven phase, [deg]

property transfer_matrix

Array: Transfer matrix of the last element

clone()

Return a copy of Beamstate object.

property xemittance

float: weight average of geometrical x emittance, [mm-mrad]

property yemittance

float: weight average of geometrical y emittance, [mm-mrad]

property zemittance

float: weight average of geometrical z emittance, [rad-MeV/u]

property xemittance_all

Array: geometrical x emittance of all charge states, [mm-mrad]

property yemittance_all

Array: geometrical y emittance of all charge states, [mm-mrad]

property zemittance_all

Array: geometrical z emittance of all charge states, [rad-MeV/u]

property xnemittance

float: weight average of normalized x emittance, [mm-mrad]

property ynemittance

float: weight average of normalized y emittance, [mm-mrad]

property znemittance

float: weight average of normalized z emittance, [rad-MeV/u]

property xnemittance_all

Array: normalized x emittance of all charge states, [mm-mrad]

property ynemittance_all

Array: normalized y emittance of all charge states, [mm-mrad]

property znemittance_all

Array: normalized z emittance of all charge states, [rad-MeV/u]

property xtwiss_beta

float: weight average of twiss beta x, [m/rad]

property ytwiss_beta

float: weight average of twiss beta y, [m/rad]

property ztwiss_beta

float: weight average of twiss beta z, [rad/MeV/u]

property xtwiss_beta_all

Array: twiss beta x of all charge states, [m/rad]

property ytwiss_beta_all

Array: twiss beta y of all charge states, [m/rad]

property ztwiss_beta_all

Array: twiss beta z of all charge states, [rad/MeV/u]

property xtwiss_alpha

float: weight average of twiss alpha x, [1]

property beammatrix

Array: averaged covariance matrices of all charge states

property beammatrix_all

Array: covariance matrices of all charge states, for each charge state, the covariance matrix could be written as:

\[\begin{split}\begin{array}{ccccccc} \color{red}{\left<x \cdot x\right>} & \left<x \cdot x'\right> & \left<x \cdot y\right> & \left<x \cdot y'\right> & \left<x \cdot \phi\right> & \left<x \cdot \delta E_k\right> & 0 \\ \left<x'\cdot x\right> & \color{red}{\left<x'\cdot x'\right>} & \left<x'\cdot y\right> & \left<x'\cdot y'\right> & \left<x'\cdot \phi\right> & \left<x'\cdot \delta E_k\right> & 0 \\ \left<y \cdot x\right> & \left<y \cdot x'\right> & \color{red}{\left<y \cdot y\right>} & \left<y \cdot y'\right> & \left<y \cdot \phi\right> & \left<y \cdot \delta E_k\right> & 0 \\ \left<y'\cdot x\right> & \left<y'\cdot x'\right> & \left<y'\cdot y\right> & \color{red}{\left<y'\cdot y'\right>} & \left<y'\cdot \phi\right> & \left<y'\cdot \delta E_k\right> & 0 \\ \left<\phi \cdot x\right> & \left<\phi \cdot x'\right> & \left<\phi \cdot y\right> & \left<\phi \cdot y'\right> & \color{red}{\left<\phi \cdot \phi\right>} & \left<\phi \cdot \delta E_k\right> & 0 \\ \left<\delta E_k \cdot x\right> & \left<\delta E_k \cdot x'\right> & \left<\delta E_k \cdot y\right> & \left<\delta E_k \cdot y'\right> & \left<\delta E_k \cdot \phi\right> & \color{red}{\left<\delta E_k \cdot \delta E_k\right>} & 0 \\ 0 & 0 & 0 & 0 & 0 & 0 & 0 \end{array}\end{split}\]

property cenvector

Array: weight average of centroid for all charge states, array of [x, x', y, y', phi, dEk, 1], with the units of [mm, rad, mm, rad, rad, MeV/u, 1].

Notes

The physics meanings for each column are:

• x: x position in transverse plane;

• x': x divergence;

• y: y position in transverse plane;

• y': y divergence;

• phi: longitudinal beam length, measured in RF frequency;

• dEk: kinetic energy deviation w.r.t. reference charge state;

• 1: should be always 1, for the convenience of handling corrector (i.e. orbtrim element)

property cenvector_all

Array: centroid for all charge states, array of [x, x', y, y', phi, dEk, 1]

property cxpy

float: weight average of normalized xp-y coupling term, [1]

property cxpy_all

Array: normalized xp-y coupling term of all charge states, [1]

property cxpyp

float: weight average of normalized xp-yp coupling term, [1]

property cxpyp_all

Array: normalized xp-yp coupling term of all charge states, [1]

property cxy

float: weight average of normalized x-y coupling term, [1]

property cxy_all

Array: normalized x-y coupling term of all charge states, [1]

property cxyp

float: weight average of normalized x-yp coupling term, [1]

property cxyp_all

Array: normalized x-yp coupling term of all charge states, [1]

property dEkcen

float: weight average of all charge states for \(\delta E_k\), [MeV/u]

property dEkcen_all

Array: kinetic energy deviation w.r.t. reference charge state, for all charge states, [MeV/u]

property dEkrms

float: general rms beam envelope for \(\delta E_k\), [MeV/u]

property phicen

float: weight average of all charge states for \(\phi\), [rad]

property phicen_all

Array: longitudinal beam length, measured in RF frequency for all charge states, [rad]

property phirms

float: general rms beam envelope for \(\phi\), [rad]

property rmsvector

Array: rms beam envelope, part of statistical results from moment1.

See also

moment1

covariance matrices of all charge states

Notes

The square of moment0_rms should be equal to the diagonal elements of moment1.

property transmat

Array: Transfer matrix of the last element

property xcen

float: weight average of all charge states for \(x\), [mm]

property xcen_all

Array: x centroid for all charge states, [mm]

property xeps

float: weight average of geometrical x emittance, [mm-mrad]

property xeps_all

Array: geometrical x emittance of all charge states, [mm-mrad]

property xepsn

float: weight average of normalized x emittance, [mm-mrad]

property xepsn_all

Array: normalized x emittance of all charge states, [mm-mrad]

property xpcen

float: weight average of all charge states for \(x'\), [rad]

property xpcen_all

Array: x centroid divergence for all charge states, [rad]

property xprms

float: general rms beam envelope for \(x'\), [rad]

property xrms

float: general rms beam envelope for \(x\), [mm]

property xtwsa

float: weight average of twiss alpha x, [1]

property xtwsa_all

Array: twiss alpha x of all charge states, [1]

property xtwsb

float: weight average of twiss beta x, [m/rad]

property xtwsb_all

Array: twiss beta x of all charge states, [m/rad]

property xtwsg

float: weight average of twiss gamma x, [rad/m]

property xtwsg_all

Array: twiss gamma x of all charge states, [rad/m]

property ycen

float: weight average of all charge states for \(y\), [mm]

property ycen_all

Array: y centroid for all charge states, [mm]

property yeps

float: weight average of geometrical y emittance, [mm-mrad]

property yeps_all

Array: geometrical y emittance of all charge states, [mm-mrad]

property yepsn

float: weight average of normalized y emittance, [mm-mrad]

property yepsn_all

Array: normalized y emittance of all charge states, [mm-mrad]

property ypcen

float: weight average of all charge states for \(y'\), [rad]

property ypcen_all

Array: y centroid divergence for all charge states, [rad]

property yprms

float: general rms beam envelope for \(y'\), [rad]

property yrms

float: general rms beam envelope for \(y\), [mm]

property ytwiss_alpha

float: weight average of twiss alpha y, [1]

property ytwsa

float: weight average of twiss alpha y, [1]

property ytwsa_all

Array: twiss alpha y of all charge states, [1]

property ytwsb

float: weight average of twiss beta y, [m/rad]

property ytwsb_all

Array: twiss beta y of all charge states, [m/rad]

property ytwsg

float: weight average of twiss gamma y, [rad/m]

property ytwsg_all

Array: twiss gamma y of all charge states, [rad/m]

property zcen

float: weight average of all charge states for \(\phi\), [rad]

property zcen_all

Array: longitudinal beam length, measured in RF frequency for all charge states, [rad]

property zeps

float: weight average of geometrical z emittance, [rad-MeV/u]

property zeps_all

Array: geometrical z emittance of all charge states, [rad-MeV/u]

property zepsn

float: weight average of normalized z emittance, [rad-MeV/u]

property zepsn_all

Array: normalized z emittance of all charge states, [rad-MeV/u]

property zpcen

float: weight average of all charge states for \(\delta E_k\), [MeV/u]

property zpcen_all

Array: kinetic energy deviation w.r.t. reference charge state, for all charge states, [MeV/u]

property zprms

float: general rms beam envelope for \(\delta E_k\), [MeV/u]

property zprms_all

Array: general rms beam envelope for \(\delta E_k\) of all charge states, [MeV/u]

property zrms

float: general rms beam envelope for \(\phi\), [rad]

property zrms_all

Array: general rms beam envelope for \(\phi\) of all charge states, [rad]

property ztwsa

float: weight average of twiss alpha z, [1]

property ztwsa_all

Array: twiss alpha z of all charge states, [1]

property ztwsb

float: weight average of twiss beta z, [rad/MeV/u]

property ztwsb_all

Array: twiss beta z of all charge states, [rad/MeV/u]

property ztwsg

float: weight average of twiss gamma z, [MeV/u/rad]

property ztwsg_all

Array: twiss gamma z of all charge states, [MeV/u/rad]

property ztwiss_alpha

float: weight average of twiss alpha z, [1]

property xtwiss_alpha_all

Array: twiss alpha x of all charge states, [1]

property ytwiss_alpha_all

Array: twiss alpha y of all charge states, [1]

property ztwiss_alpha_all

Array: twiss alpha z of all charge states, [1]

property xtwiss_gamma

float: weight average of twiss gamma x, [rad/m]

property ytwiss_gamma

float: weight average of twiss gamma y, [rad/m]

property ztwiss_gamma

float: weight average of twiss gamma z, [MeV/u/rad]

property xtwiss_gamma_all

Array: twiss gamma x of all charge states, [rad/m]

property ytwiss_gamma_all

Array: twiss gamma y of all charge states, [rad/m]

property ztwiss_gamma_all

Array: twiss gamma z of all charge states, [MeV/u/rad]

property couple_xy

float: weight average of normalized x-y coupling term, [1]

property couple_xpy

float: weight average of normalized xp-y coupling term, [1]

property couple_xyp

float: weight average of normalized x-yp coupling term, [1]

property couple_xpyp

float: weight average of normalized xp-yp coupling term, [1]

property couple_xy_all

Array: normalized x-y coupling term of all charge states, [1]

property couple_xpy_all

Array: normalized xp-y coupling term of all charge states, [1]

property couple_xyp_all

Array: normalized x-yp coupling term of all charge states, [1]

property couple_xpyp_all

Array: normalized xp-yp coupling term of all charge states, [1]

set_twiss(coor, alpha=None, beta=None, rmssize=None, emittance=None, nemittance=None, cs=0)

Set moment1 matrix by using Twiss parameter.

Parameters

coorstr

Coordinate of the twiss parameter,　‘x’, ‘y’, or ‘z’.

alphafloat

Twiss alpha, [1].

betafloat

Twiss beta, [m/rad] for ‘x’ and ‘y’, [rad/MeV/u] for ‘z’.

rmssizefloat

RMS size of the real space, [mm] of ‘x’ and ‘y’, [rad] for ‘z’.

emittancefloat

Geometrical (Unnormalized) emittance, [mm-mrad] for ‘x’ and ‘y’, [rad-MeV/u] for ‘z’.

nemittancefloat

Normalized emittance, [mm-mrad] for ‘x’ and ‘y’, [rad-MeV/u] for ‘z’.

csint

Index of the charge state to set parameter.

Notes

‘nemittance’ is ignored if both ‘emittance’ and ‘nemittance’ are input.

get_twiss(coor, cs=0)

Get twiss parameters of moment1 matrix

Parameters

coorstr

Coordinate of the twiss parameter,　‘x’, ‘y’, or ‘z’.

csint

Index of the charge state (-1 for weight average of all charge states).

Returns

twissarray

Twiss [alpha, beta, gamma] of the beam.

get_couple(coor1, coor2, cs=0)

Get normalized coupling term of moment1 matrix

Parameters

coor1str

First coordinate of the coupling term, ‘x’, xp, ‘y’, ‘yp’, ‘z’, or ‘zp’.

coor2str

Second coordinate of the coupling term, ‘x’, xp, ‘y’, ‘yp’, ‘z’, or ‘zp’.

csint

Index of the charge state (-1 for weight average of all charge states).

Returns

termfloat

Normalized coupling term of coor1 and coor2 of cs-th charge state.

set_couple(coor1, coor2, value=0.0, cs=0)

Set normalized coupling term of moment1 matrix

Parameters

coor1str

First coordinate of the coupling term, ‘x’, xp, ‘y’, ‘yp’, ‘z’, or ‘zp’.

coor2str

Second coordinate of the coupling term, ‘x’, xp, ‘y’, ‘yp’, ‘z’, or ‘zp’.

valuefloat

Normalized coupling term, (-1 ~ +1) [1].

csint

Index of the charge state.

class flame_utils.ModelFlame(lat_file=None, **kws)

Bases: object

General FLAME modeling class.

Class attributes:

latfile	str: FLAME lattice file name.
machine	FLAME machine object.
bmstate	Initial beam condtion for the simulation.

Class methods

generate_latfile([latfile, original, state])	Generate lattice file for the usage of FLAME code.
find(*args, **kws)	Find element indexs.
reconfigure(index, properties)	Reconfigure FLAME model.
run([bmstate, from_element, to_element, ...])	Simulate model.
collect_data(result, *args, **kws)	Collect data of interest from propagation results.
insert_element([index, element, econf])	Insert new element to the machine.
get_element([name, index, type])	Element inspection, get properties.
configure(econf)	Configure FLAME model.
get_all_types()	Get all uniqe element types.
get_all_names()	Get all uniqe element names.
get_index_by_type([type, rtype])	Get element(s) index by type(s).
get_index_by_name([name, rtype])	Get index(s) by name(s).
get_transfer_matrix([from_element, ...])	Calculate the complete transfer matrix from one element (from_element) to another (to_element).
convert_results(res, **kws)	Convert all beam states of results generated by run() method to be BeamState object.
inspect_lattice()	Inspect FLAME machine and print out information.
clone_machine()	Clone FLAME Machine object.

Parameters

lat_filestr

FLAME lattice file, if not set, None.

See also

BeamState

FLAME beam state class for MomentMatrix simulation type.

Examples

>>> from flame import Machine
>>> from flame_utlis import ModelFlame
>>>
>>> latfile = "lattice/test.lat"
>>> fm1 = ModelFlame()
>>> # manually initialization
>>> fm1.latfile = latfile
>>> m = Machine(latfile)
>>> fm1.machine = m
>>> fm1.bmstate = m.allocState({})
>>> # or by explicitly calling:
>>> fm1.machine, fm1.bmstate = fm1.init_machine(latfile)
>>>
>>> # initialize with valid lattice file
>>> fm2 = ModelFlame(lat_file=latfile)
>>>
>>> # (Recommanded) initialize with BeamState
>>> fm = ModelFlame()
>>> bs = BeamState(machine=m)
>>> # now the attributes of ms could be arbitarily altered
>>> fm.bmstate = bs
>>> fm.machine = m
>>>
>>> # run fm
>>> obs = fm.get_index_by_type(type='bpm')['bpm']
>>> r, s = fm.run(monitor=obs)
>>>
>>> # get result, storing as a dict, e.g. data
>>> data = fm.collect_data(r, pos=True, x0=True, y0=True)

property latfile

str: FLAME lattice file name.

property machine

FLAME machine object.

property bmstate

Initial beam condtion for the simulation.

BeamState: Could be initialized with FLAME internal state or BeamState object.

See also

BeamState

FLAME beam state class created for MomentMatrix.

static init_machine(latfile)

Initialize FLAME machine.

Parameters

latfile :

FLAME lattice file.

Returns

tuple

Tuple of (m, s), where m is FLAME machine instance, and s is initial machine states.

find(*args, **kws)

Find element indexs.

Parameters

typestr or list of str

Single element type name or list[tuple] of element type names.

Returns

list

Dict, key is type name, value if indice list of each type name, list, of indices list, with the order of type.

See also

get_index_by_type

Get element(s) index by type(s).

get_element(name=None, index=None, type=None, **kws)

Element inspection, get properties.

Returns

list of dict

List of dict of properties or empty list.

See also

get_element

Get element from FLAME machine object.

inspect_lattice()

Inspect FLAME machine and print out information.

See also

inspect_lattice

Inspect FLAME lattice file, print a brief report.

get_all_types()

Get all uniqe element types.

Returns

list of str

List of element type names

See also

get_all_types

Get all unique types from a FLAME machine.

get_all_names()

Get all uniqe element names.

Returns

list of str

List of element names.

See also

get_all_names

Get all uniqe names from a FLAME machine.

get_index_by_type(type='', rtype='dict')

Get element(s) index by type(s).

Parameters

typestr or list of str

Single element type name or list[tuple] of element type names.

rtypestr

Return type, ‘dict’ (default) or ‘list’.

Returns

dict or list

Dict, key is type name, value if indice list of each type name, list, of indices list, with the order of type.

See also

get_index_by_type

Get element(s) index by type(s).

get_index_by_name(name='', rtype='dict')

Get index(s) by name(s).

Parameters

namelist or tuple of str

Single element name or list[tuple] of element names.

rtypestr

Return type, ‘dict’ (default) or ‘list’.

Returns

dict or list

Dict of element indices, key is name, value is index, list of element indices list.

See also

get_index_by_name

Get index(s) by element name(s).

run(bmstate=None, from_element=None, to_element=None, monitor=None, include_initial_state=True)

Simulate model.

Parameters

bmstate :

FLAME beam state object, also could be BeamState object, if not set, will use the one from ModelFlame object itself, usually is created at the initialization stage, see init_machine().

from_elementint or str

Element index or name of start point, if not set, will be the first element (0 for zero states, or 1).

to_elementint or str

Element index or name of end point, if not set, will be the last element.

monitorlist[int] or list[str] or ‘all’

List of element indice or names selected as states monitors, if set -1, will be a list of only last element. if set ‘all’, will be a list of all elements.

include_initial_statebool

Include initial beam state to the list of the results if monitor contains the initial location (default is True).

Returns

tuple

Tuple of (r, s), where r is list of results at each monitor points, s is BeamState object after the last monitor point.

See also

BeamState

FLAME BeamState class created for MomentMatrix type.

propagate

Propagate BeamState object for FLAME machine object.

Notes

This method does not change the input bmstate, while propagate changes.

static convert_results(res, **kws)

Convert all beam states of results generated by run() method to be BeamState object.

Parameters

reslist of tuple

List of propagation results.

Returns

list of tuple

Tuple of (r, s), where r is list of results at each monitor points, s is BeamState object after the last monitor point.

static collect_data(result, *args, **kws)

Collect data of interest from propagation results.

Parameters

result :

Propagation results with BeamState object.

args :

Names of attribute, separated by comma.

Returns

dict

Dict of {k1:v1, k2,v2...}, keys are from keyword parameters.

See also

collect_data

Get data of interest from results.

configure(econf)

Configure FLAME model.

Parameters

econf(list of) dict

Element configuration(s), see get_element(). Pass single element dict for source configuration.

See also

configure

Configure FLAME machine.

get_element

Get FLAME lattice element configuration.

Notes

Pass econf with a list of dict for applying batch configuring. This method is not meant for reconfigure source.

reconfigure(index, properties)

Reconfigure FLAME model.

Parameters

indexint or str

Element index (or name) to reconfigure.

propertiesdict

Element property to reconfigure.

See also

configure

Configure FLAME machine.

get_element

Get FLAME lattice element configuration.

Examples

>>> # Set gradient of 'quad1' to 0.245
>>> fm.reconfigure('quad1', {'B2': 0.245})

clone_machine()

Clone FLAME Machine object.

Returns

Machine

FLAME Machine object.

insert_element(index=None, element=None, econf=None)

Insert new element to the machine.

Parameters

econfdict

Element configuration (see get_element()).

indexint or str

Insert element before the index (or element name).

elementdict

Lattice element dictionary.

Notes

User must input ‘econf’ or ‘index and element’. If econf is defined, insert econf[‘properties’] element before econf[‘index’].

generate_latfile(latfile=None, original=None, state=None, **kws)

Generate lattice file for the usage of FLAME code.

Parameters

latfile :

File name for generated lattice file.

original :

File name for original lattice file to keep user comments and indents. (optional)

state :

BeamState object, accept FLAME internal State object also. (optional)

out :

New stream paramter, file stream. (optional)

start :

Start element (id or name) of generated lattice. (optional)

end :

End element (id or name) of generated lattice. (optional)

Returns

str

Generated filename, None if failed to generate lattice file.

Notes

• If latfile is not defined, will overwrite the input lattice file;

• If start is defined, user should define state also.

• If user define start only, the initial beam state is the same as the machine.

get_transfer_matrix(from_element=None, to_element=None, charge_state_index=0)

Calculate the complete transfer matrix from one element (from_element) to another (to_element).

Parameters

from_elementint or str

Element index or name of start point, if not set, will be the first element (0 for zero states, or 1).

to_elementint or str

Element index or name of end point, if not set, will be the last element.

charge_state_indexint

Index of charge state.

Returns

2D array

Transfer matrix.

flame_utils.collect_data(result, *args, **kws)

Collect data of interest from propagation results.

Parameters

result :

Propagation results with BeamState object.

args :

Names of attribute, separated by comma.

Returns

dict

Dict of {k1:v1, k2,v2...}, keys are from keyword parameters.

See also

BeamState

FLAME beam state class for MomentMatrix simulation type.

Notes

1. Set the data of interest with k=True as input will return the defined k value.

2. Invalid attribute names will be ignored.

Examples

>>> # get x0 and y0 array
>>> collect_data(r, x0=True, y0=True)
>>> # which is equivalent as:
>>> collect_data(r, 'x0', 'y0')
>>> # or:
>>> collect_data(r, 'x0', y0=True)

flame_utils.configure(machine=None, econf=None, **kws)

Configure FLAME machine.

Parameters

machine :

FLAME machine object.

econf(list of) dict

Element configuration(s).

Returns

mNew FLAME machine object

None if failed, else new machine object.

See also

get_element

Get FLAME lattice element configuration.

Notes

If wanna configure FLAME machine by conventional way, then c_idx and c_dict could be used, e.g. reconfigure one corrector of m: configure(machine=m, c_idx=10, c_dict={'theta_x': 0.001}) which is just the same as: m.reconfigure(10, {'theta_x': 0.001}).

Examples

>>> from flame import Machine
>>> from phantasy import flameutils
>>>
>>> latfile = 'test.lat'
>>> m = Machine(open(latfile, 'r'))
>>>
>>> # reconfigure one element
>>> e1 = flameutils.get_element(_machine=m, index=1)[0]
>>> print(e1)
{'index': 1, 'properties': {'L': 0.072, 'aper': 0.02,
 'name': 'LS1_CA01:GV_D1124', 'type': 'drift'}}
>>> e1['properties']['aper'] = 0.04
>>> m = flameutils.configure(m, e1)
>>> print(flameutils.get_element(_machine=m, index=1)[0])
{'index': 1, 'properties': {'L': 0.072, 'aper': 0.04,
 'name': 'LS1_CA01:GV_D1124', 'type': 'drift'}}
>>>
>>> # reconfiugre more than one element
>>> e_cor = flameutils.get_element(_machine=m, type='orbtrim')
>>> # set all horizontal correctors with theta_x = 0.001
>>> for e in e_cor:
>>>     if 'theta_x' in e['properties']:
>>>         e['properties']['theta_x'] = 0.001
>>> m = flameutils.configure(m, e_cor)

flame_utils.convert_results(res, **kws)

Convert all beam states of results generated by run() method to be BeamState object.

Parameters

reslist of tuple

List of propagation results.

Returns

list of tuple

Tuple of (r, s), where r is list of results at each monitor points, s is BeamState object after the last monitor point.

flame_utils.generate_latfile(machine, latfile=None, state=None, original=None, out=None, start=None, end=None)

Generate lattice file for the usage of FLAME code.

Parameters

machine :

FLAME machine object.

latfile :

File name for generated lattice file.

original :

File name for original lattice file to keep user comments and indents. (optional)

state :

BeamState object, accept FLAME internal State object also. (optional)

out :

New stream paramter, file stream. (optional)

start :

Start element (id or name) of generated lattice. (optional)

end :

End element (id or name) of generated lattice. (optional)

Returns

filenamestr

None if failed to generate lattice file, or the out file name.

Notes

• If latfile and out are not defined, will print all output to screen;

• If latfile and out are all defined, out stream is preferred;

• For other cases, choose one that is defined.

• If start is defined, user should define state also.

• If user define start only, the initial beam state is the same as the machine.

• Parameter out can also be StringIO, and get string by getvalue().

• To get element configuration only by m.conf(i) method, where m is flame.Machine object, i is element index, when some re-configuring operation is done, m.conf(i) will be update, but m.conf()["elements"] remains with the initial values.

Examples

>>> from flame import Machine
>>> latfile = 'test.lat'
>>> m = Machine(open(latfile))
>>> outfile1 = generate_latfile(m, latfile='out1.lat')
>>> m.reconfigure(80, {'theta_x': 0.1})
>>> outfile2 = generate_latfile(m, latfile='out2.lat')
>>> # recommand new way
>>> fout = open('out.lat', 'w')
>>> generate_latfile(m, out=fout)

flame_utils.get_all_names(latfile=None, _machine=None)

Get all uniqe names from a FLAME machine or lattice file.

Parameters

latfilestr

FLAME lattice file.

_machine :

FLAME machine object.

Returns

str or None

None if failed, or list of valid element types’ string names.

flame_utils.get_all_types(latfile=None, _machine=None)

Get all unique types from a FLAME machine or lattice file.

Parameters

latfile:

FLAME lattice file.

_machine:

FLAME machine object.

Returns

list

None if failed, or list of valid element types’ string names.

flame_utils.get_element(latfile=None, index=None, name=None, type=None, **kws)

Inspect FLAME lattice element, return properties.

Parameters

latfilestr

FLAME lattice file.

indexint

(list of) Element index(s).

namestr

(list of) Element name(s).

typestr

(list of) Element type(s).

Returns

reslist of dict or []

List of dict of properties or empty list

See also

get_index_by_name, get_index_by_type

get_intersection()

Get the intersection of input valid list/tuple.

Notes

• 1. If more than one optional paramters (index, name, type, _pattern) are provided, only return element that meets all these definitions.

  2. If getting by multiple indices/names/types, the order of returned list is void.

• Invalid element names or type names will be ignored.

Examples

>>> from flame import Machine
>>> from phantasy import flameutils
>>> latfile = 'lattice/test.lat'
>>> ename = 'LS1_CA01:CAV4_D1150'
>>> e = flameutils.get_element(name=ename, latfile=latfile)
>>> print(e)
[{'index': 27, 'properties': {'aper': 0.017, 'name': 'LS1_CA01:CAV4_D1150',
  'f': 80500000.0, 'cavtype': '0.041QWR', 'L': 0.24, 'phi': 325.2,
  'scl_fac': 0.819578, 'type': 'rfcavity'}}]
>>> # use multiple filters, e.g. get all BPMs in the first 20 elements
>>> e = flameutils.get_element(_machine=m, index=range(20), type='bpm')
>>> print(e)
[{'index': 18, 'properties': {'name': 'LS1_CA01:BPM_D1144', 'type': 'bpm'}},
 {'index': 5, 'properties': {'name': 'LS1_CA01:BPM_D1129', 'type': 'bpm'}}]
>>> # all these filters could be used together, return [] if found nothing
>>>
>>> # get names by regex
>>> e = flameutils.get_element(_machine=m, _pattern='FS1_BBS:DH_D2394_1.?')
>>> print(e)
[{'index': 1092, 'properties': {'L': 0.104065, 'aper': 0.07,
  'bg': 0.191062, 'name': 'FS1_BBS:DH_D2394_1', 'phi': 4.5, 'phi1': 7.0,
  'phi2': 0.0, 'type': 'sbend'}},
 {'index': 1101, 'properties': {'L': 0.104065, 'aper': 0.07,
  'bg': 0.191062, 'name': 'FS1_BBS:DH_D2394_10', 'phi': 4.5, 'phi1': 0.0,
  'phi2': 7.0, 'type': 'sbend'}}]

flame_utils.get_index_by_name(name='', latfile=None, rtype='dict', _machine=None)

Get index(s) by name(s).

Parameters

namestr or list of str

Single element name or list[tuple] of element names

latfile :

FLAME lattice file, preferred.

rtypestr

Return type, ‘dict’ (default) or ‘list’.

_machine :

FLAME machine object.

Returns

inddict or list

dict of element indices, key is name, value is index, list of element indices list

See also

flatten()

flatten recursive list.

Notes

If rtype is list, list of list would be returned instead of a dict, flatten() function could be used to flatten the list.

Examples

>>> from flame import Machine
>>> from phantasy import flameutils
>>> latfile = 'lattice/test.lat'
>>> m = Machine(open(latfile, 'r'))
>>> names = 'LS1_CA01:SOL1_D1131_1'
>>> print(flameutils.get_index_by_name(name=names, latfile=latfile))
{'LS1_CA01:SOL1_D1131_1': [8]}
>>> print(flameutils.get_index_by_name(name=names, _machine=m))
{'LS1_CA01:SOL1_D1131_1': [8]}
>>> names = ['LS1_CA01:SOL1_D1131_1', 'LS1_CA01:CAV4_D1150',
>>>          'LS1_WB01:BPM_D1286', 'LS1_CA01:BPM_D1144']
>>> print(flameutils.get_index_by_name(name=names, latfile=latfile))
{'LS1_CA01:SOL1_D1131_1': [8], 'LS1_WB01:BPM_D1286': [154],
 'LS1_CA01:BPM_D1144': [18], 'LS1_CA01:CAV4_D1150': [27]}
>>> # return a list instead of dict
>>> print(flameutils.get_index_by_name(name=names, latfile=latfile, rtype='list'))
[[8], [27], [154], [18]]

flame_utils.get_index_by_type(type='', latfile=None, rtype='dict', _machine=None)

Get element(s) index by type(s).

Parameters

typestr or list of str

Single element type name or list[tuple] of element type names.

latfile :

FLAME lattice file, preferred.

rtypestr

Return type, ‘dict’ (default) or ‘list’.

_machine :

FLAME machine object.

Returns

inddict or list

Dict, key is type name, value if indice list of each type name, list, of indices list, with the order of type.

See also

flatten()

flatten recursive list.

Notes

If rtype is list, list of list would be returned instead of a dict, flatten() function could be used to flatten the list.

Examples

>>> from flame import Machine
>>> from phantasy import flameutils
>>> latfile = 'lattice/test.lat'
>>> m = Machine(open(latfile, 'r'))
>>> types = 'stripper'
>>> print(flameutils.get_index_by_type(type=types, latfile=latfile))
{'stripper': [891]}
>>> print(flameutils.get_index_by_type(type=types, _machine=m))
{'stripper': [891]}
>>> types = ['stripper', 'source']
>>> print(flameutils.get_index_by_type(type=types, latfile=latfile))
{'source': [0], 'stripper': [891]}
>>> # return a list instead of dict
>>> print(flameutils.get_index_by_type(type=types, latfile=latfile, rtype='list'))
[[891], [0]]

flame_utils.get_names_by_pattern(pattern='.*', latfile=None, _machine=None)

Get element names by regex defined by pattern.

Parameters

patternstr

Regex to search element name.

latfile :

FLAME lattice file, preferred.

_machine :

FLAME machine object.

Returns

namesList

List of element names, if not found, return None.

flame_utils.inspect_lattice(latfile=None, out=None, _machine=None)

Inspect FLAME lattice file, print a lattice information report, if failed, print nothing.

Parameters

latfile :

FLAME lattice file.

out :

output stream, stdout by default.

_machine :

FLAME machine object.

Returns

None

None if failed, or print information.

Examples

>>> from flame import Machine
>>> from phantasy import flameutils
>>> latfile = 'lattice/test.lat'
>>> m = Machine(open(latfile, 'r'))
>>> flameutils.inspect_lattice(_machine=m)
Inspecting lattice: <machine>
==============================
TYPE        COUNT   PERCENTAGE
------------------------------
SOURCE       1       0.08
STRIPPER     1       0.08
QUADRUPOLE   40      3.22
BPM          75      6.04
SOLENOID     78      6.28
SBEND        80      6.44
RFCAVITY     117     9.42
ORBTRIM      120     9.66
DRIFT        730    58.78
>>> # pass the latfile parameter
>>> flameutils.inspect_lattice(latfile=latfile)
Inspecting lattice: test.lat
==============================
TYPE        COUNT   PERCENTAGE
------------------------------
SOURCE       1       0.08
STRIPPER     1       0.08
QUADRUPOLE   40      3.22
BPM          75      6.04
SOLENOID     78      6.28
SBEND        80      6.44
RFCAVITY     117     9.42
ORBTRIM      120     9.66
DRIFT        730    58.78
>>>
>>> ## write inspection message to other streams
>>> # write to file
>>> fout = open('test.out', 'w')
>>> flameutils.inspect_lattice(latfile=latfile, out=fout)
>>> fout.close()
>>>
>>> # write to string
>>> from StringIO import StringIO
>>> sio = StringIO()
>>> flameutils.inspect_lattice(latfile=latfile, out=sio)
>>> retstr = sio.getvalue()

flame_utils.propagate(machine=None, bmstate=None, from_element=None, to_element=None, monitor=None, **kws)

Propagate BeamState.

Parameters

machine :

FLAME machine object.

bmstate :

BeamState object.

from_elementint

Element index of start point, if not set, will be the first element.

to_elementint

Element index of end point, if not set, will be the last element.

monitorlist

List of element indice selected as states monitors, if set -1, will be a list of only last element.

Returns

tuple

None if failed, else tuple of (r, bs), where r is list of results at each monitor points, bs is BeamState object after the last monitor point.

See also

BeamState

FLAME beam state class created for MomentMatrix type.

flame_utils.machine_setter(_latfile=None, _machine=None, _handle_name=None)

set flame machine, prefer _latfile

Returns

FLAME machine object

flame_utils.flatten(nnn)

flatten recursively defined list or tuple

Parameters

nnn – recursively defined list or tuple

Returns

flattened list

Example

>>> l0 = [1,2,3,[4,5],[6,[7,8,[9,10,['x',['y']]]]]]
>>> l1 = flatten(l0)
>>> print(l1)
[1,2,3,4,5,6,7,8,9,10,'x','y']

flame_utils.get_intersection(**kws)

Get the intersection of all input keyword parameters, ignore empty list or tuple.

Returns

reslist

Examples

>>> a, b, c = [], [], []
>>> print(get_intersection(a=a,b=b,c=c))
[]
>>> a, b, c = [1], [2], []
>>> print(get_intersection(a=a,b=b,c=c))
[]
>>> a, b, c = [1,2], [2], []
>>> print(get_intersection(a=a,b=b,c=c))
[2]
>>> a, b, c = [1,2], [2], [2,3]
>>> print(get_intersection(a=a,b=b,c=c))
[2]
>>> a, b, c = [1,2], [3,4], [2,3]
>>> print(get_intersection(a=a,b=b,c=c))
[]

flame_utils.hplot(*args, **kws)

Plot beam state history with input arguments.

Parameters

machineobject

FLAME machine or ModelFlame object.

result :

List of beam state, generated by Machine.propagete() or ModelFlame.run() method.

argsstr

Beam state attributes to plot, seprated by comma. (see Note)

colorsdict

Color definition of each args.

latticebool

Plot lattice layout.

legendbool

Plot legend of args

csint

Index of the charge state to plot.

Notes

List of supported BeamState arguments

posfloat

Longitudinally propagating position, [m].

ref_betafloat

Speed in the unit of light velocity in vacuum of reference charge state, Lorentz beta.

ref_bgfloat

Multiplication of beta and gamma of reference charge state.

ref_gammafloat

Relativistic energy of reference charge state, Lorentz gamma.

ref_IonEkfloat

Kinetic energy of reference charge state, [eV/u].

ref_IonEsfloat

Rest energy of reference charge state, [eV/u].

ref_IonQint

Macro particle number of reference charge state.

ref_IonWfloat

Total energy of reference charge state, [eV/u], i.e. \(W = E_s + E_k\).

ref_IonZfloat

Reference charge to mass ratio, e.g. \(^{33^{+}}_{238}U: Q[33]/A[238]\).

ref_phisfloat

Absolute synchrotron phase of reference charge state, [rad].

ref_SampleIonKfloat

Wave-vector in cavities with different beta values of reference charge state.

betaArray

Speed in the unit of light velocity in vacuum of all charge states, Lorentz beta.

bgArray

Multiplication of beta and gamma of all charge states.

gammaArray

Relativistic energy of all charge states, Lorentz gamma.

IonEkArray

Kinetic energy of all charge states, [eV/u].

IonEsArray

Rest energy of all charge states, [eV/u].

IonQArray

Macro particle number of all charge states.

IonWArray

Total energy of all charge states, [eV/u], i.e. \(W = E_s + E_k\).

IonZArray

All charge to mass ratios

phisArray

Absolute synchrotron phase of all charge states, [rad]

SampleIonKArray

Wave-vector in cavities with different beta values of all charge states.

x0_env, xcenfloat

Weight average of all charge states for x’, [rad].

y0_env, ycenfloat

Weight average of all charge states for y, [mm].

xp0_env, xpcenfloat

Weight average of all charge states for x’, [rad].

yp0_env, ypcenfloat

Weight average of all charge states for y’, [rad].

phi0_env, phicen, zcen: float

Weight average of all charge states for \(\phi\), [rad].

dEk0_env, dEkcen, zpcenfloat

Weight average of all charge states for \(\delta E_k\), [MeV/u].

x0, xcen_allArray

X centroid for all charge states, [mm].

y0, ycen_allArray

Y centroid for all charge states, [mm].

xp0, xpcen_allArray

X centroid divergence for all charge states, [rad].

yp0, ypcen_allArray

Y centroid divergence for all charge states, [rad].

phi0, phicen_all, zcen_allArray

Longitudinal beam length, measured in RF frequency for all charge states, [rad].

dEk0, dEkcen_all, zpcen_allArray

Kinetic energy deviation w.r.t. reference charge state, for all charge states, [MeV/u].

x0_rms, xrmsfloat

General rms beam envelope for x, [mm].

y0_rms, yrmsfloat

General rms beam envelope for y, [mm].

xp0_rms, xprmsfloat

General rms beam envelope for x’, [rad].

yp0_rms, yprmsfloat

General rms beam envelope for y’, [rad].

phi0_rms, phirms, zrmsfloat

General rms beam envelope for \(\phi\), [rad].

dEk0_rms, dEkrms, zprmsfloat

General rms beam envelope for \(\delta E_k\), [MeV/u].

xrms_allArray

General rms beam envelope for x of all charge states, [mm].

yrms_allArray

General rms beam envelope for y of all charge states, [mm].

xprms_allArray

General rms beam envelope for x’ of all charge states, [rad].

yprms_allArray

General rms beam envelope for y’ of all charge states, [rad].

phirms_allArray

General rms beam envelope for \(\phi\) of all charge states, [rad].

dEkrms_allArray

General rms beam envelope for \(\delta E_k\) of all charge states, [MeV/u].

moment0_env, cenvectorArray

Weight average of centroid for all charge states, array of [x, x', y, y', phi, dEk, 1], with the units of [mm, rad, mm, rad, rad, MeV/u, 1].

moment0, cenvector_allArray

Centroid for all charge states, array of [x, x', y, y', phi, dEk, 1].

moment0_rms, rmsvectorArray

RMS beam envelope, part of statistical results from moment1.

moment1, beammatrix_allArray

Covariance matrices of all charge states, for each charge state.

moment1_env, beammatrixArray

Covariance matrices of all charge states, average over all charge states.

xemittance, xepsfloat

Weight average of geometrical x emittance, [mm-mrad].

yemittance, yepsfloat

Weight average of geometrical y emittance, [mm-mrad].

zemittance, zepsfloat

Weight average of geometrical z emittance, [rad-MeV/u].

xnemittance, xepsnfloat

Weight average of normalized x emittance, [mm-mrad].

ynemittance, yepsnfloat

Weight average of normalized y emittance, [mm-mrad].

znemittance, zepsnfloat

Weight average of normalized z emittance, [rad-MeV/u].

xemittance_all, xeps_allArray

Geometrical x emittance of all charge states, [mm-mrad].

yemittance_all, yeps_allArray

Geometrical y emittance of all charge states, [mm-mrad].

zemittance_all, zeps_allArray

Geometrical z emittance of all charge states, [rad-MeV/u].

xnemittance_all, xepsn_allArray

Normalized x emittance of all charge states, [mm-mrad].

ynemittance_all, yepsn_allArray

Normalized y emittance of all charge states, [mm-mrad].

znemittance_all, zepsn_allArray

Normalized z emittance of all charge states, [rad-MeV/u].

xtwiss_beta, xtwsbfloat

Weight average of twiss beta x, [m/rad].

ytwiss_beta, ytwsbfloat

Weight average of twiss beta y, [m/rad].

ztwiss_beta, ztwsbfloat

Weight average of twiss beta z, [rad/MeV/u].

xtwiss_alpha, xtwsafloat

Weight average of twiss alpha x, [1].

ytwiss_alpha, ytwsafloat

Weight average of twiss alpha y, [1].

ztwiss_alpha, ztwsafloat

Weight average of twiss alpha z, [1].

xtwiss_beta_all, xtwsb_allArray

Twiss beta x of all charge states, [m/rad].

ytwiss_beta_all, ytwsb_allArray

Twiss beta y of all charge states, [m/rad].

ztwiss_beta_all, ztwsb_allArray

Twiss beta z of all charge states, [rad/MeV/u].

xtwiss_alpha_all, xtwsa_allArray

Twiss alpha x of all charge states, [1].

ytwiss_alpha_all, ytwsa_allArray

Twiss alpha y of all charge states, [1].

ztwiss_alpha_all, ztwsa_allArray

Twiss alpha z of all charge states, [1].

couple_xy, cxyfloat

Weigth average of normalized x-y coupling term, [1].

couple_xpy, cxpyfloat

Weigth average of normalized xp-y coupling term, [1].

couple_xyp, cxypfloat

Weigth average of normalized x-yp coupling term, [1].

couple_xpyp, cxpypfloat

Weigth average of normalized xp-yp coupling term, [1].

couple_xy_all, cxy_allArray

Normalized x-y coupling term of all charge states, [1].

couple_xpy_all, cxpy_allArray

Normalized xp-y coupling term of all charge states, [1].

couple_xyp_all, cxyp_allArray

Normalized x-yp coupling term of all charge states, [1].

couple_xpyp_all, cxpyp_allArray

Normalized xp-yp coupling term of all charge states, [1].

Examples

>>> fm = ModelFlame(lat_file = 'userfile.lat')
>>> hplot('xrms', 'yrms', machine=fm)

class flame_utils.PlotLat(source, output=None, auto_scaling=False, starting_offset=0.0, **kws)

Bases: object

Lattice picture class from FLAME lattice file or FLAME Machine object.

Parameters

sourcestr or callable

File path of the lattic file (str) or FLAME Machine object (callable)

outputstr (None), optional

Output file name. If defined, the lattice plot is generated automatically.

auto_scalingbool (True), optional

Flag for y-axis scaling by strength of the optical elements

starting_offsetfloat (0.0), optional

Position offset of starting point in the lattice file

Attributes

typesdict

Element type list of the lattice. Each element type contains on-off ‘flag’, plotting ‘color’, and y-axis ‘scale’.

generate(start=None, end=None, xlim=None, ycen=0.0, yscl=1.0, aspect=5.0, legend=True, option=True, axes=None)

Generate matplotlib Axes class object from lattice file.

Parameters

startint

Index of the lattice start.

endint

Index of the lattice end.

xlimlist[2], optinal

Plot range of the lattice.

ycenfloat (0.0)

Vertical offset of the plot.

ysclfloat (1.0)

Plot scale of the element size

aspectfloat (5.0), optional

Aspect ratio of the picture.

legendbool

Add legend for the elements.

optionbool

Add optional setting for the plot.

Attributes

axescallable

Axes class object of matplotlib.

total_lengthfloat

Total length of the lattice.

output(window=True, fname=None, **kws)

Output the lattice picture to window and/or file.

Parameters

windowbool (True)

Output flag to the window.

fnamestr, optional

File path of the output picutre.

**kwargs :

The same kwargs as pyplot.savefig() are available.