ModelFlame Class

Machine control, configuration, and output

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)