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)

Store all boundary conditions for a Mad-X twiss.

Maths Functions

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

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

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)

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

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

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.