pyaml.tuning_tools.orbit#

Orbit measurement and correction tools.

The Orbit tool reads orbit response data, computes corrector changes, and applies horizontal, vertical, and optional RF corrections.

Classes

Orbit(name, bpm_array_name, ...[, ...])

Correct the measured orbit using a configured response matrix.

class pyaml.tuning_tools.orbit.Orbit(name, bpm_array_name, hcorr_array_name, vcorr_array_name, response_matrix, rf_plant_name=None, singular_values=None, singular_values_h=None, singular_values_v=None, virtual_target=0)#

Bases: TuningTool, DynamicValidation

Correct the measured orbit using a configured response matrix.

Parameters:

name (str) – Name of the orbit tool.
bpm_array_name (str) – Name of the BPM array used for orbit readback.
hcorr_array_name (str) – Name of the horizontal corrector array.
vcorr_array_name (str) – Name of the vertical corrector array.
response_matrix (Union[str, OrbitResponseMatrixData]) – Orbit response matrix or path to a serialized matrix. BPM-response entries are in metres per radian; an optional RF response is in metres per hertz.
rf_plant_name (Optional[str]) – Optional RF plant used for RF orbit correction.
singular_values (Optional[int]) – Common number of singular values retained for both planes.
singular_values_h (Optional[int]) – Number of horizontal singular values retained.
singular_values_v (Optional[int]) – Number of vertical singular values retained.
virtual_target (float) – Target sum of horizontal corrector changes, in radians.

Attributes

`response_matrix`	Return the response matrix if it has been loaded None otherwise
`bpms`	Return the BPM array used for orbit readback.
`hcorrectors`	Return the horizontal corrector array used for correction.
`vcorrectors`	Return the vertical corrector array used for correction.
`correctors`	Return the combined horizontal and vertical corrector array.
`rf_plant`	Return the optional RF plant used for correction.

Methods

`load()`	Dynamically loads a response matrix.
`correct()`	Perform orbit correction using the configured response matrix and corrector arrays.
`set_weight()`	Set the weight of a response-matrix input or output.
`set_virtual_weight()`	Set the weight of the virtual orbit target.
`set_rf_weight()`	Set the weight of the RF-frequency correction variable.
`get_weight()`	Return the response-matrix weight for a named input or output.
`get_virtual_weight()`	Return the configured virtual-orbit target weight.
`get_rf_weight()`	Return the configured RF-frequency correction weight.
`post_init()`	Bind orbit corrector and RF handles after attachment.

Configuration

- type: pyaml.tuning_tools.orbit
  name: ORBIT_CORRECTION
  bpm_array_name: BPM
  hcorr_array_name: HORIZONTAL_CORRECTORS
  vcorr_array_name: VERTICAL_CORRECTORS
  rf_plant_name: RF
  singular_values: 16
  response_matrix: path/to/orbit_response.json

correct(plane=None, gain=1.0, gain_h=None, gain_v=None, gain_rf=None, singular_values_h=None, singular_values_v=None, reference=None, rf=False, virtual_target=None)#

Perform orbit correction using the configured response matrix and corrector arrays.

Parameters:

reference (numpy.ndarray, optional) – Optional reference orbit to correct towards. If not specified, corrects to zero orbit. Values are in metres.
gain (float, default 1.0) – Dimensionless global gain applied to all corrector kicks if per-plane gains are not specified.
plane ({'H', 'V'}, optional) – Plane to correct. If ‘H’, only horizontal correction is performed. If ‘V’, only vertical correction is performed. If None (default), both planes are corrected.
gain_h (float, optional) – Dimensionless gain for the horizontal plane. Overrides gain for H-plane if specified.
gain_v (float, optional) – Dimensionless gain for the vertical plane. Overrides gain for V-plane if specified.
gain_rf (float, optional) – Dimensionless gain for the RF-frequency correction. If not specified, the horizontal-plane gain is used.
singular_values_h (int, optional) – Number of singular values to use for SVD decomposition in the horizontal plane. If not specified, uses the default or configured value.
singular_values_v (int, optional) – Number of singular values to use for SVD decomposition in the vertical plane. If not specified, uses the default or configured value.
rf (bool, default False,) – If set to true, the rf_response will also be used in the response matrix for correction of the horizontal orbit. Only takes into effect if plane is None or if plane = ‘H’.
virtual_target (float, optional) – Target sum of horizontal corrector changes, in radians. Defaults to the configured value.

get_rf_weight()#

Return the configured RF-frequency correction weight.

get_virtual_weight()#

Return the configured virtual-orbit target weight.

get_weight(name, plane=None)#

Return the response-matrix weight for a named input or output.

If the name is present in multiple planes, pass plane to select the desired weight.

Parameters:

name (str) – Variable or observable name whose weight should be returned.
plane (Optional[Literal['H', 'V']]) – Optional plane selector, either "H" or "V".

Returns:

float – Configured dimensionless response-matrix weight.

Return type:

float

load(load_path)#

Dynamically loads a response matrix.

Parameters:: load_path (Path) – Filename of the OrbitResponseMatrixData to load

post_init()#: Bind orbit corrector and RF handles after attachment.

set_rf_weight(weight)#

Set the weight of the RF-frequency correction variable.

Parameters:: weight (float) – New dimensionless RF-variable weight used during correction.
Returns:: None – This method does not return a value.
Return type:: None

set_virtual_weight(weight)#

Set the weight of the virtual orbit target.

Parameters:: weight (float) – New dimensionless virtual-target weight used during correction.
Returns:: None – This method does not return a value.
Return type:: None

set_weight(name, weight, plane=None)#

Set the weight of a response-matrix input or output.

Weights affect the relative importance of variables and observables during orbit correction. A plane is required when name occurs in more than one plane.

Parameters:

name (str) – Variable or observable name whose weight should be changed.
weight (float) – New dimensionless weight applied during orbit correction.
plane (Optional[Literal['H', 'V']]) – Optional plane selector, either "H" or "V".

Returns:

None – This method does not return a value.

Return type:

None

property bpms: BPMArray#: Return the BPM array used for orbit readback.

property correctors: MagnetArray#: Return the combined horizontal and vertical corrector array.

property hcorrectors: MagnetArray#: Return the horizontal corrector array used for correction.

property response_matrix: OrbitResponseMatrixData | None#: Return the response matrix if it has been loaded None otherwise

property rf_plant: RFPlant | None#: Return the optional RF plant used for orbit correction.

property vcorrectors: MagnetArray#: Return the vertical corrector array used for correction.