roundrobin

Documentation

Overview

Package roundrobin implements round-robin pairing for chess tournaments.

Round-robin pairing ensures every player plays every other player exactly once (single round-robin) or twice with reversed colors (double round-robin).

The algorithm uses the FIDE Berger tables (C.05 Annex 1):

• Fix the last player (or bye dummy for odd counts) at position N-1
• Rotate remaining N-1 players through positions 0..N-2 with stride N/2-1
• Each rotation produces one round of pairings
• For N players (or N+1 if odd, with a dummy "bye" player), there are N-1 rounds per cycle

Color assignment follows FIDE Berger table conventions:

• Board 1 (fixed player vs rotating): alternates starting color per round
• Other boards: the player with the lower position index gets white
• In cycle 2 (double RR), colors are reversed if ColorBalance is true

Index

• 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)

Types

type Options

type Options struct {
	// Cycles is the number of complete round-robins.
	// 1 = single round-robin (each pair plays once).
	// 2 = double round-robin (each pair plays twice, colors reversed).
	// Default: 1.
	Cycles *int `json:"cycles,omitempty"`

	// ColorBalance controls whether colors are swapped in even cycles
	// of a double (or multi-cycle) round-robin.
	// Default: true.
	ColorBalance *bool `json:"colorBalance,omitempty"`

	// SwapLastTwoRounds controls whether the last two rounds of cycle 1
	// are swapped in a double round-robin (Cycles=2), per the FIDE
	// recommendation (C.05 Annex 1) to avoid three consecutive games
	// with the same colour at the cycle boundary.
	// Only applies when Cycles == 2 and roundsPerCycle >= 2.
	// Default: true.
	SwapLastTwoRounds *bool `json:"swapLastTwoRounds,omitempty"`
}

Options holds configurable settings for round-robin pairing. All fields are pointers to distinguish "not set" (nil = use default) from "explicitly set."

func ParseOptions

func ParseOptions(m map[string]any) Options

ParseOptions converts a map[string]any (from Firestore/JSON) into typed Options. Unrecognized keys are ignored.

func (Options) WithDefaults

func (o Options) WithDefaults() Options

WithDefaults returns a copy of Options with all nil fields filled in with system defaults.

type Pairer

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

Pairer implements the chesspairing.Pairer interface for round-robin pairing.

func New

func New(opts Options) *Pairer

New creates a new round-robin pairer with the given options.

func NewFromMap

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

NewFromMap creates a new round-robin pairer from a map[string]any config.

func (*Pairer) Pair

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

Pair generates pairings for the next round using the Berger table method.