Versions Compared

Old Version 11

changes.mady.by.user Zach Buschmann

Saved on

compared with

New Version Current

changes.mady.by.user Zach Buschmann

Saved on

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

Image Added


Table of Contents
Image Removed

Overview


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

Code is still WIP. Design details here are subject to change.

BmadLiveModel

The BmadLiveModel python class loads the FACET2E lattice and runs a local copy of Tao. The object connects to the production controls system via EPICS Channel Access and instantiates 4 daemon threads, three of which will monitor the controls system for live magnet/RF data and set devices in Tao accordingly, and a fourth which writes new model data to python data structures.

Modes of use

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

...

f2m = BmadLiveModel(instanced=True)

f2m.update_model_data()

# --> your code here

...

with BmadLiveModel() as f2m:

    # --> your code here

...

The infrastructure consists of two layers:

  • BmadLiveModel: a python class responsible for watching the accelerator and updating a live instance of PyTao based on extant machine settings
  • The live model PVA service: a process that runs it's own BmadLiveModel and publishes data to table PVs

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.

Device Monitoring

Connection to the production controls system is handled mainly via EPICS Channel Access PVs (as well as limited use of AIDA-PVA for klystron timing statuses). During real-time updating, there are three "watcher" daemon threads that monitor extant machine settings. Each thread will submit instructions for updates to the simulation to one of two shared update queues.

acc1-watcher and acc2-watcher

These are the main passive device monitoring threads. acc1 is responsible for monitoring all quadrupole magnets in the accelerator, while acc2 id responsible for monitoring dipoles, sextupoles and other miscellaneous devices.

LEM

LEM (LINAC energy management) is a set of algorithms responsible for estimating the beam momentum profile and calculating the corresponding lattice quad settings. This code only calculates the momentum profile, errors and magnet settings. Actually setting magnets in the accelerator will be handled by a LEM server GUI (coming soon...).

  • BmadLiveModel will monitors the klystron complement and bend magnet settings to calculate the live momentum profile of the beam
  • Periodically, the server will use the live momentum profile to calculate energy errors and magnet settings, which are published to a table PV

Detailed overview of LEM implementation: LEM_notes-3.pdf

LEM-watcher

Daemon thread spawned by BmadLiveModel, responsible for calculating the live beam momentum profile as described below, and for submitting update requests for cavity voltages and phases to the command queue, as well as linac amplitude, chirp and fudge values

PyTao updates

The BmadLiveModel python class loads the FACET2E lattice and runs a local copy of pytao.Tao. This instance of tao is both the engine used by the class to update the live lattice, as well as a part of the public interface of the code. BmadLiveModel.tao is a publicly accessible attribute of the class itself

model-update

This thread is responsible for executing all the submitted update requests using Tao, and for updating derived quantities (BLEM) and python data structures.

  1. empty the device update 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.bends, live.rf data structures
  4. empty the LEM update queue and set the live.LEM amplitude, chirp and fudge values

PVA model server(s)

The principal use case for the BmadLiveModel is running a real-time live model server. This server runs its own BmadLiveModel, and then publishes live model data to scalar and table PVs

Daemon process design

Controls system communication is asynchronous to maximize update frequency. Responsibility of each thread should be designed for load balancing, to maximize the live model response time.

At each iteration, the watcher threads will:

  1. check the PVs associated with every live device they are responsible for setting
  2. check if device setting has changed beyond some tolerance (exact tolerance band could be device dependent, picked to prevent analog/digital noise from prompting constant updates)
  3. push tao commands to a shared queue of updates (how implement?)

Separately, the model-update thread will do the following at each iteration:

  1. read in and execute the queue of tao commands
  2. write new data to the BmadLiveModel.live data structure

...

  • Monitor all linac subbooster & klystron amplitudes and phases (excepting TCAVs)
  • set cavity voltages and lag times in Tao accordingly

...

  • Monitor all quadrupole magnets
  • set field strengths in Tao

...

  • Monitor corrector magnets and any other miscellaneous magnets
  • set field strengths in Tao

...

  • execute queued Tao commands
  • Update the BmadLiveModel.live data structure

...

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 table PVs are as followscode for the live model itself is relatively simple, and is derived from the lcls_live_model server.

For performance, there are actually two production services. Both recalculate and update PVs once per second.

  • Model Server 1: This server is responsible for updating live twiss parameters and LEM data.
  • Model Server 2: This service is responsible for publishing R matrices

Access to the live Bmad model server (for twiss/rmat data), is mediated by the python meme service

Implementation: F2_live_model code

The code for all the infrastructure described in this document lives together. Source code can be viewed on GitHub, and API documentation is available online.

  • SLAC network master repository: /afs/slac/g/cd/swe/git/repos/slac/FACET/F2_live_model.git
  • Production deployment: /usr/local/tools/python/F2_live_model
  • GitHub mirror: F2_live_model.git
  • The public interface to the code is documented here: f2-live-model.readthedocs.io/

Details

Model server data description

PV nametable columnsnotes
BMAD:SYS0:1:FACET2E:LIVE:TWISSelement, device_name, s, z, length, p0c, alpha_x, beta_x, eta_x, etap_x, psi_x,  alpha_y, ..., psi_ynot sure if s and z are both helpful
BMAD:SYS0:1:FACET2E:LIVE:RMATelement, device_name, s, z, length, r11, r12, r13, r14, r15, r16, r21, r22, ..., r65, r66linear maps from the beginning of the linac to the downstream face of each element
BMAD:SYS0:1:FACET2E:LIVE:RMATURMATelement, device_name, s, z, length, r11, r12, r13, r14, r15, r16, r21, r22, ..., r65, r66single-element linear maps (i.e. from the upstream to downstream face of each)
BMAD:SYS0:1:FACET2E:DESIGN:TWISSelement, device_name, s, z, length, p0c, alpha_x, beta_x, eta_x, etap_x, psi_x,  alpha_y, ..., psi_y
BMAD:SYS0:1:FACET2E:DESIGN:RMATelement, device_name, s, z, length, r11, r12, r13, r14, r15, r16, r21, r22, ..., r65, r66
BMAD:SYS0:1:FACET2E:DESIGN:URMATelement, device_name, s, z, length, r11, r12, r13, r14, r15, r16, r21, r22, ..., r65, r66
BMAD:SYS0:1:FACET2E:LEM_:DATAelement, device_name, s, z, length, EREF, EACT, BREF, BACT, BERR, more ??single NTTable seems simpler than lcls-style per-device PVs

...

EERR, BLEM_DESIGN, BLEM_EXTANT

Additionally, the service will publish scalar PVs of the estimated linac amplitudes/chirps/fudges by calculated by LEM. Their names are as follows:

  • BMAD:SYS0:1:FACET2E:LEM:<XX>_FUDGE
  • BMAD:SYS0:1:FACET2E:LEM:<XX>_AMPL
  • BMAD:SYS0:1:FACET2E:LEM:<XX>_CHIRP

where <XX> is a "LEM region", either L0, L1, L2 or L3, for a total of an additional 12 PVs. (ex: BMAD:SYS0:1:FACET2E:LEM:L2_FUDGE). There is an additional read/write PV: BMAD:SYS0:1:FACET2E:LEM:PROFILE which stores the last known extant momentum profile to which current rf settings are compared. 

Dependencies

Source file descriptions

Source: F2_live_model/Details
docs/sphinx config files
config/model config files
    facet2e.yamlconfig for the FACET2E live model & server
    unaliased-elements.csvsupplemental text file of device alias (control system name) info
.readthedocs.yamlconfig for readthedocs.io doc generation
~/structs.pyauxiliary data structures for holding beamline data
~/bmad.pyimplements the BmadLiveModel class
~/

server.py

live model PVA service
~/receiver

demo.

pycontains functions for getting data from the live model PVA server (analogous to F2_ModelReceiver.m)

ipynb

Jupyter notebook with simple examples of how to use BmadLiveModel