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. The min and max of the values in the element can be evaluated using EleMinObservable and EleMaxObservable.

Observation Classes

flowchart TD
    LatticeObservable([LatticeObservable]) --> Observable([Observable])
    LiteralObservable([LiteralObservable]) --> Observable
    EleObservable[EleObservable] --> LatticeObservable
    EleMaxObservable[EleMaxObservable] --> LatticeObservable
    EleMinObservable[EleMinObservable] --> LatticeObservable
    EleLiteral[EleLiteral] --> LiteralObservable
    IsClose([IsClose]) --> Comparison([Comparison])
    IsLess([IsLess]) --> Comparison
    EleIsClose[EleIsClose] --> IsClose
    EleLessThan[EleLessThan] --> IsLess
    EleObservable -. creates .-> EleObservation[EleObservation]
    EleMaxObservable -. creates .-> EleObservation
    EleMinObservable -. creates .-> EleObservation
    EleLiteral -. creates .-> EleObservation
    EleIsClose -. creates .-> EleIsCloseResult[EleIsCloseResult]
    EleLessThan -. creates .-> EleLessThanResult[EleLessThanResult]

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
`obs_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
`obs_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.EleMinObservable

Bases: LatticeObservable[EleObservation]

Observable yielding the per-field minimum across all tracking elements.

Attributes:

Name	Type	Description
`obs_type`	`str`	Discriminator literal. Always `"ele_min"`.
`ix_uni`	`int`	Universe index.
`ix_branch`	`int`	Branch index.

pytao.constraints.observables.EleMaxObservable

Bases: LatticeObservable[EleObservation]

Observable yielding the per-field maximum across all tracking elements.

Attributes:

Name	Type	Description
`obs_type`	`str`	Discriminator literal. Always `"ele_max"`.
`ix_uni`	`int`	Universe index.
`ix_branch`	`int`	Branch index.

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
`obs_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 and Results

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.EleLessThanResult

Bases: IsLessResult

Result of an EleLessThan comparison with per-field less-than check results.

Each field is None if the corresponding component was not checked.

Attributes:

Name	Type	Description
`result_type`	`str`	Discriminator literal. Always `"ele_is_less"`.
`beta_a`	`CheckResult or None`	Mode A beta function.
`alpha_a`	`CheckResult or None`	Mode A alpha function.
`beta_b`	`CheckResult or None`	Mode B beta function.
`alpha_b`	`CheckResult or None`	Mode B alpha function.
`eta_x`	`CheckResult or None`	Horizontal dispersion.
`etap_x`	`CheckResult or None`	Horizontal dispersion slope.
`eta_y`	`CheckResult or None`	Vertical dispersion.
`etap_y`	`CheckResult or None`	Vertical dispersion slope.
`ref_energy`	`CheckResult or None`	Total reference energy.
`p0c`	`CheckResult or None`	Reference momentum.
`floor_x`	`CheckResult or None`	Global floor x coordinate.
`floor_y`	`CheckResult or None`	Global floor y coordinate.
`floor_z`	`CheckResult or None`	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.

pytao.constraints.observables.EleIsCloseResult

Bases: IsCloseResult

Result of an EleIsClose comparison with per-field check results.

Each field is None if the corresponding comparison was not run.

Attributes:

Name	Type	Description
`result_type`	`str`	Discriminator literal. Always `"ele_is_close"`.
`twiss_a`	`CheckResult or None`	Mode A Twiss comparison (beta_a, alpha_a).
`twiss_b`	`CheckResult or None`	Mode B Twiss comparison (beta_b, alpha_b).
`eta_x`	`CheckResult or None`	Horizontal dispersion.
`etap_x`	`CheckResult or None`	Horizontal dispersion slope.
`eta_y`	`CheckResult or None`	Vertical dispersion.
`etap_y`	`CheckResult or None`	Vertical dispersion slope.
`ref_energy`	`CheckResult or None`	Total reference energy (e_tot).
`p0c`	`CheckResult or None`	Reference momentum.
`orbit`	`CheckResult or None`	Orbit, as 6D vector.
`floor_x`	`CheckResult or None`	Global floor x coordinate.
`floor_y`	`CheckResult or None`	Global floor y coordinate.
`floor_z`	`CheckResult or None`	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 .-> EleIsCloseResult[EleIsCloseResult]
    EleLessThanConstraint -. creates .-> EleLessThanResult[EleLessThanResult]
    EleRegressionConstraint -. creates .-> EleIsCloseResult

pytao.constraints.config.EleIsCloseConstraint

Bases: IsCloseConstraint

Constraint checking that two element observables are approximately equal.

Attributes:

Name	Type	Description
`constraint_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

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

Attributes:

Name	Type	Description
`constraint_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

Constraint comparing current element observations against a saved reference.

Attributes:

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