burstein

Documentation

Overview

Package burstein implements the Burstein Swiss pairing system (C.04.4.2).

The Burstein system uses seeding rounds (delegating to Dutch matching) followed by opposition-index-based matching for post-seeding rounds. Seeding rounds = min(floor(totalRounds/2), 4).

Key differences from Dutch:

• Optimization criteria: C10-C13 only (color criteria, no float criteria C14-C21, no C8 look-ahead)
• Bye selection: lowest score → most games played → lowest ranking
• Post-seeding rounds re-rank by opposition index before bracket building
• No topscorer rules (TopScorers map is empty)

Index

• Variables
• func IsSeedingRound(roundNumber, totalRounds int) bool
• func RankByOppositionIndex(players []swisslib.PlayerState, state *chesspairing.TournamentState) []swisslib.PlayerState
• func SeedingRounds(totalRounds int) int
• type OppositionIndex
  • func ComputeOppositionIndex(player *swisslib.PlayerState, state *chesspairing.TournamentState) OppositionIndex
• type Options
  • func ParseOptions(m map[string]any) Options
  • func (o Options) WithDefaults() Options
• type Pairer
  • func New(opts Options) *Pairer
  • func NewFromMap(m map[string]any) *Pairer
  • func (p *Pairer) Pair(_ context.Context, state *chesspairing.TournamentState) (*chesspairing.PairingResult, error)

Variables

var ErrNoPairingPossible = errors.New("no valid pairing exists for the remaining players")

ErrNoPairingPossible is returned when no valid pairing can be found.

var ErrTooFewPlayers = errors.New("burstein pairing requires at least 2 active players")

ErrTooFewPlayers is returned when there aren't enough active players.

Functions

func IsSeedingRound

func IsSeedingRound(roundNumber, totalRounds int) bool

IsSeedingRound returns true if the given round number (1-based) is a seeding round for a tournament with the given total rounds.

func RankByOppositionIndex

func RankByOppositionIndex(players []swisslib.PlayerState, state *chesspairing.TournamentState) []swisslib.PlayerState

RankByOppositionIndex re-ranks players by opposition index and assigns new TPN values. Players are sorted by:

1. Score descending (primary, same as standard ranking)
2. Buchholz descending (higher opposition strength = better)
3. Sonneborn-Berger descending (better results against stronger opponents)
4. Original TPN ascending (tiebreak of last resort)

After sorting, new TPN values are assigned sequentially (1, 2, 3, ...).

func SeedingRounds

func SeedingRounds(totalRounds int) int

SeedingRounds returns the number of seeding rounds for the given total. Seeding rounds = min(floor(totalRounds/2), 4).

Types

type OppositionIndex

type OppositionIndex struct {
	Buchholz        float64 // sum of opponents' scores
	SonnebornBerger float64 // sum of (score vs opponent × opponent's score)
	TPN             int     // tournament pairing number (lower = higher ranked)
}

OppositionIndex holds the three components used to re-rank players after seeding rounds in the Burstein system.

Per C.04.4.2: players are re-ranked by opposition index, which is computed as Buchholz → Sonneborn-Berger → TPN (as final tiebreak).

func ComputeOppositionIndex

func ComputeOppositionIndex(player *swisslib.PlayerState, state *chesspairing.TournamentState) OppositionIndex

ComputeOppositionIndex computes the opposition index for a single player.

Buchholz = sum of opponents' pairing scores (standard 1-½-0). Sonneborn-Berger = sum of (result-against-opponent × opponent's score). TPN = current tournament pairing number (tiebreak of last resort).

type Options

type Options struct {
	// Acceleration selects Baku acceleration mode.
	// Values: "none" (default), "baku".
	Acceleration *string `json:"acceleration,omitempty"`

	// TopSeedColor forces the top seed's color in round 1.
	// Values: "auto" (default), "white", "black".
	TopSeedColor *string `json:"topSeedColor,omitempty"`

	// ForbiddenPairs lists player ID pairs that must not be paired together.
	ForbiddenPairs [][]string `json:"forbiddenPairs,omitempty"`

	// TotalRounds is the planned number of rounds in the tournament.
	// Used to compute seeding round count. If nil, derived from state.
	TotalRounds *int `json:"totalRounds,omitempty"`
}

Options holds Burstein-specific pairing configuration. All fields use pointer-nil pattern: nil = use default.

func ParseOptions

func ParseOptions(m map[string]any) Options

ParseOptions converts a generic map[string]any into typed Options.

func (Options) WithDefaults

func (o Options) WithDefaults() Options

WithDefaults returns a copy of options with defaults applied for nil fields.

type Pairer

type Pairer struct {
	// contains filtered or unexported fields
}

Pairer implements the chesspairing.Pairer interface for the Burstein Swiss system.

func New

func New(opts Options) *Pairer

New creates a new Burstein pairer with the given options.

func NewFromMap

func NewFromMap(m map[string]any) *Pairer

NewFromMap creates a new Burstein pairer from a generic options map.

func (*Pairer) Pair

func (p *Pairer) Pair(_ context.Context, state *chesspairing.TournamentState) (*chesspairing.PairingResult, error)

Pair generates pairings for the next round using the Burstein system (C.04.4.2).

Algorithm:

1. Build PlayerState for all active players
2. Determine if this is a seeding round or post-seeding round
3. Seeding rounds: use TPN-based ranking
4. Post-seeding rounds: re-rank by opposition index
5. Build score groups (all players enter matching pool)
6. Global Blossom matching (PairBracketsGlobal) — includes Stage 0.5 completability pre-matching for bye determination with odd player count
7. AllocateColor with topScorerRules=false; unmatched player receives PAB