sequences.resolver#

Sequence resolution and consistency validation.

Turns a list of base surfaces plus raw steps into a validated list of SurfaceView objects. Construction fails loudly (SequenceValidationError) if adjacent steps are not physically consistent, rather than tracing plausible nonsense.

Kramer Harrison, 2026

Functions

resolve_sequence(base_surfaces, raw_steps)

Resolve a raw step list into a validated list of SurfaceView.

validate_sequence(steps, base_surfaces)

Validate that adjacent steps share a consistent medium at their join.

Exceptions

SequenceValidationError

Raised when a sequence's steps are not physically consistent.
exception SequenceValidationError[source]#

Raised when a sequence’s steps are not physically consistent.

resolve_sequence(base_surfaces: list[Surface], raw_steps: list[RawStep]) → list[SurfaceView][source]#

Resolve a raw step list into a validated list of SurfaceView.

Parameters:

  • base_surfaces – The optic’s base surfaces, indexed by the step indices used in raw_steps.

  • raw_steps – The raw sequence, as bare surface indices and/or (index, interaction_override) pairs. See optiland.sequences.steps.parse_steps().

Returns:

The resolved, validated sequence of views, in traversal order.

Raises:

  • ValueError – If raw_steps is empty, malformed, or references an out-of-range surface index.

  • SequenceValidationError – If adjacent steps are not physically consistent.

validate_sequence(steps: list[SequenceStep], base_surfaces: list[Surface]) → None[source]#

Validate that adjacent steps share a consistent medium at their join.

Parameters:

  • steps – The resolved sequence steps.

  • base_surfaces – The optic’s base surfaces, indexed as in steps.

Raises:

SequenceValidationError – If the exit medium of some step does not equal the incident medium of the following step, naming the offending step index.