flame_utils.core package

Submodules

flame_utils.core.element module

Operations about FLAME machine elements, lattice is a special element.

flame_utils.core.element.get_all_types(latfile=None, _machine=None)[source]

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.core.element.get_all_names(latfile=None, _machine=None)[source]

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.core.element.inspect_lattice(latfile=None, out=None, _machine=None)[source]

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.core.element.get_element(latfile=None, index=None, name=None, type=None, **kws)[source]

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.core.element.get_index_by_type(type='', latfile=None, rtype='dict', _machine=None)[source]

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.core.element.get_index_by_name(name='', latfile=None, rtype='dict', _machine=None)[source]

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.core.element.get_names_by_pattern(pattern='.*', latfile=None, _machine=None)[source]

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.core.element.insert_element(machine=None, index=None, element=None)[source]

Insert new element to the machine.

Parameters
machine :

FLAME machine object.

index :

Insert element before the index (or element name).

element :

Lattice element dictionary. e.g. {‘name’:xxx, ‘type’:yyy, ‘L’:zzz}

Returns
machineFLAME machine object.

flame_utils.core.model module

Simulation/modeling with FLAME.

class flame_utils.core.model.ModelFlame(lat_file=None, **kws)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Inspect FLAME machine and print out information.

See also

inspect_lattice

Inspect FLAME lattice file, print a brief report.

get_all_types()[source]

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()[source]

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')[source]

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')[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Clone FLAME Machine object.

Returns
Machine

FLAME Machine object.

insert_element(index=None, element=None, econf=None)[source]

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)[source]

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)[source]

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.core.model.propagate(machine=None, bmstate=None, from_element=None, to_element=None, monitor=None, **kws)[source]

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.core.model.configure(machine=None, econf=None, **kws)[source]

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.core.state module

Abstracted FLAME beam state class.

class flame_utils.core.state.BeamState(s=None, **kws)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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.

flame_utils.core.state.generate_source(state, sconf=None)[source]

Generate/Update FLAME source element from FLAME beam state object.

Parameters
state :

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

sconfdict

Configuration of source element, if None, generate new one from state.

Returns
retdict

FLAME source element configuration.

See also

get_element

Get element from FLAME machine or lattice.

Notes

All zeros state may not produce reasonable result, for this case, the recommended way is to create a BeamState object with latfile or machine keyword parameter, e.g. s = BeamState(s0, machine=m), then use s as the input of generate_source.

flame_utils.core.state.get_brho(k, z)[source]

Get magnetic rigidity

Parameters
kfloat

Kinetic energy [eV/u]

zfloat

Charge to mass ratio, Q/A [1].

Returns
brhofloat

Magnetic rigidity [Tm].

flame_utils.core.state.couple_index(coor1, coor2)[source]

Get index from coordinate information

flame_utils.core.state.get_couple(matrix, coor1, coor2)[source]

Get normalized coupling term of moment1 matrix

Parameters
matrixArray

Covariance matrix of the beam.

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’.

Returns
termfloat

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

flame_utils.core.state.set_couple(matrix, coor1, coor2, value=0.0)[source]

Set normalized coupling term of moment1 matrix

Parameters
matrixArray

Covariance matrix of the beam.

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].

flame_utils.core.state.twiss_to_matrix(coor, alpha, beta, emittance, matrix=None)[source]

Set covariance 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’.

emittancefloat

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

matrixArray

Original covariance matrix of the beam

Module contents

class flame_utils.core.BeamState(s=None, **kws)[source]

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()[source]

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)[source]

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)[source]

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)[source]

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)[source]

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.

flame_utils.core.generate_source(state, sconf=None)[source]

Generate/Update FLAME source element from FLAME beam state object.

Parameters
state :

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

sconfdict

Configuration of source element, if None, generate new one from state.

Returns
retdict

FLAME source element configuration.

See also

get_element

Get element from FLAME machine or lattice.

Notes

All zeros state may not produce reasonable result, for this case, the recommended way is to create a BeamState object with latfile or machine keyword parameter, e.g. s = BeamState(s0, machine=m), then use s as the input of generate_source.

flame_utils.core.twiss_to_matrix(coor, alpha, beta, emittance, matrix=None)[source]

Set covariance 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’.

emittancefloat

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

matrixArray

Original covariance matrix of the beam

flame_utils.core.get_all_types(latfile=None, _machine=None)[source]

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.core.get_all_names(latfile=None, _machine=None)[source]

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.core.inspect_lattice(latfile=None, out=None, _machine=None)[source]

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.core.insert_element(machine=None, index=None, element=None)[source]

Insert new element to the machine.

Parameters
machine :

FLAME machine object.

index :

Insert element before the index (or element name).

element :

Lattice element dictionary. e.g. {‘name’:xxx, ‘type’:yyy, ‘L’:zzz}

Returns
machineFLAME machine object.
flame_utils.core.get_element(latfile=None, index=None, name=None, type=None, **kws)[source]

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.core.get_index_by_type(type='', latfile=None, rtype='dict', _machine=None)[source]

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.core.get_index_by_name(name='', latfile=None, rtype='dict', _machine=None)[source]

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.core.get_names_by_pattern(pattern='.*', latfile=None, _machine=None)[source]

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.core.propagate(machine=None, bmstate=None, from_element=None, to_element=None, monitor=None, **kws)[source]

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.core.configure(machine=None, econf=None, **kws)[source]

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)
class flame_utils.core.ModelFlame(lat_file=None, **kws)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Inspect FLAME machine and print out information.

See also

inspect_lattice

Inspect FLAME lattice file, print a brief report.

get_all_types()[source]

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()[source]

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')[source]

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')[source]

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)[source]

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)[source]

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)[source]

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)[source]

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)[source]

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()[source]

Clone FLAME Machine object.

Returns
Machine

FLAME Machine object.

insert_element(index=None, element=None, econf=None)[source]

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)[source]

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)[source]

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.