sequences.steps

Sequence step parsing.

A sequence is a list of raw steps, each either a bare surface index (forward traversal, nominal interaction) or a (index, interaction_override) pair, e.g.:

steps = [0, 1, 2, (3, "reflect"), (2, "reflect"), 3, 4]

The propagation direction (forward/reverse) is not specified explicitly by the user. It starts forward and flips every time a step reflects, since a reflection is what reverses the physical direction of travel. This module turns the raw, ergonomic step list into fully-resolved SequenceStep objects that carry that inferred direction explicitly.

Kramer Harrison, 2026

Functions

parse_steps(raw_steps)

Parse a raw step list into resolved SequenceStep objects.

Classes

SequenceStep(index[, reverse, ...])

A single, fully-resolved step in a surface sequence.

class SequenceStep(index: int, reverse: bool = False, interaction_override: str | None = None)

A single, fully-resolved step in a surface sequence.

Parameters:

• index – Index of the base surface in the optic’s nominal surface list.

• reverse – Whether this step is traversed in the reverse physical direction (light travelling from the base surface’s nominal “post” side toward its “pre” side).

• interaction_override – "reflect" or "refract" to force the interaction type at this step, or None to use the base surface’s nominal interaction.

index: int

interaction_override: str | None = None

reverse: bool = False

parse_steps(raw_steps: list[int | tuple[int, str] | list[Any]]) → list[SequenceStep]

Parse a raw step list into resolved SequenceStep objects.

Direction is inferred: it starts forward (reverse=False) and flips after every step whose resolved interaction is a reflection, since that is the point at which the physical direction of propagation reverses.

Parameters:

raw_steps – The raw sequence, as bare surface indices and/or (index, interaction_override) pairs.

Returns:

The resolved sequence steps, in order.

Raises:

ValueError – If raw_steps is empty or contains an invalid step.