Segment-by-Segment

Constants

This module provides constants to be used with 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)

Bases: object

Store all boundary conditions for a Mad-X twiss.

alfx: float = None

alfy: float = None

as_dict()

betx: float = None

bety: float = None

dphix: float = None

dphiy: float = None

dpx: float = None

dpy: float = None

dx: float = None

dy: float = None

r11: float = None

r12: float = None

r21: float = None

r22: float = None

wx: float = None

wy: float = None

Maths Functions

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

class omc3.segment_by_segment.math.Measurement(value: float, error: float)

Bases: NamedTuple

Very simple container for a value and its error. Implements only negation and addition with another Measurement.

error: float

Alias for field number 1

value: float

Alias for field number 0

class omc3.segment_by_segment.math.SegmentBoundaryConditions(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)

Bases: object

Store boundary conditions with error as used by the error propagation functions.

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

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: SegmentBoundaryConditions) → 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: SegmentBoundaryConditions) → ArrayLike

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

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 at the start of the segment for alpha and beta and their uncertainties.

omc3.segment_by_segment.math.propagate_error_dispersion(beta: ArrayLike, dphi: ArrayLike, init: SegmentBoundaryConditions) → 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_f1001_amp(dphix: ArrayLike, dphiy: ArrayLike, init: SegmentBoundaryConditions) → ArrayLike

Propagates the error on the amplitude part of f1001 through dphix and dphiy phase-advance.

TODO: Probably do an actual propagation (this just using the inital value)? This was how it was in BBS. (jdilly, 2025)

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_f1001_imag(dphix: ArrayLike, dphiy: ArrayLike, init: SegmentBoundaryConditions) → 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_f1001_phase(dphix: ArrayLike, dphiy: ArrayLike, init: SegmentBoundaryConditions) → Series

Propagates the error on the phase part of f1001 through dphix and dphiy phase-advance.

TODO: Probably do an actual propagation (this just using the inital value)? This was how it was in BBS. (jdilly, 2025)

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_f1001_real(dphix: ArrayLike, dphiy: ArrayLike, init: SegmentBoundaryConditions) → 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_f1010_amp(dphix: ArrayLike, dphiy: ArrayLike, init: SegmentBoundaryConditions) → Series

Propagates the error on the amplitude part of f1001 through dphix and dphiy phase-advance.

TODO: Probably do an actual propagation (this just using the inital value)? This was how it was in BBS. (jdilly, 2025)

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_f1010_imag(dphix: ArrayLike, dphiy: ArrayLike, init: SegmentBoundaryConditions) → 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_f1010_phase(dphix: ArrayLike, dphiy: ArrayLike, init: SegmentBoundaryConditions) → Series

Propagates the error on the phase part of f1001 through dphix and dphiy phase-advance.

TODO: Probably do an actual propagation (this just using the inital value)? This was how it was in BBS. (jdilly, 2025)

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_f1010_real(dphix: ArrayLike, dphiy: ArrayLike, init: SegmentBoundaryConditions) → 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_phase(dphi: ArrayLike, init: SegmentBoundaryConditions) → 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

Parameters:

• 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.quadratic_add(*values)

Calculate the root-sum-squared of the given values. The individual “values” can be pd.Series and then their elements are summed by indices.

Propagables

In the propagables module, 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.

This module exposes the main classes for propagables, to avoid making the imports so long and complicated.

Segments

Classes to hold the information of the segments in the sbs definition.

exception omc3.segment_by_segment.segments.SbsDefinitionError

Bases: Exception

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)

Bases: object

element: str = None

end: str

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.

name: str

start: str

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)

Bases: TfsCollection

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.

PREFIX = 'sbs_'

property alpha_phase_x

property alpha_phase_y

property beta_amp_x

property beta_amp_y

property beta_kmod_x

property beta_kmod_y

property beta_phase_x

property beta_phase_y

property dispersion_x

property dispersion_y

property f1001

property f1010

property momentum_dispersion_x

property momentum_dispersion_y

property norm_dispersion_x

property norm_dispersion_y

property phase_x

property phase_y

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

Bases: TfsCollection

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.

property backward

property backward_corrected

property forward

property forward_corrected