Tutorial

1. Basic usage

In Python interface (include IPython-notebook), user can import flame_utils ModelFlame class.

from flame_utils import ModelFlame

Create ModelFlame object with input lattice file.

fm = ModelFlame(lat_file = 'userfile.lat')

run() simulation through the lattice.

r, s = fm.run()

Here s is the BeamState object at the end of the lattice section.

User can obtain various beam parameter which listed in BeamState docstring.

s.xrms       # returns horizontal(x) rms beam size
s.ref_IonEk  # returns reference beam energy

Plot result by using hplot().

from flame_utils import hplot
hplot('xrms', 'yrms', machine=fm)

User can observe the beam state history by using monitor keyword in run().

r, s = fm.run(monitor = 'all')  # observe the beam state in all elements

Here r contains the list of (index, BeamState) for each lattice element.

Also, obtain list of beam parameters along the lattice by using collect_data().

d = fm.collect_data(r, 'pos', 'xrms', 'yrms')
d['xrms']  # list of xrms along the lattice

Plot by using matplotlib

import matplotlib.pyplot as plt
plt.plot(d['pos'], d['xrms'])
plt.plot(d['pos'], d['xrms'])

or plot by using hplot().

from flame_utils import hplot
hplot('xrms', 'yrms', machine=fm, result=r)

2. Initial beam parameter control

bmstate returns initial BeamState of the input lattice file.

fm.bmstate.xrms # initial xrms size

User can change the initial beam condition by using set_twiss().

fm.bmstate.set_twiss('x', rmssize = 0.7)
# set xrms size to 0.7 mm with the same emittance

3. Lattice element parameter control

find() index of the lattice element.

fm.find(type='quadrupole')  # find by type
>>> [4, 6, 8, 28, 30, 32, 44, 46, 48, 56, 58, 60, 64, 66, 68, 78, 80, 82, 84]
fm.find(name='qd1')         # find by name
>>> [78]

Check element information by get_element().

fm.get_element(index = 78)    # get by index
# or
fm.get_element(name = 'qd1')  # get by name
>>> [{'index': 78,
    'properties': {'aper': 0.025,
    'name': 'qd1',
    'type': 'quadrupole',
    'L': 0.4107,
    'B2': 10.0}}]

Change the element parameter by reconfigure().

fm.reconfigure(78, {'B2': 8.0})     # set new parameter by index
# or
fm.reconfigure('qd1', {'B2': 8.0})  # set new parameter by name

Use can find all elements properies in Lattice elements .

Save new setting to the file by generate_latfile().

fm.generate_latfile(latfile='New.lat', original='userfile.lat')

4. Advanced use cases

In run() method, user can define from_element, to_element and bmstate as an initial condition.

r1, s1 = fm.run(to_element=56)               # simulate to 56th element
r2, s2 = fm.run(bmstate=s1, from_element=57) # simulate from 57th element

This result should be the same as

r, s = fm.run()

These are benefits to minimize the simulation time by selecting the re-calculation section.

Notes

In the case of user put monitor = 'all' in run(), the index of r is consistent with the lattice index in get_element().

r1, s1 = fm.run(monitor='all')
r2, s2 = fm.run(to_element=78)

Here r1[78][1] is the same as s2.