Segment-by-Segment

Segment by Segment: Constants

This module provides constants to be used with segment by segment

Segment by Segment: Definitions

This module provides definitions to be used with segment by segment

class omc3.segment_by_segment.definitions.MadXBoundaryConditions(alfx: float = None, alfy: float = None, betx: float = None, bety: float = None, dx: float = None, dy: float = None, dpx: float = None, dpy: float = None, wx: float = None, wy: float = None, dphix: float = None, dphiy: float = None, r11: float = None, r12: float = None, r21: float = None, r22: float = None)

Store all boundary conditions for a Mad-X twiss.

class omc3.segment_by_segment.definitions.Measurement(*args, **kwargs)

Alias for a uncertainties variable.

Additionally has a method to convert it to a tuple and iterate over it.

class omc3.segment_by_segment.definitions.PropagableBoundaryConditions(alpha: Measurement = None, beta: Measurement = None, dispersion: Measurement = None, f1001_amplitude: Measurement = None, f1001_phase: Measurement = None, f1010_amplitude: Measurement = None, f1010_phase: Measurement = None)

Store boundary conditions with error for propagating.

class omc3.segment_by_segment.definitions.PropagableColumns(column: str, plane: str = '{}')

Class to define columns for propagables. One could also implicitly define the error-columns, either via __getattr__ or as a wrapper, but I decided to explicitely name these columns, so that the IDEs can see them and can help in renaming and autocompletion (jdilly 2023).

Segment by Segment: Maths functions

This module provides mathematical helper functions, e.g. to propagate errors.

omc3.segment_by_segment.math.phase_diff(phase_a: ArrayLike, phase_b: ArrayLike) → ArrayLike

Returns the phase difference between phase_a and phase_b, mapped to [-0.5, 0.5].

omc3.segment_by_segment.math.propagate_error_alpha(alpha: ArrayLike, dphi: ArrayLike, init: PropagableBoundaryConditions) → ArrayLike

Propagates the alpha-error from alpha0 to alpha with dphi phaseadvance. See Eq. (4) in [LangnerDevelopmentsSegmentbySegmentTechnique2015] .

Parameters:

• alpha (ArrayLike) -- Alpha function at the observation point(s).

• dphi (ArrayLike) -- Phase advances from the initial position to the observation point(s), in units of 2pi radians.

• init (PropagableBoundaryConditions) -- Initial conditions for alpha and beta and their uncertainties.

omc3.segment_by_segment.math.propagate_error_beta(beta: ArrayLike, dphi: ArrayLike, init: PropagableBoundaryConditions) → ArrayLike

Propagates the beta-error from beta0 to beta with dphi phase-advance. See Eq. (3) in [LangnerDevelopmentsSegmentbySegmentTechnique2015] .

Args:

beta (ArrayLike): Beta function at the observation point(s). dphi (ArrayLike): Phase advances from the initial position to the observation point(s), in units of 2pi radians. init (PropagableBoundaryConditions): Initial conditions at the start of the segment for alpha and beta and their uncertainties.

omc3.segment_by_segment.math.propagate_error_coupling_1001_im(dphix: ArrayLike, dphiy: ArrayLike, init: PropagableBoundaryConditions) → ArrayLike

Propagates the error on the imagary part of f1001 through dphix and dphiy phase-advance, based on the initial amplitude and phase error of f1001. See Eq. (6) in [LangnerDevelopmentsSegmentbySegmentTechnique2015] .

Parameters:

• dphix (ArrayLike) -- Phase advances in x from initial position to observation point(s).

• dphiy (ArrayLike) -- Phase advances in y from initial position to observation point(s).

• init (PropagableBoundaryConditions) -- Initial conditions for f1001 amplitude and phase and their uncertainties.

omc3.segment_by_segment.math.propagate_error_coupling_1001_re(dphix: ArrayLike, dphiy: ArrayLike, init: PropagableBoundaryConditions) → ArrayLike

Propagates the error on the real part of f1001 through dphix and dphiy phase-advance, based on the initial amplitude and phase error of f1001. See Eq. (5) in [LangnerDevelopmentsSegmentbySegmentTechnique2015] .

Parameters:

• dphix (ArrayLike) -- Phase advances in x from initial position to observation point(s).

• dphiy (ArrayLike) -- Phase advances in y from initial position to observation point(s).

• init (PropagableBoundaryConditions) -- Initial conditions for f1001 amplitude and phase and their uncertainties.

omc3.segment_by_segment.math.propagate_error_coupling_1010_im(dphix: ArrayLike, dphiy: ArrayLike, init: PropagableBoundaryConditions) → ArrayLike

Propagates the error on the imaginary part of f1010 through dphix and dphiy phase-advance, based on the initial amplitude and phase error of f1010. See Eq. (7) in [LangnerDevelopmentsSegmentbySegmentTechnique2015] , yet the phases dphix and dphiy are subtracted from the initial rdt phase.

Parameters:

• dphix (ArrayLike) -- Phase advances in x from initial position to observation point(s).

• dphiy (ArrayLike) -- Phase advances in y from initial position to observation point(s).

• init (PropagableBoundaryConditions) -- Initial conditions for f1010 amplitude and phase and their uncertainties.

omc3.segment_by_segment.math.propagate_error_coupling_1010_re(dphix: ArrayLike, dphiy: ArrayLike, init: PropagableBoundaryConditions) → ArrayLike

Propagates the error on the real part of f1010 through dphix and dphiy phase-advance, based on the initial amplitude and phase error of f1010. See Eq. (7) in [LangnerDevelopmentsSegmentbySegmentTechnique2015] , yet the phases dphix and dphiy are subtracted from the initial rdt phase.

Parameters:

• dphix (ArrayLike) -- Phase advances in x from initial position to observation point(s).

• dphiy (ArrayLike) -- Phase advances in y from initial position to observation point(s).

• init (PropagableBoundaryConditions) -- Initial conditions for f1010 amplitude and phase and their uncertainties.

omc3.segment_by_segment.math.propagate_error_dispersion(beta: ArrayLike, dphi: ArrayLike, init: PropagableBoundaryConditions) → ArrayLike

Propagates the dispersion error with dphi phase-advance.

Parameters:

• beta (ArrayLike) -- Beta function at the observation point(s).

• dphi (ArrayLike) -- Phase advances from the initial position to the observation point(s), in units of 2pi radians.

• init (PropagableBoundaryConditions) -- Initial conditions for alpha and beta and the dispersion uncertainty.

omc3.segment_by_segment.math.propagate_error_phase(dphi: ArrayLike, init: PropagableBoundaryConditions) → ArrayLike

Propagates the phase-error. See Eq. (2) in [LangnerDevelopmentsSegmentbySegmentTechnique2015] . This implementation has a minus-sign instead of the first plus-sign as in the reference, this seems to be the correct implementation, as found e.g. in https://github.com/pylhc/MESS/tree/master/FODO_Test_Lattice/Phase_Error_Propagation

Args:

dphi (ArrayLike): Phase advances from the initial position to the observation point(s), in units of 2pi radians. init (PropagableBoundaryConditions): Initial conditions at the start of the segment for alpha and beta and their uncertainties.

Segment by Segment: Propagables

In this module, the propagables, i.e. the parameters that can be propagated through the segment, are defined. Each propagable has a corresponding class, which contains the functions that describe the forward and backward propagation for the respective parameter.

class omc3.segment_by_segment.propagables.AlphaPhase(segment: Segment, meas: OpticsMeasurement)

add_differences(segment_diffs: SegmentDiffs)

This function calculates the differences between the propagated forward and backward models and the measured values. It then adds the results to the segment_diffs class (which writes them out, if its allow_write is set to True).

correction_backward(plane)

Deviations between backward propagated models with and without correction.

correction_forward(plane)

Deviations between forward propagated models with and without correction.

expected_backward(plane)

Interpolation of measured deviations to corrected backward propagated model.

expected_forward(plane)

Interpolation of measured deviations to corrected forward propagated model.

classmethod get_at(names: IndexType, meas: OpticsMeasurement, plane: str) → ValueErrorType

Get corresponding measurement values at the elements names

Parameters:

• names -- element name(s)

• measurement -- Measurement Collection

• plane -- plane to use

Returns:

Series or float containing the required values at names.

init_conditions_dict()

Return a dictionary containing the initial values for this propagable at start and end of the segment.

For the naming, see save_initial_and_final_values macro in omc3/model/madx_macros/general.macros.madx.

measured_backward(plane)

Interpolation of measured deviations to backward propagated model.

measured_forward(plane)

Interpolation of measured deviations to forward propagated model.

class omc3.segment_by_segment.propagables.BetaPhase(segment: Segment, meas: OpticsMeasurement)

add_differences(segment_diffs: SegmentDiffs)

This function calculates the differences between the propagated forward and backward models and the measured values. It then adds the results to the segment_diffs class (which writes them out, if its allow_write is set to True).

correction_backward(plane)

Deviations between backward propagated models with and without correction.

correction_forward(plane)

Deviations between forward propagated models with and without correction.

expected_backward(plane)

Interpolation of measured deviations to corrected backward propagated model.

expected_forward(plane)

Interpolation of measured deviations to corrected forward propagated model.

classmethod get_at(names: IndexType, meas: OpticsMeasurement, plane: str) → ValueErrorType

Get corresponding measurement values at the elements names

Parameters:

• names -- element name(s)

• measurement -- Measurement Collection

• plane -- plane to use

Returns:

Series or float containing the required values at names.

measured_backward(plane)

Interpolation of measured deviations to backward propagated model.

measured_forward(plane)

Interpolation of measured deviations to forward propagated model.

class omc3.segment_by_segment.propagables.Phase(segment: Segment, meas: OpticsMeasurement)

add_differences(segment_diffs: SegmentDiffs)

Calculate the differences between the propagated models and the measured values.

correction_backward(plane)

Deviations between backward propagated models with and without correction.

correction_forward(plane)

Deviations between forward propagated models with and without correction.

expected_backward(plane)

Interpolation of measured deviations to corrected backward propagated model.

expected_forward(plane)

Interpolation of measured deviations to corrected forward propagated model.

classmethod get_at(names: IndexType, meas: OpticsMeasurement, plane: str) → ValueErrorType

Get corresponding measurement values at the elements names

Parameters:

• names -- element name(s)

• measurement -- Measurement Collection

• plane -- plane to use

Returns:

Series or float containing the required values at names.

init_conditions_dict()

Return a dictionary containing the initial values for this propagable at start and end of the segment.

For the naming, see save_initial_and_final_values macro in omc3/model/madx_macros/general.macros.madx.

measured_backward(plane)

Interpolation of measured deviations to backward propagated model.

measured_forward(plane)

Interpolation of measured deviations to forward propagated model.

class omc3.segment_by_segment.propagables.Propagable(segment: Segment, meas: OpticsMeasurement)

abstractmethod add_differences(segment_diffs: SegmentDiffs)

This function calculates the differences between the propagated forward and backward models and the measured values. It then adds the results to the segment_diffs class (which writes them out, if its allow_write is set to True).

abstractmethod correction_backward(plane: str)

Deviations between backward propagated models with and without correction.

abstractmethod correction_forward(plane: str)

Deviations between forward propagated models with and without correction.

abstractmethod expected_backward(plane: str)

Interpolation of measured deviations to corrected backward propagated model.

abstractmethod expected_forward(plane: str)

Interpolation of measured deviations to corrected forward propagated model.

abstractmethod classmethod get_at(names: IndexType, measurement: OpticsMeasurement, plane: str) → ValueErrorType

Get corresponding measurement values at the elements names

Parameters:

• names -- element name(s)

• measurement -- Measurement Collection

• plane -- plane to use

Returns:

Series or float containing the required values at names.

init_conditions_dict()

Return a dictionary containing the initial values for this propagable at start and end of the segment.

For the naming, see save_initial_and_final_values macro in omc3/model/madx_macros/general.macros.madx.

abstractmethod measured_backward(plane: str)

Interpolation of measured deviations to backward propagated model.

abstractmethod measured_forward(plane: str)

Interpolation of measured deviations to forward propagated model.

property segment_models

TfsCollection of the segment models.

omc3.segment_by_segment.propagables.get_all_propagables() → tuple

Return all defined Propagables.

exception omc3.segment_by_segment.segments.SbsDefinitionError

Exception to be raised when the sbs definition is invalid.

class omc3.segment_by_segment.segments.Segment(name: 'str', start: 'str', end: 'str', element: 'str' = None, init_conds: 'str' = None)

classmethod init_from_element_name(element_name: str)

Initialize from the string representation for elements as used in inputs.

classmethod init_from_input(input_str: str)

Initialize from the string representation for segments or elements as used in inputs.

classmethod init_from_segment_definition(segment: str)

Initialize from the string representation for segments as used in inputs.

to_input_string()

String representation of the segment as used in inputs.

class omc3.segment_by_segment.segments.SegmentDiffs(directory: Path, segment_name: str, *args, **kwargs)

TfsCollection of segment-by-segment outputfiles for the differences between propagated model and measurements.

Parameters:

• directory -- The path where to write the files to/find the files.

• segment_name -- Name of the segment corresponding to the model to load.

class omc3.segment_by_segment.segments.SegmentModels(directory: Path, segment: Segment)

Class to hold and load the models of the segments created by MAD-X. The filenames need to be the same as in omc3.model.model_creators.abstract_model_creator.SegmentCreator.

Parameters:

• directory -- The path where to find the models.

• segment -- A segment instance corresponding to the model to load.