Elo-MMR-Py

Fast Python bindings for Elo-MMR, a multiplayer rating method designed for contests with many participants. The rating calculation runs in Rust and releases Python's GIL, while the public API uses ordinary Python objects and precise type information.

The exact mmr algorithm is the default. The approximate mmr-fast variant remains an explicit choice.

Installation

python -m pip install Elo-MMR-Py

Binary ABI3 wheels support standard CPython 3.11 and newer on Linux x86_64 and aarch64, macOS x86_64 and arm64, and Windows x86_64. PyPy, free-threaded CPython, and 32-bit platforms do not have prebuilt wheels.

Quickstart

Use rate_latest() for leaderboards and services. It creates one immutable PlayerRating per participant instead of one Python object per historical event.

from elo_mmr_py import Contest, rate_latest

contests = [
    Contest(
        standings=[('Ada', 0, 0), ('Grace', 1, 1), ('Linus', 2, 2)],
        name='Example final',
        time_seconds=1_700_000_000,
    )
]

leaderboard = sorted(rate_latest(contests).values(), key=lambda player: -player.rating)
for player in leaderboard:
    print(player.name, player.rating, player.rating_sig, player.contests_played)

Use rate() when you need every historical rating event:

from elo_mmr_py import rate

players = rate(contests)  # system='mmr' is the exact default
ada_history = players['Ada'].events

Long-running services can retain state with Rater, and advanced Elo-MMR users can pass an immutable EloMmrConfig. Their canonical interfaces and executable example are in the API documentation.

Standings and ties

A standing is (name, low_rank, high_rank). Ranks are zero-based and inclusive. An ordinary result has low_rank == high_rank; tied participants repeat the same interval. See Contest representation for a tie example and the complete ordering rules.

Rating systems

mmr is the recommended exact default. mmr-fast is an explicit approximation whose benefit depends on the workload. See Rating systems for every supported mode and its constraints.

Checkpoints

Both APIs accept str | os.PathLike[str] checkpoint paths and can atomically save or resume rating state. The checkpoint guide is the canonical reference for the schema, migration, compatibility, file permissions, symlinks, and failure behavior.

Documentation and development

The complete guide covers concepts, API details, checkpoints, performance, errors, development, and releasing. Source setup and all required checks live in the development guide; see CONTRIBUTING.md for contribution policy.