knob documentation

`Knob(elements, knob_structure, **extra_params)`

A class used to create a Knob.

A knob is a certain change in the beamline (elements offsets, strengths change, etc.) that is applied to modify change conditions like beam waist, dispersion or something more complex.

So far the elements' types accepted for the knobs creation are Quadrupole and Cavity.

The Knob is going to store the references of the Elements provided and use them to apply the changes. Thus changes to the elements here are going to change the originals.

If parameter `step_size'' is provided, the coordinates modifications when using [apply_knob'][placetmachine.lattice.knob.Knob.apply_knob] are adjusted towards the closest number full of steps.

Attributes:

Name	Type	Description
`elements`	`List[Element]`	List of the elements that used in this Knob.
`variables`	`List[dict]`	A list containing dictionaries that describe the changes that are performed to the elements when `Knob` is applied. Number of elements in the list should be the same as the number of the elements. It contains the info on the amplitude for each coordinate to change for the given `Element` as well as the total accumulated changes, mismatches and step sizes. An example of the dict that describes that `Element` must be moved vertically by 5.0 micron and horizontaly by -2.0 micron: `{ 'y': { 'amplitude': 5.0, 'change': 0.0, 'step_size': 0.5, 'mismatch': 0.0 } 'x': { 'amplitude': -2.0, 'change': 0.0 'step_size': 0.5, 'mismatch': 0.0 } }` Both vertical and horizontal movers are anticipated to have a step size of 0.5 micron in this example. Also, for each coordinate a mismatch and total accumnulated coordinate changes are kept.
`supported_amplitudes`	`Optional[List[float]]`	A list of the supported amplitudes. When provided, only the amplitudes from the list are applied. This list contains the amplitudes that an attribute `amplitude` can take. That means that amplitude given in `Knob.apply()` is adjusted so that the sum `Knob.amplitude + amplitude` eqists in `supported_amplitudes`. Since, strategies, like `min_scale` and `min_scale_memory` have their own amplitude selection, attribute `supported_amplitudes` has no effect on them.
`amplitude_mismatch`	`float`	A mismatch between the amplitude requested and the amplitude applied. By default is `0.0`. It is modified when the `apply()` strategy foresees the automatic adjustment of the amplitude. So `amplitude_mismatch` accomodates this mismatch between multiple `apply()` calls.
`name`	`str`	Name of the Knob.
`types_of_elements`	`List[str]`	Types of the elements involved in the Knob.
`amplitude`	`float`	The current Knob amplitude.

Parameters:

Name	Type	Description	Default
`elements`	`List[Element]`	List of elements to be used for this `Knob`. Elements provided here must be the elements that are the part of the Beamline.	required
`knobs_structure`		A list containing info about the elements' amplitudes and step sizes. An example of such a list for a knob containing 2 elements: `[{'y':{'amplitude': 2.0, 'step_size': 0.5}}, {'x': {'amplitude': 2.5}, 'y': {'amplitude': -0.5}}]` Here, the first element has an amplitude `2.0` for the coordinate `y`, while the second element requires a combination of `x` and `y` changes of `2.5` and `-0.5` respectively.	required

Other Parameters:

Name	Type	Description
`name`	`str`	The name of the knob. If not provided, defaults to "".
`supported_amplitudes`	`Optional[List[float]]`	A list of the supported amplitudes.

`__apply_min_scale(amplitude)`

Apply the the knob.

The offsets are evaluated the following way: 1. The minimum offset is evalued among all the elements. For instance, lets take the smallest offset amplitude is 1.0 $\mu$m, step size of 0.5 $\mu$m, and the knob amplitude of 0.6. The rounded smallest offsets is goint to be 0.5. 2. We take the smallest rounded offset and evaluate the offsets of the other elements by scalling the offset amplitudes correspondingly. These offsets are also rounded to the closest value proportional to the step size.

As a result of such adjustemnt - amplitude applied may differ from the amplitude passed.

Parameters:

Name	Type	Description	Default
`amplitude`	`float`	Amplitude of the knob to apply.	required

`__apply_min_scale_memory(amplitude, **extra_params)`

Apply the the knob.

The offsets are evaluated the following way: 1. The minimum offset is evalued among all the elements. For instance, lets take the smallest offset amplitude is 1.0 $\mu$m, step size of 0.5 $\mu$m, and the knob amplitude of 0.6. The rounded smallest offsets is goint to be 0.5. 2. We take the smallest rounded offset and evaluate the offsets of the other elements by scalling the offset amplitudes correspondingly. These offsets are also rounded to the closest value proportional to the step size.

As a result of such adjustment - amplitude applied may differ from the amplitude passed.

When evaluating the offsets, the mismatch between the current values and values expected by the amplitude are added. Also, the amplitude mismatch (difference between the amplitude provided to the function Knob.amplitude) is taken into accound.

Parameters:

Name	Type	Description	Default
`amplitude`	`float`	Amplitude of the knob to apply.	required

Other Parameters:

Name	Type	Description
`use_global_mismatch`	`bool`	If `True` (default) coordinates' changes are evaluated to also compensate the possible mismatches caused by other knobs.

`__apply_simple_memory(amplitude, **extra_params)`

Apply the the knob.

The offsets to apply are evaluated by rounding the offsets' amplitude taking into account also the the accumulated mismatch. It also takes into account the present amplitude mismatch Knob.amplitude_mismatch.

If supported_amplitudes is provided, it takes the closest value such that amplitude + Knob.amplitude exist in the knob.supported_amplitudes and applies it. The difference between the applied and requested amplitudes is added to amplitude_mismatch attribute.

Parameters:

Name	Type	Description	Default
`amplitude`	`float`	Amplitude of the knob to apply.	required

Other Parameters:

Name	Type	Description
`ignore_supported_amplitudes`	`bool`	If `True` (default is `False`) ignores the `supported_amplitudes` attribute even if present.
`use_global_mismatch`	`bool`	If `True` (default) coordinates' changes are evaluated to also compensate the possible mismatches caused by other knobs.

`__appply_simple(amplitude, **extra_params)`

Apply the the knob.

The offsets to apply are evaluated by rounding the offsets' amplitude. Is prone to accumulating the missmatches of the knobs offsets.

If supported_amplitudes is provided, it takes the closest value such that amplitude + Knob.amplitude exist in the Knob.supported_amplitudes and applies it. The difference between the applied and requested amplitudes is added to amplitude_mismatch attribute.

Parameters:

Name	Type	Description	Default
`amplitude`	`float`	Amplitude of the knob to apply.	required

Other Parameters:

Name	Type	Description
`ignore_supported_amplitudes`	`bool`	If `True` (default is `False`) ignores the `supported_amplitudes` attribute even if present.

`__evaluate_sensitive_coordinate()`

Evaluate the most sensitive coordinate and element by checking the relation between their absolute amplitudes and step sizes. The smaller value is - the more sensitive the element/coordinate is.

Returns:

Type	Description
`The id of the element and the coordinate of the most sensitive point. If no such found`
(eg. no step sizes defined) returns `None, None`.

`apply(amplitude, **kwargs)`

Apply the knob.

Amplitude defines the fraction of the amplitudes of each individual coordinates to add to the elementss involved in the Knob. If step_size is not defined (default), coordinate change is applied directly. If step_size is defined, the actual coordinate change may be different from anticipated. This difference may also depend on the strategy used.

Parameters:

Name	Type	Description	Default
`amplitude`	`float`	Amplitude of the knob to apply.	required

Other Parameters:

Name	Type	Description
`strategy`	`str`	Strategy to use for calculations of the offsets when the `step_size` is defined. Default is `None`. Possible options are: `[None, 'simple', 'simple_memory', 'min_scale', 'min_scale_memory']` If strategy is `None` all of the step sizes are ignored.
`use_global_mismatch`	`bool`	If `True` (default) coordinates' changes are evaluated to also compensate the possible mismatches caused by other knobs. Only applicable to the strategies that memorize the mismatches, such as: `['simple_memory', 'min_scale_memory']`

`cache_state()`

Save the current knobs' state into the cache.

It saves the changes applied by the knob so it could be restored later. Attributes to be cached:

[`amplitude`, `amplitude_mismatch`, `changes`, `mismatch`]

`reset()`

Reset the knob's data.

It resets the knob to 0.0 amplitude. That means the elements' offsets changes done by the knob are removed. Consequently resets the following attributes: amplitude, mismatch, and changes.

`to_dataframe()`

Return the DataFrame with the Knob data.

The data included in the DataFrame is:

['name', 'type', 'girder', 's']

which is a name, type, girder id, and location of the element belonging to the girder. Plus the coordinate amplitude, current value in the beamline, coordinate change performed by the knob, and the mismatch when there is a finit step size:

['y_amplitude', 'y_current']

Typically, the properties, like girder or s are acquired during the Beamline creation. When the knob is created on the isolated element, these properties are set to None.

Returns:

Type	Description
`DataFrame`	Knob data summary

`upload_state_from_cache(clear_cache=False)`

Upload the knob's data from the cache.

Attributes to be upload:

[`amplitude`, `amplitude_mismatch`, `changes`, `mismatch`]

As these values are uploaded - elements' offsets are adjusted correspondingly.

Parameters:

Name	Type	Description	Default
`clear_cache`	`bool`	If `True` clears the cached data.	`False`