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.

empty the device update queue of (approximately*) all submitted updates
run all the set ele commands, then re-calculate lattice parameters
update the live.p0c, live.e_tot, live.twiss, live.quads, live.bends, live.rf data structures
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:

check the PVs associated with every live device they are responsible for setting
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)
push tao commands to a shared queue of updates (how implement?)

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

read in and execute the queue of tao commands
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 name	table columns	notes
`BMAD:SYS0:1:FACET2E:LIVE:TWISS`	`element, device_name, s, z, length, p0c, alpha_x, beta_x, eta_x, etap_x, psi_x, alpha_y, ..., psi_y`not sure if s and z are both helpful
`BMAD:SYS0:1:FACET2E:LIVE:RMAT`	`element, device_name, s, z, length, r11, r12, r13, r14, r15, r16, r21, r22, ..., r65, r66`	linear maps from the beginning of the linac to the downstream face of each element
`BMAD:SYS0:1:FACET2E:LIVE:RMATURMAT`	`element, device_name, s, z, length, r11, r12, r13, r14, r15, r16, r21, r22, ..., r65, r66`	single-element linear maps (i.e. from the upstream to downstream face of each)
`BMAD:SYS0:1:FACET2E:DESIGN:TWISS`	`element, 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:RMAT`	`element, device_name, s, z, length, r11, r12, r13, r14, r15, r16, r21, r22, ..., r65, r66`
`BMAD:SYS0:1:FACET2E:DESIGN:URMAT`	`element, device_name, s, z, length, r11, r12, r13, r14, r15, r16, r21, r22, ..., r65, r66`
`BMAD:SYS0:1:FACET2E:LEM_:DATA`	`element, 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

numpy, scipy
pyEPICS
p4p
Bmad + Tao
Pytao
facet2-lattice
The live model needs to run on the production network (primarily on facet-srv02)

Source file descriptions

Source: `F2_live_model/`	Details
`docs/`	sphinx config files
`config/`	model config files
`facet2e.yaml`	config for the FACET2E live model & server
`unaliased-elements.csv`	supplemental text file of device alias (control system name) info
`.readthedocs.yaml`	config for readthedocs.io doc generation
`~/structs.py`	auxiliary data structures for holding beamline data
`~/bmad.py`	implements 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`

Confluence and Jira now require federated login. Read more.

Page tree

Versions Compared

Old Version 10

New Version Current

Key

Overview

BmadLiveModel

Modes of use

`BmadLiveModel`

Device Monitoring

`acc1-watcher` and `acc2-watcher`

LEM

`LEM-watcher`

`PyTao` updates

`model-update`

PVA model server(s)

Daemon process design

F2 Live Model Server

Implementation: `F2_live_model` code

Details

Model server data description

Dependencies

Source file descriptions

Confluence and Jira now require federated login. Read more.

Page tree

Page History

Versions Compared

Old Version 10

New Version Current

Key

Overview

BmadLiveModel

Modes of use

BmadLiveModel

Device Monitoring

acc1-watcher and acc2-watcher

LEM

LEM-watcher

PyTao updates

model-update

PVA model server(s)

Daemon process design

F2 Live Model Server

Implementation: F2_live_model code

Details

Model server data description

Dependencies

Source file descriptions

`BmadLiveModel`

`acc1-watcher` and `acc2-watcher`

`LEM-watcher`

`PyTao` updates

`model-update`

Implementation: `F2_live_model` code