pyaml.tuning_tools.tune_response_matrix#

Betatron-tune response-matrix measurement tools.

The TuneResponseMatrix measures the sensitivity of horizontal and vertical betatron tune to quadrupole-strength changes and stores the fitted responses in a serializable response-matrix data model.

Classes

TuneResponseMatrix(name, quad_array_name, ...)

Measure the response of the betatron tune to quadrupole-strength changes.
class pyaml.tuning_tools.tune_response_matrix.TuneResponseMatrix(name, quad_array_name, betatron_tune_name, quad_delta, n_step=1, sleep_between_step=0, n_avg_meas=1, sleep_between_meas=0)#

Bases: MeasurementTool, DynamicValidation

Measure the response of the betatron tune to quadrupole-strength changes.

The tune response matrix describes the change in horizontal and vertical betatron tune produced by changes in quadrupole strength. Each quadrupole in the configured magnet array is varied over a range of strengths, and the resulting tune values are measured and averaged.

For measurements using more than one strength step, a linear fit is used to determine the tune response to each quadrupole. The resulting matrix has one row for each tune plane and one column for each quadrupole.

After a successful measurement, the result is stored in MeasurementTool.latest_measurement as a ResponseMatrixData representation.

Parameters:

  • name (str) – Name of the measurement tool.

  • quad_array_name (str) – Name of the quadrupole array used for the measurement.

  • betatron_tune_name (str) – Name of the betatron tune monitor used to measure the horizontal and vertical tunes.

  • quad_delta (float) – Maximum positive and negative quadrupole-strength change applied during the measurement, in the configured quadrupole strength unit (typically m^-1).

  • n_step (int, optional) – Number of quadrupole-strength settings used for each quadrupole. The settings are distributed linearly from -quad_delta to quad_delta. The default is 1.

  • sleep_between_step (float, optional) – Time in seconds to wait after changing a quadrupole strength and before measuring the tune. The default is 0.

  • n_avg_meas (int, optional) – Number of tune measurements averaged at each strength setting. The default is 1.

  • sleep_between_meas (float, optional) – Time in seconds to wait between tune measurements used for averaging. The default is 0.

Attributes

quad_array_name

Name of the configured quadrupole array.

betatron_tune_name

Name of the configured betatron tune monitor.

quad_delta

Configured quadrupole-strength change, in the configured quadrupole unit (typically m^-1).

n_step

Configured number of strength settings.

sleep_between_step

Configured delay after each strength change.

n_avg_meas

Configured number of tune measurements to average.

sleep_between_meas

Configured delay between averaged tune measurements.

quadrupoles

Quadrupole array used for the measurement.

tune_monitor

Betatron tune monitor used for the measurement.

Methods

measure()

Measure tune response matrix.

Notes

The generated response matrix has shape (2, n_quadrupoles). The first row contains the horizontal tune response and the second row contains the vertical tune response.

Quadrupole strengths are restored after each individual scan and again when the measurement exits because of an error or interruption.

Configuration

- type: pyaml.tuning_tools.tune_response_matrix
  name: TUNE_RESPONSE_MATRIX
  quad_array_name: QUADRUPOLES
  betatron_tune_name: BETATRON_TUNE
  quad_delta: 1e-4
measure(quad_delta=None, n_step=None, sleep_between_step=None, n_avg_meas=None, sleep_between_meas=None, callback=None)#

Measure tune response matrix.

latest_measurement contains:

matrix:list[list[float] # The response matrix
variable_names:list[str] # Variable names
observable_names:list[str] # Observables names

Example

from pyaml.accelerator import Accelerator
from pyaml.common.constants import Action

def callback(action: Action, data:dict):
    print(f"{action}, data:{data}")
    return True

sr = Accelerator.load("tests/config/EBSTune.yaml")
acc = sr.design

if acc.trm.measure(n_avg_meas=3,sleep_between_meas=5,callback=callback):
    acc.trm.save("ideal_trm.json")
    acc.trm.save("ideal_trm.yaml", with_type="yaml")
    acc.trm.save("ideal_trm.npz", with_type="npz")
Parameters:

  • quad_delta (float) – Quadrupole-strength change in the configured quadrupole unit (typically m^-1).

  • n_step (int, optional) – Number of step for fitting the tune slope [-quad_delta/n_step..quad_delta/n_step] Default from config

  • sleep_between_step (float) – Delay in seconds after quadrupole excitation. Default: from config.

  • n_avg_meas (int, optional) – Default number of tune measurement per step used for averaging Default from config

  • sleep_between_meas (float) – Delay in seconds between two tune measurements. Default: from config.

  • callback (Callable, optional) –

    Callback executed after each strength setting or measurement. See send_callback(). If the callback return false, then the scan is aborted and strength restored. callback_data dict contains:

    source:MeasurementTool # Tool that triggered the callback
idx:int # The index in the element array being processed
step:int # The current step
avg_step:int # The current avg step
magnet:str # The magnet being excited
strength:float # Quadrupole strength, typically in m^-1
tune:np.array # Dimensionless measured tune (on Action.MEASURE)
dtune:np.array # Tune change per quadrupole-strength unit (on Action.RESTORE)

property quadrupoles: MagnetArray#

Return the quadrupole array used for the measurement.

property tune_monitor: BetatronTuneMonitor#

Return the betatron tune monitor used for the measurement.