pyaml.tuning_tools.tune#

Betatron-tune measurement and correction tools.

The Tune tool reads horizontal and vertical betatron tune, computes quadrupole-strength corrections from a response matrix, and applies those corrections to the configured quadrupole array.

Classes

Tune(name, quad_array_name, response_matrix)

Adjust the horizontal and vertical betatron tunes.

class pyaml.tuning_tools.tune.Tune(name, quad_array_name, response_matrix, betatron_tune_name='BETATRON_TUNE')#

Bases: TuningTool, DynamicValidation

Adjust the horizontal and vertical betatron tunes.

The tune correction is calculated from a response matrix describing the change in horizontal and vertical tune produced by changes in quadrupole strength. The pseudo-inverse of this matrix is used to convert a requested tune change into the corresponding quadrupole-strength changes.

The response matrix may be supplied directly as a ResponseMatrixData instance or loaded from a file. The tune is measured using the configured betatron tune monitor, while corrections are applied through the configured quadrupole array.

Parameters:

name (str) – Name of the tuning tool.
quad_array_name (str) – Name of the quadrupole array used to adjust the tune.
response_matrix (str or ResponseMatrixData) – Tune response matrix or path to a file containing the response matrix. The matrix is expected to have one row for each tune plane and one column for each quadrupole.
betatron_tune_name (str, optional) – Name of the betatron tune monitor used to measure the horizontal and vertical tunes. The default is "BETATRON_TUNE".

Attributes

`quad_array_name`	Name of the configured quadrupole array.
`betatron_tune_name`	Name of the configured betatron tune monitor.
`quadrupoles`	Quadrupole array used by the correction.
`tune_monitor`	Betatron tune monitor used by the correction.
`response_matrix`	Loaded tune response matrix.

Methods

`load()`	Load a tune response matrix and prepare its pseudoinverse.
`get()`	Return the requested horizontal and vertical tune setpoint.
`readback()`	Return the current horizontal and vertical betatron tune.
`set()`	Iteratively correct the betatron tune to a requested setpoint.
`correct()`	Calculate quadrupole-strength changes for a tune change.
`add()`	Apply a tune correction relative to the current setpoint.

Configuration

- type: pyaml.tuning_tools.tune
  name: TUNE_CORRECTION
  quad_array_name: QUADRUPOLES
  betatron_tune_name: BETATRON_TUNE
  response_matrix: path/to/tune_response.json

add(dtune, wait_time=0.0)#

Apply a tune correction relative to the current setpoint.

Parameters:

dtune (np.array) – Horizontal and vertical tune change to apply (dimensionless).
wait_time (float) – Delay in seconds after changing quadrupole strengths.

correct(dtune)#

Calculate quadrupole-strength changes for a tune change.

Parameters:: dtune (np.array) – Desired horizontal and vertical tune change (dimensionless).
Returns:: numpy.ndarray – Quadrupole-strength changes calculated from the response-matrix pseudoinverse, in the configured quadrupole strength units (typically m^-1).
Raises:: PyAMLException – If no response matrix has been loaded.
Return type:: array

get()#: Return the requested dimensionless horizontal and vertical tune setpoint.

load(load_path)#

Load a tune response matrix and prepare its pseudoinverse.

Parameters:: load_path (Path) – Path to the serialized ResponseMatrixData file.

readback()#: Return the current dimensionless horizontal and vertical betatron tune.

set(tune, iter=1, wait_time=0.0)#

Iteratively correct the betatron tune to a requested setpoint.

Parameters:

tune (np.array) – Target horizontal and vertical tune values (dimensionless).
iter (int) – Number of correction iterations.
wait_time (float) – Delay in seconds between correction iterations.

property quadrupoles: MagnetArray#: Return the quadrupole array used by the correction.

property response_matrix: ResponseMatrixData | None#: Return the loaded tune response matrix, if available.

property tune_monitor: BetatronTuneMonitor#: Return the betatron tune monitor used by the correction.