CBETA-V, the Virtual Machine, and EPICS

CBETA-V

CBETA-V is a custom version of Tao, written by David Sagan. It has all of the normal functionality of Tao, but with a few extra commands to allow access to EPICS. In order to make use of these commands, the lattice has to be marked up in various ways.

Lattice additions

All of the lattice additions for CBETA are made in separate files named something similar to epics-overlays.bmad.

Interaction with the lattice is done via BMAD overlays or through the element description. In both cases, it needs to be named with a particular style in order for CBETA-V to realize that it is associated with an EPICS record. Here are some examples of these naming requirements

• BPMs

The description of the element is changed to indicate what the EPICS records for the position and intensity are.

IS1BPM01[descrip] = "IS1BPM01_{H/V/I}"

• Corrector magnets

An overlay is made for the bl_hkick or bl_vkick. The overlay needs to have "_field_diff" in the name.

MS1CRV01_field_diff: overlay = {MS1CRV01[bl_vkick]:value}, var = {value}, value = MS1CRV01[bl_vkick]

• Dipole magnets with non-zero design bend angle

Similarly to corrector magnets, an overlay is made for the g_err. In addition, a "zero_offset" is added, which is used when the beam energy is not the design energy (see the command dipole_set, below.

MS1DIP01_field_diff: overlay = {MS1DIP01[G_ERR]:-c_light*(value+zero_offset)/p042 + MS1DIP01[G_ERR]}, var = {value,zero_offset}, value = 0, zero_offset = 0

• Focusing magnets

For quads and solenoids, the overlay is made for the field values, e.g. the b1_gradient.

MB1QUB01_field: overlay = {MB1QUB01[B1_GRADIENT]:value}, var = {value}, value = MB1QUB01[B1_GRADIENT]

• RF Cavities

For RF cavities, overlays are made for both the gradient and gradient error, phi0 and phi0_err.

RD1CAV01_voltage_ref:       overlay = {RD1CAV01[gradient]:value/1},     var = {value}, value = RD1CAV01[gradient]
RD1CAV01_voltage_diff:      overlay = {RD1CAV01[gradient_err]:value/1}, var = {value}, value = RD1CAV01[gradient_err]
RD1CAV01_relative_ph_ref:   overlay = {RD1CAV01[phi0]:value/360},           var = {value}, value = RD1CAV01[phi0]*360
RD1CAV01_relative_ph_diff: overlay = {RD1CAV01[phi0_err]:value/360},       var = {value}, value = RD1CAV01[phi0_err]*360

Custom commands

Once these lattice additions have been made, the following commands will interact with EPICS and either set or read the values of the overlays.

• get_epics : Get values of machine parameters and store them in the lattice overlays.
• put_epics : Set the values of the machine parameters (careful!) from the values in CBETA-V
• dipole_set : Scale the zero_offset parameter of dipole magnets, using the ratio of the beam energy to the lattice reference energy.

The Virtual Machine

The virtual machine is a set of python scripts written by Colwyn that do the following things.

• Create a set of "virtual" EPICS records to mimic records in the real machine (both controls and diagnostics)
• Start an instance of CBETA-V
• Monitor the virtual EPICS records for changes, and if detected, then run them through the lattice and output all simulated diagnostics

Starting a virtual machine

• Go to the directory /nfs/erl/online/epics/pcaspy/virtual_machine/
• Run the command: python3.6 virtual_machine.py -n 0 -l 1p -v -N 1200
  • -n 0 : This runs virtual machine 0 on the current computer. Other integers can be used for more than one VM at a time.
  • -l 1p : This selects the 1-pass lattice
  • -v : Verbose output
  • -N 1200 : All output data will be at 1200 equally spaced s-positions. Higher numbers take longer to calculate, but make prettier plots

Example virtual EPICS records

All virtual records have the same name as the real machine records, except with a prefix appended at the beginning. The prefix is something like vm0@erp122: which would be the prefix for virtual machine 0 on the computer erp122.

For example:

• BPM Data : vm0@erp122:IS1BPM01_H, ...
• Magnet commands : vm0@erp122:MS1QUA01_cmd, ...

EPICS controls for the virtual machine

All magnet and cavity control screens in EDM can be toggled between real and virtual machines. In the upper-right corner of their control screen will be a button that will select between "Real" for the real machine and a set of pre-defined virtual machines labeled by their computer. When interacting with a virtual machine, the window should change to a greenish background so there is no confusion.

Example: (left size) real controls for A1-A3 magnets. (right side) virtual machine controls.

There is also a screen for the extra commands that can be issued to the virtual machine

• Find "CBETA-V" on the main EDM screen.
• 
• Clicking it will open up a new window with a few simple commands
• 
• The buttons perform the following functions
  • Simulation Done : Red = the simulation is currently running, Green = simulation is finished
  • Synchronize to machine : Manual = all controls can be adjusted. Sync = controls are forced to be equal their real machine counterparts
  • Autoscale dipoles : If the simulated energy is not precisely equal to 42 MeV, then this button will scale all dipoles (S1, R1, ...) so that the beam is put back onto the design trajectory
  • Kill VM : A safer way to kill the virtual machine, compared to hitting Ctrl-C in the window it was run in. Guaranteed to kill all subprocesses.

Diagnostics for the virtual machine

Right now the primary diagnostic for the virtual machine is the Matlab script "cbv", which is covered in its own Wiki.