F2_live_model documentation

This is the API documentation for FACET-II Bmad live-modeling code.

class bmad.BmadLiveModel(design_only=False, instanced=False, log_level='INFO', log_handler=None)

Provides an instance of PyTao that is updated with live machine parameters. This class streams live accelerator settings data via asynchronus network monitoring and a daemon process that periodically updates Tao.

Has a limited API for common tasks, more sophisitcated tasks can manipulate the tao instance

Parameters:

  • design_only – disables connection to the controls system, defaults to False

  • instanced – take single-shot live data instead of streaming, defaults to False

  • log_level – desired logging level, defaults to ‘INFO’

  • FileHandler – (optional) FileHandler object for logging, otherwise logs to stdout

Raises:

ValueError – if design_only and instanced flags are both set

get_rmat(ele, which='model')

returns 6x6 ndarray of single-element or (if given 2 elements) A-to-B transfer maps

Note:

single-element transfer maps are calculated between the upstream and downstream faces of the element in question, while A-to-B transfer maps are calculated from the downstream face of element A and the downstream face of element B

Parameters:

  • ele – beamline element(s), may be a single element e or a tuple of (e1, e2)

  • which – which lattice to read from, default is ‘model’, can also choose ‘design’

Returns:

(R,v0) tuple of the map R (6x6 np.ndarray), and “0th order” map v0 (1x6 vector)

refresh_all(catch_errs=False)

single-shot model update (only for use with instanced models)

Parameters:

catch_errs – catch errors and log during update rather than halt, defaults to False

Raises:

RuntimeError – if the design_only flag is set, or instanced flag is not set

start()

starts daemon to monitor accelerator controls data & update PyTao

Raises:

RuntimeError – if the design_only or instanced flags are set

stop()

stop background processes

write_bmad(title=None)

save current lattice to a .bmad file, default title is f2_elec_<ymdhms>.bmad

Parameters:

title – absolute filepath for desired output file, default is the current directory

property L

length of all elements in s-order

property S

S position of all elements in s-order

property Z

linac Z position (floor coordinate) of all elements

property design

design model data, identical interface to live model data

property device_names

control system channel access addresse of all elements in s-order

property ele_types

Bmad ‘key’ (element type) of all elements in s-order

property elements

Bmad model names of all elements in s-order

property ix

dictionary of numerical indicies of various beamline elements

BmadLiveModel.ix['<ele_name>'] returns numerical indices for the given element in model data arrays ex: BmadLiveModel.L[ix['QE10525']] would return the length of QE10525

There are also some shortcut masks for quickly selecting all elements of a given type ix['QUAD'] will return the indicies of every quadrupole magnet in the model, valid masks are: RF, SOLN, XCOR, YCOR, COR, BEND, QUAD, SEXT, DRIFT, BPMS, PROF, DRIFT

Note:

mask indicies are equivalent to: np.where(self.ele_types == '<Bmad ele.key>')

property live

Data structure containing live model data.

Live momentum profile and twiss parameters are stored an Numpy arrays in s-order, while single-device information is accessed through a dictionary of device data structures.

top-level attributes are: live.p0c, e_tot, gamma_rel, Brho, twiss, rf, quads, bends

the twiss data structure contains the following fields (for x and y): twiss.beta_x, alpha_x, eta_x, etap_x, psi_x, gamma_x, ...

each device dictionary is indexed by element name (i.e. ‘QE10525’) and returns dataclasses describing the relevant live parameters, as well as s positions and lengths for convenience unique attributes are as follows: rf[<name>].voltage, rf[<name>].phi0, quads[<name>].b1_gradient

Note:

this interface is nonexhaustive, and only covers commonly used data

property tao

local instance of pytao.SubprocessTao

class structs._ModelData(p0c, e_tot, twiss)
property Brho

particle magnetic rigidity (for electrons) in kG m: Brho ~ 10 * E [MeV] / 300 = 10 * E [eV] / 0.3e9 (c)

bends

dictionary of _Dipole objects, indexed by element name

e_tot

total particle energy in eV

property gamma_rel

relativistic Lorentz factor

p0c

z-momentum profile in eV

quads

dictionary of _Quad objects, indexed by element name

rf

dictionary of _Cavity objects, indexed by element name

twiss

_Twiss dataclass

class structs._Cavity(S: float, l: float, voltage: float, phase: float)
class structs._Dipole(S: float, l: float, b_field: float, g: float)
class structs._F2LEMData(L0: structs._LEMRegionData, L1: structs._LEMRegionData, L2: structs._LEMRegionData, L3: structs._LEMRegionData)
class structs._Quad(S: float, l: float, b1_gradient: float, k1: float)
class structs._Twiss(beta_x: numpy.ndarray, beta_y: numpy.ndarray, alpha_x: numpy.ndarray, alpha_y: numpy.ndarray, eta_x: numpy.ndarray, eta_y: numpy.ndarray, etap_x: numpy.ndarray, etap_y: numpy.ndarray, psi_x: numpy.ndarray, psi_y: numpy.ndarray)
class server.f2LiveModelServer(design_only=False, log_level='INFO', log_handler=None)
This class is used to run the live model PVA server. It uses a BmadLiveModel to

periodically update NTTable PVs with model data.

This service publishes PVs of the following form: BMAD:SYS0:1:<source>:<data> where

source is LIVE or DESIGN and data is TWISS, RMAT or URMAT.

Note:

Running server.py as a script will start the service.

Note:

When active, this service will update a heartbeat PV: PHYS:SYS1:1:MODEL_SERVER

run()

connect the BmadLiveModel to the accelerator and begins updating PVs with live data

Note:

this function will execute forever until either an exception occurs or a KeyboardInterrupt is provided to signal a stop