ncaa_eval.evaluation.bracket module

Bracket data structures and construction for NCAA tournament simulation.

Provides the immutable bracket tree used by the simulation engine:

• MatchupContext — context for hypothetical matchup queries.

• BracketNode — node in a tournament bracket tree.

• BracketStructure — immutable tournament bracket.

• build_bracket() — constructs a 64-team tree from TourneySeed.

• _build_subtree() — recursive balanced binary tree builder.

Constants:

• N_ROUNDS — number of rounds in a 64-team bracket (6).

• N_GAMES — total games in a 64-team bracket (63).

class ncaa_eval.evaluation.bracket.BracketNode(round_index: int, team_index: int = -1, left: BracketNode | None = None, right: BracketNode | None = None)

Bases: object

Node in a tournament bracket tree.

A leaf node represents a single team; an internal node represents a game whose winner advances.

round_index

Round number (0-indexed). Leaves have round_index=-1.

Type:

int

team_index

Index into the bracket’s team_ids tuple for leaf nodes. -1 for internal nodes.

Type:

int

left

Left child (None for leaves).

Type:

ncaa_eval.evaluation.bracket.BracketNode | None

right

Right child (None for leaves).

Type:

ncaa_eval.evaluation.bracket.BracketNode | None

property is_leaf: bool

Return True if this is a leaf (team) node.

left: BracketNode | None = None

right: BracketNode | None = None

round_index: int

team_index: int = -1

class ncaa_eval.evaluation.bracket.BracketStructure(root: ~ncaa_eval.evaluation.bracket.BracketNode, team_ids: tuple[int, ...], team_index_map: dict[int, int], seed_map: dict[int, int] = <factory>)

Bases: object

Immutable tournament bracket.

root

Root BracketNode of the bracket tree.

Type:

ncaa_eval.evaluation.bracket.BracketNode

team_ids

Tuple of team IDs in bracket-position order (leaf order).

Type:

tuple[int, …]

team_index_map

Mapping of team_id → index into team_ids.

Type:

dict[int, int]

seed_map

Mapping of team_id → seed_num for seed-aware scoring.

Type:

dict[int, int]

root: BracketNode

seed_map: dict[int, int]

team_ids: tuple[int, ...]

team_index_map: dict[int, int]

class ncaa_eval.evaluation.bracket.MatchupContext(season: int, day_num: int, is_neutral: bool)

Bases: object

Context for a hypothetical matchup probability query.

Passed to ProbabilityProvider so that stateless models can construct the correct feature row for a hypothetical pairing. Stateful models (Elo) typically ignore context and use internal ratings.

season

Tournament season year (e.g. 2024).

Type:

int

day_num

Tournament day number (e.g. 136 for Round of 64).

Type:

int

is_neutral

True for all tournament games (neutral site).

Type:

bool

day_num: int

is_neutral: bool

season: int

ncaa_eval.evaluation.bracket.N_GAMES: int = 63

Total number of games in a 64-team bracket (63).

ncaa_eval.evaluation.bracket.N_ROUNDS: int = 6

Number of rounds in a 64-team single-elimination bracket.

ncaa_eval.evaluation.bracket.build_bracket(seeds: list[TourneySeed], season: int) → BracketStructure

Construct a 64-team bracket tree from tournament seeds.

Play-in teams (is_play_in=True) are excluded. Exactly 64 non-play-in seeds are required.

Parameters:

• seeds – List of TourneySeed objects for the given season.

• season – Season year to filter seeds.

Returns:

Fully constructed BracketStructure.

Raises:

ValueError – If the number of non-play-in seeds for season is not 64.