dutch

Documentation

Overview

Package dutch implements the FIDE Dutch Swiss pairing system (C.04.3).

The Dutch system is the most widely used Swiss pairing system in chess. Players are grouped by score, then paired within brackets using transposition and exchange algorithms subject to 21 quality criteria.

Index

• Variables
• func GenerateTranspositions(s2 []*swisslib.PlayerState, maxCount int) [][]*swisslib.PlayerState
• func MatchBracketFeasible(bracket swisslib.Bracket, ctx *swisslib.CriteriaContext) bool
• func SplitS1S2(players []*swisslib.PlayerState) (s1, s2 []*swisslib.PlayerState)
• func SplitS1S2Heterogeneous(bracket swisslib.Bracket) (s1, s2 []*swisslib.PlayerState)
• type Exchange
  • func GenerateExchanges(s1, s2 []*swisslib.PlayerState) []Exchange
• 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("swiss pairing requires at least 2 active players")

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

Functions

func GenerateTranspositions

func GenerateTranspositions(s2 []*swisslib.PlayerState, maxCount int) [][]*swisslib.PlayerState

GenerateTranspositions generates permutations of s2 in lexicographic order by TPN. Capped at maxCount to handle large brackets.

func MatchBracketFeasible

func MatchBracketFeasible(bracket swisslib.Bracket, ctx *swisslib.CriteriaContext) bool

MatchBracketFeasible checks whether a bracket can produce at least one valid pairing. This is a lightweight version of MatchBracketMulti designed for C8 look-ahead: it uses reduced search limits and only checks absolute criteria (forbidden pairs, C1, C3), returning true as soon as any valid pairing is found.

The reduced limits prevent the combinatorial explosion that occurs when C8 look-ahead runs the full matching algorithm on large merged brackets:

• Transpositions capped at 120 (vs 5040 in full matching)
• Exchanges capped at 50 (vs 500 in full matching)
• No deferred finalization (skips sub-bracket recursion)
• No optimization scoring (just absolute criteria)

func SplitS1S2

func SplitS1S2(players []*swisslib.PlayerState) (s1, s2 []*swisslib.PlayerState)

SplitS1S2 splits a homogeneous bracket into S1 (top half) and S2 (bottom half). For a bracket of n players: S1 = floor(n/2) top-ranked, S2 = remainder. Players must be sorted by TPN ascending.

func SplitS1S2Heterogeneous

func SplitS1S2Heterogeneous(bracket swisslib.Bracket) (s1, s2 []*swisslib.PlayerState)

SplitS1S2Heterogeneous splits a heterogeneous bracket into S1 (downfloaters) and S2 (native players).

Types

type Exchange

type Exchange struct {
	S1 []*swisslib.PlayerState
	S2 []*swisslib.PlayerState
}

Exchange represents a swap of players between S1 and S2.

func GenerateExchanges

func GenerateExchanges(s1, s2 []*swisslib.PlayerState) []Exchange

GenerateExchanges generates all possible exchanges between S1 and S2, ordered by the number of players swapped (fewer swaps first).

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"`
}

Options holds Dutch-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 FIDE Dutch Swiss pairing.

func New

func New(opts Options) *Pairer

New creates a new Dutch pairer with the given options.

func NewFromMap

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

NewFromMap creates a new Dutch 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 FIDE Dutch system (C.04.3).

Algorithm:

1. Build PlayerState for all active players
2. Build score groups (all players enter matching pool)
3. Global Blossom matching (PairBracketsGlobal) — includes Stage 0.5 completability pre-matching for bye determination with odd player count
4. Order boards per FIDE A.6
5. Allocate colors for all paired games
6. Unmatched player (if any) receives PAB
7. Return PairingResult