Tune PLL

This screen is used to manage the Tune Phase Locked Loop functionality. For this to work the tune PLL NCO must be driven to the bunches to be measured, and the tune PLL detector must be configured to measure the same bunches. Then once the appropriate phase has been identified as set as the target phase, the frequency of the NCO will be driven to keep the measured phase.

The PVs here are divided into a number of groups. All PVs are prefixed with $(device):$(axis).

Long waveforms of Tune PLL data can be captured using the Matlab Tune PLL capture script.

NCO

This group includes the readback waveform at the top.

Name	PV	Description
Tune Following Frequency	`:PLL:NCO:OFFSETWF`	This waveform records the complete history of the Tune PLL offset frequency
Offset FIFO readout overrun	`:PLL:NCO:FIFO_OVF`	This will report an alarm status if the `OFFSETWF` waveform overruns. Typically this can happen if the detector dwell time is set too low.
Reset FIFO	`:PLL:NCO:RESET_FIFO_S`	This will force the `OFFSETWF` to discard any partially captured data. This is used to ensure that the next update received for `MEAN_OFFSET` is fully up to date.

All the PVs in the NCO group directly affect or measure the frequency generated by the tune PLL NCO.

Name	PV	Description
Freq	`:PLL:NCO:FREQ_S`	When written this will set the PLL NCO to the given frequency. If feedback is running the offset will briefly be forced to zero.
	`:PLL:NCO:FREQ`	This reads back the current NCO frequency. This PV updates at 10Hz.
Offset	`:PLL:NCO:OFFSET`	This is the current PLL offset, updated at 10Hz.
Gain	`:PLL:NCO:GAIN_S`	The NCO signal strength is configured here.
	`:PLL:NCO:ENABLE_S`	This PV turns the NCO output on or off.
Mean	`:PLL:NCO:MEAN_OFFSET`	This is the mean offset computed over the last full `OFFSETWF` waveform.
Std	`:PLL:NCO:STD_OFFSET`	This is the standard deviation computed over the last full `OFFSETWF` waveform.
Tune	`:PLL:NCO:TUNE`	This is the fractional tune computed from the `MEAN_OFFSET` value and the base frequency. This PV updates when `MEAN_OFFSET` updates, and is forced to NaN when feedback is not running.

Detector

This group of PVs is used to configure the detector used to measure the response.

Name	PV	Description
Source	`:PLL:DET:SELECT_S`	Used to configure source of data for the detector. The possible sources are as documented for `:DET:SELECT_S` on Detector Overview. For Tune PLL the "ADC no fill" source is recommended.
Gain	`:PLL:DET:SCALING_S`	The magnitude of values read out from the detector as reported by `:PLL:FILT:MAG_DB` should be greater than -84dB to avoid loss of resolution in the phase measurement, and cannot be greater than 0dB without generating overflow. The dynamic range of the detector is much larger, and this gain control allows the readout scaling to be adjusted for best results.
Bunches		This links to the Detector Bunch Enables screen where the detector bunches can be configured.
	`:PLL:DET:COUNT`	This reports how many bunches are being measured by the detector.
Dwell	`:PLL:DET:DWELL_S`	This configures the number of turns used to measure a single detector value.
Blanking	`:PLL:DET:BLANKING_S`	This can be set to "Ignore", in which case the blanking trigger is ignored, or to "Blanking". If "Blanking" is selected, then while the blanking trigger (configured in Trigger Configuration) is active all inputs are ignored: both the detector and the feedback controller stand still. Note that updates are still generated: this ensures that any spectral measurements made using the `:PLL:NCO:OFFSETWF` waveform remain accurate.

Readbacks

The readback PVs show the current measurements from the detector, all updating at 10 Hz.

Name PV Description

I, Q

:PLL:FILT:I

:PLL:FILT:Q

Detector readbacks in I and Q components. To regard the response as a complex number, compute .

Magnitude

:PLL:FILT:MAG

:PLL:FILT:MAG_DB

Magnitude of the detector response and converted to dB, relative to overflow at magnitude = 1.0.

Phase :PLL:FILT:PHASE Phase of the detector response.

Debug Links to the Tune PLL Debug for a detailed view of the detector response.

:PLL:DEBUG:ENABLE_S This PV indicates whether the debug readbacks are enabled. This readback is normally not required, and the extra processing load can usefully be avoided by leaving this disabled when not required.

Mag rel std

:PLL:DEBUG:RSTD_ABS, :PLL:DEBUG:RSTD_ABS_DB

"Magnitude relative standard deviation". This pair of fields and "IQ rel std" below are an attempt to capture the quality of signal and lock as a single number. This number should be small if there is a strong detector signal, but is not affected by the quality of the lock. Given a debug IQ waveform the relative standard deviation here is calculated as:

The :RSTD_ABS_DB is simply .

IQ rel std

:PLL:DEBUG:RSTD, :PLL:DEBUG:RSTD_DB

"IQ relative standard deviation". This is intended to capture the quality of the PLL lock as a single number: this number should be small if there is little deviation in angle. Give waveform this is calculated as:

Again, :RSTD_DB is simply .

Status

The status indicators here show the status of the detector and the feedback controller, and show the reason for stopping if feedback is not running. When feedback is running all indicators in the left hand column will be green, otherwise one with be red to indicate a reason for stopping. Similarly the right hand column shows the current active state of each part of the Tune PLL system.

Name	Stop PV	Status PV	Description
Stopped by user	`:PLL:CTRL:STOP:STOP`		The controller has been deliberately stopped by triggering one of the stop PVs.
Detector overflow	`:PLL:CTRL:STOP:DET_OVF`	`:PLL:STA:DET_OVF`	The detector readout has overflowed. To avoid this condition reduce the readout gain `:PLL:DET:SCALING_S` as appropriate.
Magnitude error	`:PLL:CTRL:STOP:MAG_ERROR`	`:PLL:STA:MAG_ERROR`	The signal magnitude as measured by the detector is smaller than the threshold set in `:PLL:CTRL:MIN_MAG_S`. Avoid this by either increasing the detector readout gain or adjusting the threshold.
Offset overflow	`:PLL:CTRL:STOP:OFFSET_OVF`	`:PLL:STA:OFFSET_OVF`	The frequency offset has moved beyond the threshold set in `:PLL:CTRL:MAX_OFFSET_S`.

Config

The Tune PLL controller is a simple PI controller. The configuration for the controller is set here.

Name	PV	Description
Integral	`:PLL:CTRL:KI_S`	This is the integral term for the PI controller.
Proportional	`:PLL:CTRL:KP_S`	This is the proportional term for the PI controller.
Mag. limit	`:PLL:CTRL:MIN_MAG_S`	This sets a minimum value for the detector magnitude. The controller will stop if the value is too low. This should be set above 0.00005 to ensure adequate phase resolution.
Offset limit	`:PLL:CTRL:MAX_OFFSET_S`	This limits the maximum frequency offset excursion before the controller will stop.
Target Phase	`:PLL:CTRL:TARGET_S`	When the tune PLL controller is running it will work to maintain the readback phase `:PLL:FILT:PHASE` equal to this value.

Control

This group contains the top level running status PV and four controls for starting and stopping the tune PLL controller.

Name	PV	Description
Status	`:PLL:CTRL:STATUS`	Reports "Stopped" or "Running" depending whether the controller is running.
Start	`:PLL:CTRL:START_S`	Starts the controller if it is stopped.
Stop	`:PLL:CTRL:STOP_S`	Stops the controller if it is started.

The remaining two controls are slightly anomalous, as the are shared between both axes, and thus are only present in TMBF mode, and the PV names do not include the $(axis) component; thus the full names are written below.

Name	PV	Description
Start All	`$(device):PLL:CTRL:START_S`	Starts controllers on both axes simultaneously. If both controllers are configured with the same dwell time and are started together then they will remain synchronous.
Stop All	`$(device):PLL:CTRL:STOP_S`	Stops controllers on both axes simultaneously.