Machine documentation

`Machine(**calc_options)`

A class used for controling the beamline in Placet.

Uses Python interface to Placet (Placet) and Beamline class for controling the beamline.

Changes the logic of using the Placet for beam tracking. By default, the number of the machines is set to 1. Each Machine instance corresponds to 1 actual beamline. The beamline is described with Beamline object. All the corrections are applied to the current machines with the current offsets by default. Though, one can overwrite that with the typical survey functions, which violates the logic of this class and also has to be used carefully.

Attributes:

Name	Type	Description
`placet`	`Placet`	A `Placet` object, used for communicating with the Placet process running in the background.
`console`	`rich.console.Console`	An object used for the fancy terminal output.
`beamline`	`Optional[Beamline]`	An object storing the beamline info.
`beams_invoked`	`List[Beam]`	An object storing the beams that were created within current `Machine`.
`beamlines_invoked`	`List[str]`	An object storing the names of the beamlines that were created within the current `Machine`.
`callback_struct_`	`tuple(Callable, dict)`	The function that is used as callback for the tracking along with its parameters.
`_data_folder_`	`str`	The name of the folder where the temporary files produced by Placet are stored.

Other Parameters:

Name	Type	Description
`debug_mode`	`bool`	If `True` (default is `False`), runs `self.placet` in debug mode.
`save_logs`	`bool`	If `True` (default is `True`), saves the execution logs by means of invoking `save_debug_info` for `self.placet`.
`send_delay`	`Optional[float]`	The time delay before each data transfer to a Placet process (sometimes needed for stability).
`console_output`	`bool`	If `True` (default is `True`), prints the calculations progress in the console.
`show_intro`	`bool`	If `True` (default is `True`), prints the welcome message of Placet at the start.

`DFS(beam, survey=None, **extra_params)`

Perform the Dispersion Free Steering or DFS.

Before actually invoking the Placet.TestMeasuredCorrection() function, runs Placet.Zero().

If bpms_realign is False - the reference orbit will not be saved. That means, that any further alignment will typically use BPMs center as the best orbit solution (Eg. Rf alignment). When it is True, runs the callback with 'BpmRealign' command. After performing the DFS, sets the callback to "empty".

The default DFS parameters used:

{
        'beam0': beam,
        'beam1': test_beam,
        'cbeam0': test_beam_2,
        'cbeam1': test_beam_3,
        'survey': "from_file",
        'machines': 1,
        'wgt1': 3,
        'bin_iteration': 1000,
        'correct_full_bin': 1,
        'binlength': 36,
        'binoverlap': 18,
        'bpm_res': 0.1,
        'emitt_file': "temp/emitt.dat",

        'timeout': 1000,
        'errors_file': alignment_file
}

Parameters:

Name	Type	Description	Default
`beam`	`Beam`	The beam to use.	required
`survey`	`Optional[str]`	The type of survey to be used. So far the accepted options are: `[None, "None", "Zero", "Clic", "Nlc", "Atl", "AtlZero", "Atl2", "AtlZero2, "Earth"]` If survey is `None` (default) - uses the current beamline alignment from `self.beamline`. The rest value are Placet built-in surveys. After it is used, the alignment in `self.beamline` is going to be updated with new values generated by a survey.	`None`

Other Parameters:

Name	Type	Description
`bpms_realign`	`bool`	If `True` (default is `True`), updates the reference orbit (bpm reading) by invoking a new callback procedure with `BpmRealign` in it.

Other arguments accepted are inherited from Placet.TestMeasuredCorrection(), except of machines, survey, and beam.

Returns:

Type	Description
`DataFrame`	The tracking summary. The comlumns of the resulting DataFrame: `['correction', 'beam', 'beamline', 'survey', 'positions_file', 'emittx', 'emitty']`

`RF_align(beam, survey=None, **extra_params)`

Perform the accelerating structures alignment (RF alignment).

Does the correction with Placet.TestRfAlignment(). After, runs Machine.track() to evaluate the emittances.

Parameters:

Name	Type	Description	Default
`beam`	`Beam`	The beam to use.	required
`survey`	`Optional[str]`	The type of survey to be used. So far the accepted options are: `[None, "None", "Zero", "Clic", "Nlc", "Atl", "AtlZero", "Atl2", "AtlZero2, "Earth"]` If survey is `None` (default) - uses the current beamline alignment from `self.beamline`. The rest value are Placet built-in surveys. After it is used, the alignment in `self.beamline` is going to be updated with new values generated by a survey.	`None`

Other arguments accepted are inherited from Placet.TestRfAlignment(), except of machines, survey, and beam.

Returns:

Type	Description
`DataFrame`	The tracking summary The comlumns of the resulting DataFrame: `['correction', 'errors_seed', 'beam_seed', 'survey', 'positions_file', 'emittx', 'emitty']`

`apply_cavs_errors(phase_error=0.0, grad_error=0.0)`

Add the errors to the cavities' phases and gradients.

Parameters:

Name	Type	Description	Default
`phase_error`	`float`	Standard deviation of the phase (Absolue value).	`0.0`
`grad_error`	`float`	Standard deviation of the gradient (Absolue value).	`0.0`

`apply_knob(knob, amplitude, strategy, **extra_params)`

Apply the knob and update the beamline offsets.

It is generaly safer to use this function instead of individual Knob.apply(). Here, the checks are performed to ensure that all the elements involved in knob exist in self.beamline.

Parameters:

Name	Type	Description	Default
`knob`	`Knob`	The knob to use.	required
`amplitude`	`float`	Amplitude to apply.	required
`strategy`	`str`	Strategy to use for calculations of the offsets when the knob has `step_size` defined. Default is 'simple_memory'.	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_quads_errors(strength_error=0.0)`

Add the relative strength errors to all the Quadrupoles in self.beamline.

Parameters:

Name	Type	Description	Default
`strength_error`	`float`	Standard relative deviation of the quadrupole strength.	`0.0`

`assign_errors(survey=None, **extra_params)`

Assign the alignment errors to the beamline currently used (beamline attribute). Uses provided survey along with the static errors given as keyword arguments. The survey acts as an instruction on how to misalign the lattice.

There are several options to misalign the beamline using different built-int misalignment surveys (accessed through Machine.misalignment_surveys):

["default_clic", "from_file", "empty", "misalign_element", "misalign_elements", 
"misalign_girder", "misalign_girders"]

These surveys are implemented as Python functions and can be called outside of the score of this function.

"default_clic" corresponds to the function Machine.default_clic() and applies the misalignments according to Placet.Clic() survey.
"from_file" corresponds to the function Machine.from_file() and applies the misalignments from the file.
"empty" corresponds to the function Machine.empty() and does not apply any misalignments.
"misalign_element" corresponds to the function Machine.misalign_element() and misaligns one element in the beamline.
"misalign_elements" corresponds to the function Machine.misalign_element() and misaligns multiple element in the beamline.
"misalign_girder" corresponds to the function Machine.misalign_girder() and misaligns one girder in the beamline.
"misalign_girders" corresponds to the function Machine.misalign_girders() and misaligns multiple girders in the beamline.

Parameters:

Name	Type	Description	Default
`survey`	`Optional[str]`	If survey is `None`, by default applying 'empty' survey.	`None`

Other Parameters:

Name	Type	Description
`static_errors`	`dict`	The dict containing the static errors of the lattice. This data is used when invoking `Machine.survey_errors_set()` Is required when using `"default_clic"` survey. All the possible settings are: `['quadrupole_x', 'quadrupole_y', 'quadrupole_xp', 'quadrupole_yp', 'quadrupole_roll', 'cavity_x', 'cavity_realign_x', 'cavity_y', 'cavity_realign_y', 'cavity_xp', 'cavity_yp', 'cavity_dipole_x', 'cavity_dipole_y', 'piece_x', 'piece_xp', 'piece_y', 'piece_yp', 'bpm_x', 'bpm_y', 'bpm_xp', 'bpm_yp', 'bpm_roll', 'sbend_x', 'sbend_y', 'sbend_xp', 'sbend_yp', 'sbend_roll']`
`errors_seed`	`int`	The seed for errors sequence. If not defined, the random number is used.
`filename`	`str`	When `"from_file"` survey is used, the `filename` is used to read the misalignments, otherwise ignored.

Other keyword arguments accepted are the parameters of the Placet.InterGirderMove().

`cavities_setup(**extra_params)`

Set the main cavities parameters.

It is required for the beam creation. Beams in Placet use the results from the command

% calc wake.dat

to have the values for the transverse (longitudinal?) wakes.

The calc function from the file "wake_calc.tcl" uses the functions from "clic_beam.tcl". These functions utilize the global variable structure'. Thus, until these functions are substituted with Python alternatives, one has to call this function every time one sets the beamline. Moreover the macroparticles' weights are takendirectly from the file "wake.dat".

One has to provide all the other parameters. Having zeros as default could lead to unexpected behaviour.

The variables a, g, l, delta, and delta_g are going to be declared in Placet in the form of structure by using Placet.set_list().

Other Parameters:

Name	Type	Description
`a`	`float`	to check
`g`	`float`	to check
`l`	`float`	to check
`delta`	`float`	to check
`delta_g`	`float`	to check
`phase`	`float`	Cavities phase. Default is `0.0`.
`frac_lambda`	`float`	to check. Default is `0.0`.
`scale`	`float`	to check. Default is `1.0`.

`create_beamline(lattice, **extra_params)`

Create the beamline in Placet from the input lattice file.

The beamline attribute of Machine is going to be overwritten.

Parameters:

Name	Type	Description	Default
`lattice`	`str`	The name of the file containing the lattice.	required

Other Parameters:

Name	Type	Description
`name`	`str`	The name of the beamline (By default is set to `"default"`).
`callback`	`bool`	If `True`(default is `True`) creates the callback procedure in Placet by invoking `set_callback()`.
`cavities_setup`	`dict`	The dictionary containing the parameters for `cavities_setup()`.
`parser`	`str`	The type of parser to be used to read the file into a `Beamline` object. The possible options are described in `Beamline`
`parser_variables`	`dict`	The dict with the variables and their values that parser is going to use to parse the file. Can only be used with `"advanced"` parcer of `Beamline`.
`debug_mode`	`bool`	If `True` (default is `False`), prints the information during the parsing processes.
`parse_for_placet`	`bool`	[Only if `"advanced"` parser is used]. If `True` (default is `False`), feeds the parsed version of the lattice saved with [`Beamline.to_placet()`] function. Otherwise, feeds the original file given in lattice.

Returns:

Type	Description
`Beamline`	The created beamline.

`default_clic(**extra_params)`

Apply the default Clic survey to a lattice.

The function calls Clic func in Placet. It requires the lattice misalignments to be already declared with either with Machine.survey_errors_set() (preferred) or with self.placet.SurveyErrorSet().

Can be used inside of a proc in Placet.

Other Parameters:

Name	Type	Description
`additional_lineskip`	`int`	Can only take the value of '0' (default). If not given, the default values for the commands are used

Other keyword arguments accepted are parameters of the self.placet.InterGirderMove() function, which is invoked within default_clic.

`empty(**extra_params)`

Apply the empty survey function.

Corresponds to using 'None' survey in Placet.

Can be used inside of a proc in Placet.

`eval_obs(beam, observables, **extra_params)`

Evaluate the requested observables for the current state of self.beamline.

The observalbles could be the following:

For particle beam:
```
['E', 'x', 'y', 'z', 'px', 'py']
```

For macroparticle beam:

['s', 'weight', 'E', 'x', 'px', 'y', 'py', 'sigma_xx', 'sigma_xpx', 
'sigma_pxpx', 'sigma_yy', 'sigma_ypy', 'sigma_pypy', 'sigma_xy', 
'sigma_xpy', 'sigma_yx', 'sigma_ypx']

Also, emittance ['emittx', 'emitty'] is evaluted in each case.

The units for the coordinates are: - E: GeV - s(z), x, y, z: micrometer - px, py: microrad, - emittx, emitty: nm

Parameters:

Name	Type	Description	Default
`beam`	`Beam`	The beam to use.	required
`observables`	`Union[str, List[str]]`	The variables to read from the tracking data when performing the scan. It can consist of: `['s', 'weight', 'E', 'x', 'px', 'y', 'py', 'sigma_xx', 'sigma_xpx', 'sigma_pxpx', 'sigma_yy', 'sigma_ypy', 'sigma_pypy', 'sigma_xy', 'sigma_xpy', 'sigma_yx', 'sigma_ypx', 'emittx', 'emitty']` When more than 1 observable is needed, they should be passed as a list.	required

Other Parameters:

Name	Type	Description
`suppress_output`	`bool`	If `True` (default is `False`) suppresses the log message in regards of the tracking.

Returns:

Type	Description
`List[float]`	The values of the observables.

`eval_orbit(beam)`

Evaluate the beam orbit based on the BPM readings.

Parameters:

Name	Type	Description	Default
`beam`	`Beam`	The beam to use.	required

Returns:

Type	Description
`DataFrame`	The orbit along the beamline.

`eval_track_results(beam, **extra_params)`

Evaluate the beam parameters at the beamline exit.

At the beginning of the run, if the calculation requires performing the tracking, sets the callback. Depending on the beam type, the different callback is defined. For sliced beam it is Machine.save_sliced_beam(). For particle beam it is Machine.save_beam().

The structure of the data in the files for the sliced beam:

1. s long position along [um]
2. weight
3. energy [GeV]
4. x [um]
5. x' [um/m]
6. y [um]
7. y' [um/m]
8. sigma_xx
9. sigma_xx'
10. sigma_x'x'
11. sigma_yy
12. sigma_yy'
13. sigma_y'y'
14. sigma_xy (always 0)
15. 0
16. 0
17. 0

The structure of the data in the files for the particle beam:

1. energy [GeV]
2. x [um]
3. y [um]
4. z [um]
5. x' [urad]
6. y' [urad]

Parameters:

Name	Type	Description	Default
`beam`	`Beam`	The beam to use.	required

Other Parameters:

Name	Type	Description
`keep_callback`	`bool`	If `True` (default is `False`), does not change the callback function at the end of the run.

Returns:

Type Description

tuple(DataFrame, float, float)

Returns the DataFrame with the particles' coordinates at the beamline exit and final horizontal and vertical emittance.

The columns of the DataFrame includes are:

For sliced beam:

['s', 'weight', 'E', 'x', 'px', 'y', 'py', 'sigma_xx', 'sigma_xpx', 
'sigma_pxpx', 'sigma_yy', 'sigma_ypy', 'sigma_pypy', 'sigma_xy', 
'sigma_xpy', 'sigma_yx', 'sigma_ypx']

For particle beam:
```
['E', 'x', 'y', 'z', 'px', 'py']
```

`eval_twiss(beam, **extra_params)`

Evaluate the Twiss parameters along the lattice.

The method uses Placet.TwissPlotStep() function to evaluate the Twiss.

(?) Apparently, it evaluates the twiss for error-free Lattice, or alternatively, for the current misalignments in the lattice.

Parameters:

Name	Type	Description	Default
`beam`	`Beam`	The beam to use.	required

Other Parameters:

Name	Type	Description
`step`	`float`	Step size to be taken for the calculation. If less than 0 the parameters will be plotted only in the centres of the quadrupoles.
`start`	`int`	(?) First particle for twiss computation.
`end`	`int`	(?) Last particle for twiss computation
`list`	`List[int]`	Save the twiss parameters only at the selected elements.
`file_read_only`	`str`	When the parameter is given, the function just reads the Twiss from this file and does not generate it.
`beamline`	`str`	The beamline to be used in the calculations.

Returns:

Type	Description
`DataFrame`	Returns a Pandas Dataframe with the Twiss data. The table contains the following columns: `["id", "type", "s", "betx", "bety", 'alfx', 'alfy', 'Dx', 'Dy', 'E']`

`from_file(**extra_params)`

Apply the survey that uses the misalignments from the file.

Other Parameters:

Name	Type	Description
`file`	`str`	The name of the file with the misalignments.
`additional_lineskip`	`int`	Can only take the value of `0`. If not given, the default values for the commands are used.

`import_beamline(lattice, **extra_params)`

Import the existing Beamline object as a beamline into Placet.

Parameters:

Name	Type	Description	Default
`lattice`	`Beamline`	The Beamline to import.	required

Other Parameters:

Name	Type	Description
`callback`	`bool`	If `True`(default is `True`) creates the callback procedure in Placet by invoking `set_callback()`. !!Should be handled carefully! Some functions expect 'callback' procedure to exist. Eg. `eval_track_results()` evaluates the macroparticles coordinates. To do so, 'callback' procedure is required.
`cavities_setup`	`dict`	A dictionary containing the parameters for `cavities_setup()`.

`iterate_knob(beam, knob, observables, knob_range=[-1.0, 0.0, 1.0], **extra_params)`

Iterate the given knob in the given range and get the iteration summary.

Saves the knob's state at the beginning of the iteration and restores it at the end.

Parameters:

Name	Type	Description	Default
`beam`	`Beam`	The name of the beam to be used.	required
`knob`	`Knob`	The knob to perform scan on.	required
`observables`	`Union[str, List[str]]`	The variables to read from the tracking data when performing the scan. It can consist of any combination of: `['s', 'weight', 'E', 'x', 'px', 'y', 'py', 'sigma_xx', 'sigma_xpx', 'sigma_pxpx', 'sigma_yy', 'sigma_ypy', 'sigma_pypy', 'sigma_xy', 'sigma_xpy', 'sigma_yx', 'sigma_ypx', 'emittx', 'emitty']` When more than 1 observable is needed, they should be passed as a list.	required
`knob_range`	`List[float]`	The list of the knob values to perform the scan.	`[-1.0, 0.0, 1.0]`

Other Parameters:

Name	Type	Description
`iteration_type`	`str`	The type of the knob iteration scan to perform. The possible options are `["natural", "with_cache"]` When it is "with_cache" (default), after each value from `knob_range` is applied the knob is reset to the initial state. When it is "natural", the elements' offsets associated with a `knob` are not reset. Since `Knob.apply()` is additive function, an amplitude difference between the previous and current is applied.
`knob_apply_strategy`	`str`	Strategy to use for calculations of the offsets when knob has `step_size` defined. Default is 'simple_memory'. Possible options are: `["simple", "simple_memory", "min_scale", "min_scale_memory"]`
`fit`	`Callable`	Function to fit the data. !! Only works if the amound of observables is equaly 1.
`plot`	`Callable`	Function to plot the iteration data. !! Only works if the amound of observables is equaly 1.
`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']`

Returns:

Type Description

dict

The scan summary. The structure of the dictionary looks like this:

{
'scan_log': 
{
'knob_range': knob_range, 
'obs_data': observable_values
}, 
'fitted_value': ..,
'best_obs': ..
}

obs_data follows the same format as the input variable observables. The data stored there follows the shape:

[[obs1_value1, obs2_value1, ..], [obs1_value2, obs2_value2, ..]]

fitted_value is the best value estimated from the fit (if the fit function is given) and only 1 observable best_obs is the fitted function.

`make_beam_many(beam_name, n_slice, n, **extra_params)`

Generate the particle beam.

Wraps Beam.make_beam_many(). Similar to make_beam_many from "make_beam.tcl" in Placet but rewritten in Python.

Practically could pass the whole beam_setup to the function. Keep the same structure as in Placet. Optional parameters (if not given, checks self.beam_parameters. If self.beam_parameters does not have them throws an Exception)

Parameters:

Name	Type	Description	Default
`beam_name`	`str`	Name of the beam.	required
`n_slice`	`int`	Number of the slices.	required
`n`	`int`	Number of the particles per slice.	required

Other Parameters:

Name	Type	Description
`sigma_z`	`float`	[Required] Bunch length in micrometers.
`charge`	`float`	[Required] Bunch charge.
`beta_x`	`float`	[Required] Horizontal beta-function.
`beta_y`	`float`	[Required] Vertical beta-function.
`alpha_x`	`float`	[Required] Horizontal alpha-function.
`alpha_y`	`float`	[Required] Vertical alpha-function.
`emitt_x`	`float`	[Required] Horizontal normalized emittance.
`emitt_y`	`float`	[Required] Vertical normalized emittance.
`e_spread`	`float`	[Required] Energy spread.
`e_initial`	`float`	[Required] Initial energy.
`n_total`	`int`	[Required] Total number of the particles.

Returns:

Type	Description
`str`	The beam name.

`make_beam_slice_energy_gradient(beam_name, n_slice, n_macroparticles, eng, grad, beam_seed=None, **extra_params)`

Generate the macroparticle (sliced) beam.

Wraps Beam.make_beam_slice_energy_gradient(). Similar to make_beam_slice_energy_gradientfrom "make_beam.tcl" in Placet but rewritten in Python.

Parameters:

Name	Type	Description	Default
`beam_name`	`str`	Name of the beam.	required
`n_slice`	`int`	Number of the slices.	required
`n_macroparticles`	`int`	Number of the macroparticles per slice.	required
`eng`	`float`	Initial energy offset.	required
`grad`	`float`	Accelerating gradient offset.	required
`beam_seed`	`Optional[int]`	The seed number of the random number distribution. If not given a random number in the range [1, 1000000] is taken.	`None`

Other Parameters:

Name	Type	Description
`sigma_z`	`float`	[Required] Bunch length in micrometers.
`charge`	`float`	[Required] Bunch charge.
`beta_x`	`float`	[Required] Horizontal beta-function.
`beta_y`	`float`	[Required] Vertical beta-function.
`alpha_x`	`float`	[Required] Horizontal alpha-function.
`alpha_y`	`float`	[Required] Vertical alpha-function.
`emitt_x`	`float`	[Required] Horizontal normalized emittance.
`emitt_y`	`float`	[Required] Vertical normalized emittance.
`e_spread`	`float`	[Required] Energy spread.
`e_initial`	`float`	[Required] Initial energy.
`n_total`	`int`	[Required] Total number of the particles.

Returns:

Type	Description
`str`	The beam name.

`misalign_articulation_point(**extra_params)`

Offset the articulation point either between 2 girders or at the beamline start/end.

The girders and elements on them are misalligned accordingly (wrt the geometry of the girder).

There is an option to provide the ids of the girders to the right and to the left of the articulation point. That require girder_right - girder_left to be equal 1, otherwise an exception will be raised.

It is possible to provide only 1 id either of the right or the left one. This also works for the start/end of the beamline.

Other Parameters:

Name	Type	Description
`girder_left`	`Optional[int]`	The ID of the girder to the left of the articulation point.
`girder_right`	`Optional[int]`	The ID of the girder to the right of the articulation point.
`x`	`float`	The horizontal offset in micrometers. Default is `0.0`.
`y`	`float`	The vertical offset in micrometers. Default is `0.0`.
`filter_types`	`Optional[List[str]]`	The types of elements to apply the misalignments to. By default, the misalignments are applied to all the elements on the girder.

`misalign_element(**extra_params)`

Apply the geometrical misalignments to the element with the given ID.

Duplicates Beamline.misalign_element().

Other Parameters:

Name	Type	Description
`element_index`	`int`	The id of the element in the lattice. Required
`x`	`float`	The horizontal offset in micrometers. Default is `0.0`.
`xp`	`float`	The horizontal angle in micrometers/m. Default is `0.0`.
`y`	`float`	The vertical offset in micrometers. Default is `0.0`.
`yp`	`float`	The vertical angle in micrometers/m. Default is `0.0`.
`roll`	`float`	The roll angle in microrad. Default is `0.0`.

`misalign_elements(**extra_params)`

Apply the geometrical misalignments to the elements in the dictionary

Other Parameters:

Name	Type	Description
`offsets_data`	`dict`	[Required] The dictionary with the elements offsets in the following format: `{ 'element_id1': { 'x': .. 'y': .. .. } 'element_id2': { .. } .. }`

`misalign_girder(**extra_params)`

Offset the girder transversaly together with the elements on it.

All the elements on the girder are equally misaligned.

Other Parameters:

Name	Type	Description
`girder`	`int`	The girder ID.
`filter_types`	`Optional[List(str)]`	The types of elements to apply the misalignments to. By default, the misalignments are applied to all the elements on the girder.
`x`	`float`	The horizontal offset in micrometers.
`y`	`float`	The vertical offset in micrometers.

`misalign_girder_general(**extra_params)`

Misalign the girder by means of moving its end points.

Other Parameters:

Name	Type	Description
`girder`	`int`	[Required] The id of the girder.
`x_right`	`float`	The horizontal offset in micrometers of right end-point. Default is `0.0`.
`y_right`	`float`	The vertical offset in micrometers of the right end-point. Default is `0.0`.
`x_left`	`float`	The horizontal offset in micrometers of left end-point. Default is `0.0`.
`y_left`	`float`	The vertical offset in micrometers of the left end-point. Default is `0.0`.
`filter_types`	`Optional[List[str]]`	The types of elements to apply the misalignments to. By default, the misalignments are applied to all the elements on the girder.

`misalign_girders(**extra_params)`

Misalign the girders according to the dictionary.

Other Parameters:

Name	Type	Description
`offsets_data`	`dict`	The dictionary with the girders offsets in the following format: `{ 'girder_id1': { 'x': .. 'y': .. .. } 'girder_id2':{ .. } .. }`
`filter_types`	`Optional[List[str]]`	The types of elements to apply the misalignments to. By default, the misalignments are applied to all the elements on the girder.

`one_2_one(beam, survey=None, **extra_params)`

Perform the one-to-one (1-2-1) alignment.

It is a wrapped version of Placet.TestSimpleCorrection().

Parameters:

Name	Type	Description	Default
`beam`	`Beam`	The beam to use.	required
`survey`	`Optional[str]`	The type of survey to be used. So far the accepted options are: `[None, "None", "Zero", "Clic", "Nlc", "Atl", "AtlZero", "Atl2", "AtlZero2, "Earth"]` If survey is `None` (default) - uses the current beamline alignment from `self.beamline`. The rest value are Placet built-in surveys. After it is used, the alignment in `self.beamline` is going to be updated with new values generated by a survey.	`None`

Other arguments accepted are inherited from Placet.TestSimpleCorrection(), except of machines, survey, and beam.

Returns:

Type	Description
`DataFrame`	The tracking summary after the correction. The columns of the resulting DataFrame: `['correction', 'beam', 'beamline', 'survey', 'positions_file', 'emittx', 'emitty']`

`phase_advance(start_id, end_id)`

Get the phase advance

Does not work atm.

Parameters:

Name	Type	Description	Default
`start_id`	`int`	Element index of the first element	required
`end_id`	`int`	Element index of the last element	required

`random_reset(seed=None)`

Reset the random seed in Placet.

Runs Placet.RandomReset().

`save_beam(**extra_params)`

Save the particle beam.

Can be used inside of a proc in Placet.

Other keyword arguments accepted are parameters of the self.placet.BeamDump() function, which is invoked within save_beam.

`save_sliced_beam(**extra_params)`

Save the sliced beam.

Other keyword arguments accepted are parameters of the self.placet.BeamSaveAll() function, which is invoked within save_sliced_beam.

`scan_knob(beam, knob, observable, knob_range, fit_func, **extra_params)`

Scan the given knob in the given range, apply the fit function and set the knob value to the optimum.

Since, the optimal value is set only in self.beamline, in case one needs to update these values in Placet immediatly, one has to call Machine._update_lattice_misalignments()

Parameters:

Name	Type	Description	Default
`beam`	`Beam`	The beam used for the scan.	required
`knob`	`Knob`	The knob to perform scan on.	required
`knob_range`	`List[float]`	The list of the knob values to perform the scan.	required
`observable`	`str`	The variables to read from the tracking data and use it for identifying the optimum in the scan. It can be one of: `['s', 'weight', 'E', 'x', 'px', 'y', 'py', 'sigma_xx', 'sigma_xpx', 'sigma_pxpx', 'sigma_yy', 'sigma_ypy', 'sigma_pypy', 'sigma_xy', 'sigma_xpy', 'sigma_yx', 'sigma_ypx', 'emittx', 'emitty']`	required
`fit_func`	`Callable`	The fit function for the data.	required

Other Parameters:

Name	Type	Description
`plot`	`Callable[[List[float], List[float]], None]`	The function to plot the knob iteration of the format f(x, y).
`evaluate_optimal`	`bool`	If `True` (default is `True`) reevaluates the emittance by running `track()` function.
`iteration_type`	`str`	The type of the knob iteration scan to perform. The possible options are `["natural", "with_cache"]` When it is "with_cache" (default), after each value from `knob_range` is applied the knob is reset to the initial state. When it is "natural", the elements' offsets associated with a `knob` are not reset. Since `Knob.apply()` is additive function, an amplitude difference between the previous and current is applied.
`knob_apply_strategy`	`str`	Strategy to use for calculations of the offsets when knob has `step_size` defined. Default is 'simple_memory'. Possible options are: `["simple", "simple_memory", "min_scale", "min_scale_memory"]`
`minimization`	`bool`	If `True` (default) the goal of the function is the minimization of the provided `observable`. If `False` - maximization of `observable`. This is needed to evaluate the best value of `observable` in case the fitted value is not smallest/largest.
`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']`

Returns:

Type	Description
`DataFrame`	The scan summary. The columns of the output table are: `['correction', 'positions_file', 'emittx', 'emitty', 'knob_value', 'scan_log']`

`set_callback(func, **extra_params)`

Set the callback function for the tracking.

By default, when a Beamline is created within Machine, a callback procedure is declared with TclCall. This procedure is going to be called every time the beam tracking through the beamline is performed. The name of this procedure is set to 'callback'. After the beamline creation the name of the function cannot be changed, but the actual procedure can be overwritten in Placet. And this is what this function does.

It is primaraly used for saving the macroparticle and particle beams' distributions. Normally, one does not have to call it, but use the other function that set it automatically.

Parameters:

Name	Type	Description	Default
`func`	`Callable`	Function for the callback.	required

Other parameters could be any keyword argument that the input func accepts.

`survey_errors_set(**extra_params)`

Set the default errors for the Placet surveys.

Overwrites the Placet.SurveyErrorSet() and sets the values not provided by the user to zero by default. Original Placet.SurveyErrorSet() only overwrites the values provided by the user, not touching the rest.

Other parameters are the same as for Placet.SurveyErrorSet(). The full list:

['quadrupole_x', 'quadrupole_y', 'quadrupole_xp', 'quadrupole_yp', 'quadrupole_roll', 
'cavity_x', 'cavity_realign_x', 'cavity_y', 'cavity_realign_y', 'cavity_xp', 
'cavity_yp', 'cavity_dipole_x', 'cavity_dipole_y', 'piece_x', 'piece_xp', 'piece_y', 
'piece_yp', 'bpm_x', 'bpm_y', 'bpm_xp', 'bpm_yp', 'bpm_roll', 'sbend_x', 'sbend_y', 
'sbend_xp', 'sbend_yp', 'sbend_roll']

Refer to Placet.SurveyErrorSet() for more details.

`track(beam, survey=None)`

Perform the tracking without applying any corrections.

It is a wrapped version of Placet.TestNoCorrection(). When survey parameter is not provided (Recommended), the current misalignments in self.beamline are used. This is important, because Placet.TestNoCorrection() does not offer such capabilities. It can only misalign the lattice according to some guidelines and ignores the misalignmenst prior to calling.

Machine.track() on the other hand relies on the data stored in self.beamline. So, to overcome the limitation of Placet.TestNoCorrection() the default survey is set to "from_file" and the file used is the one produced for the current state of self.beamline.

[!!] Be aware that Placet internally does not generate random numbers, but rather takes pseudo random numbers from the sequence, uniquely defined by a seed value. So, if you run your Machine program with a Placet built-in surveys there is alway a chance you are going to get the same offsets sequence. To make sure that misalignments are different one has to run Placet.RandomReset before the tracking with surveys. In Machine.assign_errors() for example, this is invoked by default (set to a random value) if the error_seed parameter is not declared.

Parameters:

Name	Type	Description	Default
`beam`	`Beam`	The beam to use.	required
`survey`	`Optional[str]`	The type of survey to be used. So far the accepted options are: `[None, "None", "Zero", "Clic", "Nlc", "Atl", "AtlZero", "Atl2", "AtlZero2, "Earth"]` If survey is `None` (default) - uses the current beamline alignment from `self.beamline`. The rest value are Placet built-in surveys. After it is used, the alignment in `self.beamline` is going to be updated with new values generated by a survey.	`None`

Returns:

Type	Description
`DataFrame`	The tracking summary. The columns of the resulting DataFrame: `['correction', 'beam', 'beamline', 'survey', 'positions_file', 'emittx', 'emitty']`