Element Constraints

An EleObservation contains the output of a tao.ele(...) call (ie Twiss parameters, reference energy, floor positions, etc.). The observation may be evaluted from a single element in a lattice with EleObservable. A reduction (min, max, or avg) of the values over the tracking elements of a lattice can be evaluated using EleReduceObservable, with the reduction selected by its operator field. User-defined values are provided with EleLiteral.

Observation Classes

flowchart TD
    LatticeObservable([LatticeObservable]) --> Observable([Observable])
    LiteralObservable([LiteralObservable]) --> Observable
    EleObservable[EleObservable] --> LatticeObservable
    EleReduceObservable[EleReduceObservable] --> LatticeObservable
    EleLiteral[EleLiteral] --> LiteralObservable
    IsClose([IsClose]) --> Comparison([Comparison])
    IsLess([IsLess]) --> Comparison
    EleIsClose[EleIsClose] --> IsClose
    EleLessThan[EleLessThan] --> IsLess
    EleObservable -. creates .-> EleObservation[EleObservation]
    EleReduceObservable -. creates .-> EleObservation
    EleLiteral -. creates .-> EleObservation
    EleIsClose -. creates .-> ComparisonResult([ComparisonResult])
    EleLessThan -. creates .-> ComparisonResult

pytao.constraints.observables.EleObservation

Bases: Observation

Observation with all of the data available in a Bmad element. Ie, all of the information you get from a pytao tao.ele(...) call.

Attributes:

Name	Type	Description
type	str	Discriminator literal. Always "ele".
element	Element	Element data including Twiss parameters, orbit, floor position, and attributes.

Observables

pytao.constraints.observables.EleObservable

Bases: LatticeObservable[EleObservation]

Observable that fetches element data from the lattice.

Attributes:

Name	Type	Description
type	str	Discriminator literal. Always "ele".
ele_id	str or int	Element index or name passed to tao.ele().
ix_uni	int	Universe index.
ix_branch	int	Branch index.

pytao.constraints.observables.EleReduceObservable

Bases: LatticeObservable[EleObservation]

Observable that performs a reduction across all tracking elements

Attributes:

Name	Type	Description
type	str	Discriminator literal. Always "ele_reduce".
ix_uni	int	Universe index.
ix_branch	int	Branch index.
begin_ele	(str | int | None, optional)	Starting element name or index. None implies first element. By default None.
end_ele	(str | int | None, optional)	Ending element name or index. None implies end element. By default None.

pytao.constraints.observables.ele.ReduceMode

Bases: str, Enum

pytao.constraints.observables.EleLiteral

Bases: LiteralObservable[EleObservation]

Literal element observable with user-specified field values.

Only non-None fields are included in the produced observation.

Attributes:

Name	Type	Description
type	str	Discriminator literal. Always "ele_literal".
beta_a	float or None	Mode A beta function.
alpha_a	float or None	Mode A alpha function.
beta_b	float or None	Mode B beta function.
alpha_b	float or None	Mode B alpha function.
eta_x	float or None	Horizontal dispersion.
etap_x	float or None	Horizontal dispersion slope.
eta_y	float or None	Vertical dispersion.
etap_y	float or None	Vertical dispersion slope.
p0c	float or None	Reference momentum.
floor_x	float or None	Global floor x coordinate.
floor_y	float or None	Global floor y coordinate.
floor_z	float or None	Global floor z coordinate.

Operators

Both operators produce a ComparisonResult whose checks are keyed by the field names listed below.

pytao.constraints.observables.EleIsClose

Bases: IsClose[EleObservation]

IsClose operator comparing two EleObservation instances across all available data.

Set a field to None to skip that comparison.

Attributes:

Name	Type	Description
twiss_a	AnyTwissComparison or None	Comparison method for mode A Twiss parameters.
twiss_b	AnyTwissComparison or None	Comparison method for mode B Twiss parameters.
eta_x	TolComparison or None	Comparison for horizontal dispersion.
etap_x	TolComparison or None	Comparison for horizontal dispersion slope.
eta_y	TolComparison or None	Comparison for vertical dispersion.
etap_y	TolComparison or None	Comparison for vertical dispersion slope.
ref_energy	TolComparison or None	Comparison for total reference energy.
p0c	TolComparison or None	Comparison for reference momentum.
orbit	TolComparison or None	Comparison for orbit, as 6D vector.
floor_x	TolComparison or None	Comparison for global floor x coordinate.
floor_y	TolComparison or None	Comparison for global floor y coordinate.
floor_z	TolComparison or None	Comparison for global floor z coordinate.

pytao.constraints.observables.EleLessThan

Bases: IsLess[EleObservation]

Component-wise less-than comparison between two EleObservations.

Set a field to True to enable the less-than check for that component.

Attributes:

Name	Type	Description
beta_a	bool	Check mode A beta function.
alpha_a	bool	Check mode A alpha function.
beta_b	bool	Check mode B beta function.
alpha_b	bool	Check mode B alpha function.
eta_x	bool	Check horizontal dispersion.
etap_x	bool	Check horizontal dispersion slope.
eta_y	bool	Check vertical dispersion.
etap_y	bool	Check vertical dispersion slope.
ref_energy	bool	Check total reference energy.
p0c	bool	Check reference momentum.
floor_x	bool	Check global floor x coordinate.
floor_y	bool	Check global floor y coordinate.
floor_z	bool	Check global floor z coordinate.

Operator Helper Classes

pytao.constraints.observables.TolComparison

Bases: ConstraintsBase

Scalar or array approximate-equality check using np.allclose.

Attributes:

Name	Type	Description
atol	float	Absolute tolerance.
rtol	float	Relative tolerance.

pytao.constraints.observables.BmagTwissComparison

Bases: TwissComparisonMethod

Twiss comparison using the Bmag metric.

Attributes:

Name	Type	Description
type	str	Discriminator literal. Always "bmag".
max_bmag	float	Upper bound for an acceptable Bmag value.
min_bmag	float	Lower bound for an acceptable Bmag value.

Constraints, and Results

flowchart TD
    ComparisonConstraint([ComparisonConstraint]) --> Constraint([Constraint])
    RegressionConstraint([RegressionConstraint]) --> Constraint
    IsCloseConstraint([IsCloseConstraint]) --> ComparisonConstraint
    IsLessConstraint([IsLessConstraint]) --> ComparisonConstraint
    EleIsCloseConstraint[EleIsCloseConstraint] --> IsCloseConstraint
    EleLessThanConstraint[EleLessThanConstraint] --> IsLessConstraint
    EleRegressionConstraint[EleRegressionConstraint] --> RegressionConstraint
    EleIsCloseConstraint -. creates .-> ComparisonResult([ComparisonResult])
    EleLessThanConstraint -. creates .-> ComparisonResult
    EleRegressionConstraint -. creates .-> ComparisonResult

pytao.constraints.config.EleIsCloseConstraint

Bases: IsCloseConstraint[EleObservables, EleIsClose]

Constraint checking that two element observables are approximately equal.

Attributes:

Name	Type	Description
type	str	Discriminator literal. Always "ele_eq".
obs_a	EleObservables	First element observable.
obs_b	EleObservables	Second element observable.
comparison	EleIsClose	Comparison operator applied to the two observations.

pytao.constraints.config.EleLessThanConstraint

Bases: IsLessConstraint[EleObservables, EleLessThan]

Constraint checking that obs_a is component-wise less than obs_b.

Attributes:

Name	Type	Description
type	str	Discriminator literal. Always "ele_lt".
obs_a	EleObservables	Left-hand side observable.
obs_b	EleObservables	Right-hand side observable.
comparison	EleLessThan	Less-than operator configuration.

pytao.constraints.config.EleRegressionConstraint

Bases: RegressionConstraint[EleIsClose]

Constraint comparing current element observations against a saved reference.

Attributes:

Name	Type	Description
type	str	Discriminator literal. Always "ele_reg".
obs	EleObservables	Element observable to evaluate and compare.
comparison	EleIsClose | str	Comparison operator used to check current against reference.