Overview

This page summarizes the design & implementation of the interface between the live FACET-II controls system and the FACET2E Bmad model.

GitHub mirror: F2_live_model.git

API documentation: f2-live-model.readthedocs.io/

BmadLiveModel

The goal of this class is to provide access to an instance of Tao that can view/manipulate the FACET2 Bmad model with settings that match those of the actual production accelerator.

The BmadLiveModel python class loads the FACET2E lattice and runs a local copy of pytao.SubprocessTao This object connects to the production controls system via EPICS Channel Access, and connects callback functions to each live quantity (PV) of interest. When live quantities change, these callbacks will submit update instructions to a shared queue. Additionally, a daemon thread (model-update) will periodically empty the queue and execute all the scheduled update commands and then update the BmadLiveModel.live data structure.

Modes of use

The BmadLiveModel can be used in three distinct modes, depending on the input flags at construction:

f2m = BmadLiveModel(design_only=True)

f2m = BmadLiveModel(instanced=True)
f2m.refresh_all() 
# --> your code here

f2m = BmadLiveModel()
f2m.start()
# --> your code here
f2m.stop

with BmadLiveModel() as f2m:
    # --> your code here

Daemon process design

This class makes use of both thread-level and process-level parallelism. Controls system monitoring, processing of update requests and data structure changes are handled asynchronously by callback functions and a model-update daemon thread. The Tao instance itself is contained in a separate subprocess via pytao.SubprocessTao.  Controls monitoring and device update management are handled asynchronously to optimize performance and minimize delays between changes being broadcast over the network and being mirrored in the model. Tao itself is wrapped in a subprocess for handling Fortran errors, and calls to BmadLiveModel.tao will still block the main python executable

PV callback functions are responsible for the following actions:

1. convert the new value into Bmad units (i.e. from kGm → T, GeV → eV etc)
2. submit a tuple of (element name, attribute, value) to the queue

Separately, the model-update thread will run forever in a loop, at each iteration it will:

1. empty the command queue of (approximately*) all submitted updates
2. run all the set ele commands, then re-calculate lattice parameters
3. update the live.p0c, live.e_tot, live.twiss, live.quads, live.xcors, live.ycors, live.bends, live.rf data structures (← or update on request?)

LEM

LEM (LINAC energy management) is responsible for estimating the beam momentum profile pz(s), calculating the corresponding lattice quad settings. The server-side algorithm is as follows: 

1. calculate the current beam momentum profile, pz_live(s)

   1. start with an estimated momentum profile based on reported klystron amplitudes & phases

      
   2. the actual final energy of the beam in each linac is known, given by the spectrometer bend magnet setting. The momentum profile is (approximately) a monotonically increasing function of s between these points
   3. calculate a "fudge" for each linac (defined as E_estimated / E_design)
   4. use this value to scale the estimated momentum profile to match the design energies. pz_live(s) = fudge * pz_estimated(s)
2. use the live momentum profile to calculate quad settings for the linac
   1. from design momentum profile:
      1. calculate a dimensionless "LEM error", pz_err(s) = pz_live(s) / pz_design(s)
      2. calculate the new magnet BDESes as BDES_LEM = pz_err(s) * BDES_DESIGN, where B_DESIGN is the design value for each quad
   2. from design multipole coefficients (lcls style)
      1. get design multipole coefficients (k0_des, k1_des for bends/quads), and magnet lengths l_eff from the model
      2. calculate the rigidity Brho(s) = pz_live(s) (GeV) / 299.792458e4 
      3. calculate BDES_LEM = Brho * k_des * l_eff
3. publish B_LEM and related PVs to BMAD:SYS0:1:FACET2E:LEM_DATA

F2 Live Model Server

The live model server runs its own BmadLiveModel, and periodically writes live model data for NTTables accessible on the controls system via EPICS PVAccess. The code for the live model itself is relatively simple, and is derived from the lcls_live_model server.

Access to the live Bmad model server (for twiss/rmat data), should be provided through the python meme service

The format of the publish tables are as folllows:

Implementation details

Dependencies

The live model needs to run on the production network (primarily on facet-srv02)

• numpy, spicy
• pyEPICS
• p4p
• Bmad + Tao
• Pytao
• facet2-lattice

Source files