CLS Orbit Control Notes

The number of orbit-control magnet (OCM) objects is currently defined in software as a preprocessor (compile-time) variable. To reflect the increased number of OCM channels introduced to the OrbitController’s domain as part of the hardware upgrades, the definition of NumOcm must be changed to follow suit (see orbitcontroller/include/Ocm.h).

NumOcm is used to derive NumHOcm and NumVOcm, the number of horizontal and vertical corrector channels, respectively. These variables are utilized primarily as bounds on looping operations over various containers. In particular, the dimensions of the (inverse) Response Matrices for each plane are partially determined by these parameters. Since the user interface (i.e. EPICS records) will create one Ocm object per record, it is possibleto do away entirely with the compile-time variables, as the number of Ocm objects will be implicitly given by the number that are created and stored in their respective containers. This approach will also permit the use of dynamically sized arrays, instead of fixed-size arrays. For example:

could then become:

with the dimensions given by:

Changes must also be to the control system interface of the project, found under orbitcontrolUI/. These changes are somewhat less obtrusive than those required to the source under orbitcontroller/, as in this case only EPICS database substitution files must be modified. In particular, this affects files of the form Ocm24*.sub under orbitcontrolUI/orbitcontrolUIApp/Db.

The substitution file-fields that need to be modified are:

Structurally, The OrbitControl system is based on a Model-View-Controller architecture (see figure below). The model objects are simply instances of Bpm or Ocm classes, manipulated via concrete instances of their respective controllers, either BpmController or OcmController classes. These controllers are interfaces: C++ classes containing only pure virtual methods. It is important to realize that the OrbitController is both an OcmController and a BpmController: utilizing multiple-inheritance, the OrbitController provides implementations for both pure-virtual controller classes.

Conventionally, the "View" in an MVC design is a GUI element such as a text-field or button. In this case, the "View" is not a specific element, as the control-points of the software are exposed via Channel Access and therefore do not require a GUI at all in order to be accessed. In fact, it is probably more accurate to classify the system as simply a Model-Controller architecture, with Channel Access as the interface between the "Controller" and any conventional GUI widgets that might be utilized.

Upon closer inspection of the architectural details, the classes and active objects (i.e. threads) appear as shown below ([resource-view]):

This representation of the OrbitController illustrates several key concepts:

From the user’s perspective, including the newer MatLab control program, the OrbitController is essentially a Finite State Machine (FSM). The runtime behavior of the OrbitController, including BPM data acquisition and orbit-correction algorithm application, may be altered simply by instructing the FSM to transition to one of the following states:

The behavior of the OrbitController is represented in the following image of the [FSM]. However, it should be noted that not all states are depicted in this image (for purely aesthetic reasons).

From the developer’s point of view, the FSM is implemented using a variation of the State Pattern, as presented in the book, ""Design Patterns: Elements of Reusable Object-Oriented Software", by Erich Gamma et al. This pattern permits the addition of States by simply sub-classing the appropriate class, and implementing the required abstract (pure virtual) methods, stateAction(), stateEntry(), and stateExit().

As mentioned, there are 54 sets of BPMs in the storage ring, each of which provides two, primary process variables: an x-position and a y-position, represented as analog input (ai) records. The OrbitController’s BpmControl thread simply produces averages of the digitized x and y BPM signals collected by the AdcReader threads (see [resource-view] figure). It is those averages that populate the database records, BPM14aa-bb:x and BPM14aa-bb:y.

Although not yet utilized by operations, there are also 54 sets of standard deviations produced for the corresponding x and y BPM average positions. These are records with names like, BPM14aa-bb:x:sigma or , BPM14aa-bb:y:sigma. These values are are also calculated by the BpmControl thread.

As previously mentioned, the effect of disabling a BPM x or y channel is not fully understood or dealt with. However, the database binary-out records with names like, BPM14aa-bb:isInCorrection, are intended to provide the interface to such functionality. Note that this interface is intended to disable both the x and y BPM channels as a unit.

Two other groups of analog-output records utilized in the orbit-correction algorithm are those with names like BPM14aa-bb:x:ref (reference, or "Golden Orbit") and BPM14aa-bb:x:offs (offset). These values are typically set by the MatLab program as part of initializing the system for "fast", autonomous operations, and are seldom changed during operation. The OrbitController linearly combines these numbers with the current BPM average positions and this result forms the vector, $\Delta x$, utilized in the expression, $\Delta \theta_x = R^{-1}\Delta x$, given previously.

There are three, thus far undiscussed, records remaining in the [BPM-database] figure. These records may not properly be grouped with the others of that figure, but their placement is for reasons of conciseness. Actually, these records are part of the OrbitController's interface. Their utility is discussed below:

As of version v3.0.1 of the OrbitController, the set of "fast" orbit-correctors consists of 48 OCM. The records controlling the setpoints of the power-supplies for these have names ending in ":dac" (eg: OCM14aa-bb:dac). Those records with the suffix of ":fbk" are not feedback from the power-supply channels: they are feedback on the setpoint values, as the OrbitController has no physical means of obtaining true power-supply current values.

Once the hardware modifications are in place to incorporate the dual-purpose sextupole magnets into the "fast" orbit-correction algorithm, there will need to be records created to control them. Place-holder values already exist in the various "*.sub" (substitution) files, but they are commented out. At this point, please consult the file, "orbitcontrolUI/Db/README.OCM.ringOrder". It contains crucial further details for this stage of the upgrade process.

The records with names of the pattern, OCM14aa-bb:delay, control the amount of spin-delay (in micro-seconds) required for correct operation of the OCM setpoint delivery. This delay is necessary, as the VMIC-2536 hardware contains optical-isolators with relatively long rise and (especially) fall-times. The nominal (worst-case) settings of 35 micro-seconds are issued to each channel upon record initialization, and need not be altered.

Enabling and disabling of OCM channels is accomplished via those records with names like, OCM14aa-bb:isInCorrection. Note that this does not actually enable or disable a channel, but rather only admits or omits that channel from participating in the orbit correction algorithm. Thus, the correction calculated for that channel may or may not be distributed depending on the setting of these records.

The three remaining families of records in the [OCM-database] figure are not actually associated with any physical OCM channel. They exist to provide support the mathematical operations of the orbit-control algorithm. Each record receives it values from the operator’s MatLab program. They are briefly discussed here: