rstt package

Subpackages

Submodules

rstt.config module

Configuration module for rstt simulation default behaviours.

This module contains ‘global’ variables used as default values in functions and classes across the rstt package. It offers a simple approach to tune behaviour of simulations once instead of passing identical parameters multiple times in different function calls.

Warning

The module is a work in progress with limited test. Bugs are expected.

Example

1from rstt import Player
2import rstt.config as cfg
3
4
5cfg.PLAYER_DIST_ARGS['mu'] = 2000
6cfg.PLAYER_DIST_ARGS['sigma'] = 50
7
8# create players with an average level of approximatively 2000 and a standard deviation of 50.
9players = Player.create(nb=10)
rstt.config.DUEL_HISTORY = False

Default behaviour of the rstt.game.match.Duel when param ‘tracking’ is None. If set to True, the Duel instance will ‘try’ to add the match to its participants game history.

rstt.config.EVENTSTANDING_DEFAULT_POINTS = {}

Default points dictionary of rstt.ranking.inferer.EventStanding when param ‘default’ is None.

The empty dictionary means that if you instanciate an EventStanding without providing a value for ‘the default’ parameter and later call the rstt.ranking.inferer.add_event() without providing a value for the ‘points’ parameter, you may aswell just not passan ‘event’ value. Or even not call the method at all as the corresponding added event will be ignored by the inferer.

rstt.config.GAUSSIAN_PLAYER_MEAN_ARGS = {'mu': 1500, 'sigma': 500}

Default args for mean level generator used by rstt.player.gaussian.GaussianPlayer when param ‘mu’ is None

rstt.config.GAUSSIAN_PLAYER_MEAN_DIST(mu, sigma)

Default mean level generator used by rstt.player.gaussian.GaussianPlayer when param ‘mu’ is None

rstt.config.GAUSSIAN_PLAYER_MEAN_MEAN = 1500

Deafault mu of GAUSSIAN_PLAYER_MEAN_ARGS

rstt.config.GAUSSIAN_PLAYER_MEAN_SIGMA = 500

Deafault sigmaof GAUSSIAN_PLAYER_MEAN_ARGS

rstt.config.GAUSSIAN_PLAYER_SIGMA_ARGS = {'mu': 100, 'sigma': 50}

Default args for level deviation generator used by rstt.player.gaussian.GaussianPlayer when param ‘sigma’ is None

rstt.config.GAUSSIAN_PLAYER_SIGMA_DIST(mu, sigma)

Default level standard deviation generator used by rstt.player.gaussian.GaussianPlayer when param ‘sigma’ is None

rstt.config.GAUSSIAN_PLAYER_SIGMA_MEAN = 100

Deafault mu of GAUSSIAN_PLAYER_SIGMA_ARGS

rstt.config.GAUSSIAN_PLAYER_SIGMA_SIGMA = 50

Deafault sigma of GAUSSIAN_PLAYER_SIGMA_ARGS

rstt.config.LOGSOLVER_BASE = 10

Default base of rstt.solver.solvers.LogSolver when param ‘base’ is None

rstt.config.LOGSOLVER_LC = 400

Default logistic constant of rstt.solver.solvers.LogSolver when param ‘lc’ is None

rstt.config.MATCH_HISTORY = False

Default behaviour of the rstt.game.match.Match when param ‘tracking’ is None. If set to True, the Match instance will ‘try’ to add the match to its participants game history.

rstt.config.PLAYER_DIST(mu, sigma)

Default level generator used by rstt.player.basicplayer.BasicPlayer.create() when param ‘level_dist’ is None

rstt.config.PLAYER_DIST_ARGS = {'mu': 1500, 'sigma': 500}

Default args for level generator used by rstt.player.basicplayer.BasicPlayer.create() when param ‘level_params’ is None

rstt.config.PLAYER_GAUSSIAN_MU = 1500

Deafault mu of PLAYER_DIST_ARGS

rstt.config.PLAYER_GAUSSIAN_SIGMA = 500

Deafault sigma of PLAYER_DIST_ARGS

rstt.stypes module

Typing in RSTT

This modules defines different componnents types for the package. RSTT user level functions and class methods are typehecked. It helps raising meaningfull errors at runtime, write understandable functions. The module purpose is also to help develloper to extent and integrate their own component that fit in the RSTT framework.

When a type name clashes with an existing class, the type name is prefixed by a capital S. For example: rstt.stypes.SPlayer should only be used for typehint in functions signatures. rstt.player.player.Player is a class representing competitors.

Note

RSTT relies on typeguard 3.0.0 and Duck-Typing for function signatures. Which means that Protocol are defined by the existence of attributes/methods, and not their type signatures.

class rstt.stypes.Achievement(event_name: str, place: int, prize: float)[source]

Bases: object

DataClass indicating player’s result in event.

Achievements are object generated by rstt.scheduler.tournament.competition.Competition. It is collected by rstt.player.palyer.Player to track their history in events.

Note

Since achievements are automaticaly stored by Player, there is no field indicating the ‘who’

event_name: str

The name of the event

place: int

The place of the player in the final standing of the event

prize: float

The earnings of the player during the event

class rstt.stypes.Evaluator(*args, **kwargs)[source]

Bases: Protocol

eval(options: list[list[SPlayer]], initial_seeds: Iterable, results: Any, **kwargs) → list[list[SPlayer]][source]

reorder options based on criteria

The options can be evaluated based on an history of Game(s), or Player(s) appreciation. Usually the eval function does some ‘sorting’ operations

Parameters

optionsList[List[Player]]

Different ordering of players possibility to evaluate

initial_seedsIterable

An apriori ‘preference’ on the player.

resultsAny

A collection of results indicating palyer’s performaces so far.

Returns

List[List[Player]]

A reordered version of the parameter ‘options’.

class rstt.stypes.Event(*args, **kwargs)[source]

Bases: Protocol

Event interface

Runtime_checkable Protocol for competitive events.

Events are automated game generators. Typical events are tournament inheriting from the rstt.scheduler.competition.Competition class. Examples are rstt.scheduler.tournament.knockout.SingleEliminationBracket and rstt.scheduler.tournament.groups.RoundRobin

games(by_rounds: bool) → list[SMatch] | list[list[SMatch]][source]

getter for SMatch

Parameters

by_roundsbool

a boolean value indicating if the return should be a List[Smatch] (false), or a List[List[SMatch]]

Returns

Union[List[SMatch], List[List[SMatch]]]

All SMatch played during the event.

name() → str[source]

getter for the name event

Name are assumed to be unique identifier

Returns

str

The name of the event

participants() → list[SPlayer][source]

getter for the involved competitiors

Returns

list[SPlayer]

A list of SPlayer taking part in the compeittion, i.e. playing games.

standing() → dict[SPlayer, int][source]

getter for the event standing

A standing represent the result of the event (and not a given SMatch). The place 1 indicates the winner of the event.

Returns

Dict[SPlayer, int]

A dictionary indicating the final placement of all SPlayer that participated in the Event.

class rstt.stypes.Generator(*args, **kwargs)[source]

Bases: Protocol

generate(status: list[int] | list[SPlayer]) → list[list[int]] | list[list[SPlayer]][source]

Generate different ordering version of a given List

the different version produced are refered as ‘options’ For short input, this function could just produce all possible orderings. For long inout, this function could implement greedy strategy. Thus the input is a list, and the initial ordering is meaningfull for the strategy

Parameters

statusUnion[List[int], List[Player]]

A list of element to compute options

Returns

Union[list[list[int]], list[list[SPlayer]]]

the options, A list of different ‘option’ which are reordering of the given ‘status’ Idealy the first option is a direct, and ‘obvious’ transformation of status

class rstt.stypes.Inference(*args, **kwargs)[source]

Bases: Protocol

Inference Interface

Runtime_checkable Protocol responsible to estimate the level of SPlayer. Inference is a core component of rstt.ranking.ranking.Ranking. Examples are rstt.ranking.inferer.Elo or rstt.ranking.inferer.EventStanding.

rate(*args, **kwargs) → Any[source]

A method to rate Splayer based on ‘observation’

Different Inference can have different parameters and returns values/types. There is no general patterns that can be extracted. However, the existence of this method has the benefit to sementicly fit other famous package in the field of ranking system in competition, such as Openskill and TrueSkill.

Note

For devellopers: The type-signature of the rate method is a ‘contract’ with the other components of a Ranking instance, namely a rstt.stypes.Observer instance. For example if the ranking uses a rstt.ranking.observer.GameByGame Observer, then the inferer.rate() method should accept a List[Rating] and either a Score or a List[int] as parameters. The GameByGame expect a List[Rating] as return value. The type of Rating has to be compatible with the rstt.stypes.RatingSystem of the Ranking.

Parameters:

Any

The input of the rate method is usually some sort of prior ‘Rating’ or collection of ‘Rating’ and an indication of why/how the ratings should change.

Returns

Any

The return of the rate method is usually a sort of updated ‘Rating’ or collection of ‘Rating’.

class rstt.stypes.Observer(*args, **kwargs)[source]

Bases: Protocol

Obersever Interface

Runtime_checkable Protocol implementing a workfow triggered by rstt.ranking.ranking.Ranking.update(). The observer component of a ranking is responsible to update ratings of SPlayer based on ‘observation’ passed to the update() function. Examples are rstt.ranking.observer.GameByGame and rstt.ranking.observer.BatchGame.

It is possible to entirely change the behaviour of Ranking by simply changing the observer component. Indeed both the Elo and Glicko rating systems can be used either with the GameByGame or BatchGame observer. Yet, for identical input, the resulting updated can be different.

Note

‘Observation’ is an abstract arbitrary notion, it does not even need to be something passed as a parameters to a rstt.ranking.ranking.Ranking.update() method. For example the rstt.ranking.standard.BTRanking rank players based on the returned value of their level() method, which could change silently during a simulation. In this case the ranking.update() method is called without parameters.

handle_observations(infer: Inference, datamodel: RatingSystem, *args, **kwargs) → None[source]

method that triggers a rating update routine

The method uses a RatingSystem to get prior rating of Player and store updated ratings. It uses an Inference instance to compute the updated ratings, usually from the prior ratings and some additional parameters

Parameters

inferInference

An inference object responsible to update ratings

datamodelRatingSystem

A ratingSystem object storing rating compatible with the passed infer.

class rstt.stypes.RatingSystem(*args, **kwargs)[source]

Bases: Protocol

RatingSystem interface

Runtime_checkable Protocol acting as a sort of Dict[SPlayer, Rating] where Rating can be of Any type. RatingSystem are componnent of rstt.ranking.ranking.Ranking and provde an ‘ordinal()’ method used by the ranking to sort automatically players (assign a rank).

An example is the rstt.ranking.datamodel.KeyModel that acts as a defaultdictionary, ensuring that any SPlayer has at least a default rating such that it can be ranked in a Ranking.

get(key: SPlayer) → Any[source]

getter method for rating

Parameters

keySPlayer

A key to get the corresponding value (rating)

Returns

Any

A corresponding value, meant has the player’s rating

keys()[source]

Dict like keys method

Returns

view object

view on the RatingSystem entries

ordinal(rating: Any) → float[source]

Convert a value to a float

This methods is used to compare keys to each others based on their associated values.

Parameters

ratingAny

A rating to convert

Returns

float

A single floating value. rstt.ranking.ranking.Ranking assumes that a higher returned value means ‘better’.

set(key: SPlayer, rating: Any) → None[source]

setter method for rating

Allows a user to tune the rating of a SPlayer at will

Parameters

keySPlayer

A key for which the associated value should change

ratingAny

The new value associated to the provided key

class rstt.stypes.SMatch(*args, **kwargs)[source]

Bases: Protocol

Match interface

Runtime_checkable Protocol representing a confrontation between rstt.stypes.SPlayer. Examples of SMatch can be found in the rstt.game.match module.

players() → list[SPlayer][source]

getter for match participants

Returns

List[SPlayer]

The list of SPlayer who participates in the match. The order of players matches the order of float value in the rstt.stypes.SMatch.scores()

scores() → list[float][source]

getter for the match score

Returns

Score

The outcome of the match. The order of players returned by rstt.stypes.SMatch.players() matches the order of float value in the returned Score.

class rstt.stypes.SPlayer(*args, **kwargs)[source]

Bases: Protocol

Player interface

Runtime_checkable Protocol representating the notion of a participant in a rstt.stypes.SMatch and an element in a rstt.ranking.ranking.Ranking. Examples of SPlayer are implemented in the subpackage rstt.player

level() → float[source]

return the level (or strenght, skills) of the splayer

name() → str[source]

return the name of the competitors. Assumed to be a unique identifier

rstt.stypes.Score

Outcome of match

A list of float value, each representing the result of a corresponding participant in the Match.

class rstt.stypes.Seeder(*args, **kwargs)[source]

Bases: Protocol

seed(players: list[SPlayer], initial_seeds: Iterable, results: Any, **kwargs) → list[SPlayer][source]

Reorder players in a ‘meaningfull’ fashion

Parameters

playersList[Player]

A list of Player to order

initial_seedsIterable

An original ordering of the players

resultsAny

Any data structure containing games (type ´Game´) related to the involved players

Returns

List[Player]

A list of the same players, in a different order

class rstt.stypes.Shuffler(*args, **kwargs)[source]

Bases: Protocol

rearange(status: list[int]) → list[int][source]

Reorder elements in a ‘meaningfull’ fashion

Parameters

statusList[int]

A list of integers [e0, e1, e2, …]

Returns

List[int]

A list of the same integers, in a different order.

class rstt.stypes.Solver(*args, **kwargs)[source]

Bases: Protocol

Solver interface

Runtime_checkable Protocol responsible of SMatch outcome generation. For a rstt.game.match.Duel. An example is a deterministic Solver where the player with the highest level wins the duel rstt.solver.solvers.BetterWin

solve(match: SMatch, *agrs, **kwargs) → None[source]

Method that decide an SMatch outcome.

This method has three responsabilities.

  • First it should generate a suitable game result (Score).

  • Assign the result to the game

  • add the game to the history of the game participants that tracks their games.

Note

An SMatch can only be assigned an outcome once, but the Solver does not need to take any precaution in that regards. It is the responsability of the Smatch. The same can be said about player tracking their game history, a match can only be added once, but it is the player responsability to enforce it.

Parameters

matchSMatch

A game to generate an outcome for.

Module contents

class rstt.BTRanking(name: str = '', players: list[SPlayer] | None = None)[source]

Bases: Ranking

Consensus Ranking For the Bradley-Terry Model

Ranking based on the player’s level() method. This also work for Time varying player, inherited class from rstt.player.playerTVS.PlayerTVS, But it needs to be updated manually everytime player’s level is updated.

Attributes

datamodel: rstt.ranking.datamodel.KeyModel (float as rating type) backend: rstt.ranking.inferer.PlayerLevel handler: rstt.ranking.observer.PlayerChecker

Parameters

namestr, optional

A name to identify the ranking, by default ‘’

players_type_, optional

SPlayer to add to the ranking, by default None

Warning

BTRanking validity is limited to Bradley-Terry like models and is not suited for simulation using ‘None-transitive’ level.

class rstt.BasicElo(name: str, default: float = 1500, k: float = 20.0, lc: float = 400.0, base: float = 10.0, players: list[SPlayer] | None = None)[source]

Bases: Ranking

Simple Elo System

Attributes

datamodel: rstt.ranking.datamodel.KeyModel (float as rating type) backend: rstt.ranking.inferer.elo.Elo handler: rstt.ranking.observer.GameByGame

Parameters

namestr, optional

A name to identify the ranking, by default ‘’

defaultfloat, optional

Datamodel parameter, a default elo rating, by default 1500.0

kfloat, optional

Backend parameter, the K value, by default 20.0

lcfloat, optional

Backend parameter, constant dividing the ratings difference in the expected score formula , by default 400.0

playersOptional[List[SPlayer]], optional

Players to register in the ranking, by default None

class rstt.BasicGlicko(name: str, mu: float = 1500.0, sigma: float = 350.0, minRD: float = 30.0, maxRD: float = 350.0, c: float = 63.2, q: float = 0.005756462732485115, lc: int = 400, players: list[SPlayer] | None = None)[source]

Bases: Ranking

Simple Glicko system

Implement A glicko rating system as originaly proposed.

Note

As recommanded in the source paper, the update() method starts by adjusting each players rating before processing any game data (sort of a rating decay)

Attributes

datamodel: rstt.ranking.datamodel.GaussianModel (rstt.ranking.rating.GlickoRating as rating) backend: :class:`rstt.ranking.inferer.Glicko as backend handler rstt.ranking.observer.BatchGame as handler

Parameters

namestr, optional

A name to identify the ranking, by default ‘’

handler_type_, optional

Backend as parameter, by default BatchGame() The original recommendation is to update the ranking by grouping matches within rating period. Which is what the BatchGame Observer do, (each update call represent one period). To match other glicko, use A GameByGame observer

mufloat, optional

Datamodel parameter, the default mu of the rating, by default 1500.0

sigmafloat, optional

Datamodel parameter, the default sigma of the rating, by default 350.0

playersOptional[List[SPlayer]], optional

Players to register in the ranking, by default None

forward(*args, **kwargs)[source]

Internal ‘update’ function

This method calls the handler rstt.stypes.handle_observations() with the parameters of the update function.

Note

FOR RANKING DESIGNER ONLY method designed for devellopers who wants to modify the ranking.update function’s behavivous. In most cases, it is sufficient to write an apropriate observer as the ranking.handler.

However, sometimes it is relevant to do some ranking preprocessing before any rating updates. This would not always be possible to do inside the handle_observations method as the observer do not have access to all ranking attributes.

class rstt.BasicOS(name: str, model=None, players: list[SPlayer] | None = None)[source]

Bases: Ranking

Simple OpenSkill Integretion

Ranking to integrate an openskill model into the rstt package.

Attributes

datamodel: rstt.ranking.datamodel.GaussianModel (openskill.models.rating as rating type) backend: an openskill model instance handler: rstt.ranking.standard.BasicOs.OSGBG, which behaves as a GameByGame observer

Parameters

namestr, optional

A name to identify the ranking, by default ‘’

modelopenskills.models

One of openskills.models implementation, by default None

playersOptional[List[SPlayer]], optional

Players to register in the ranking, by default None

Example:

1from rstt import Player, BasicOS
2from openskill.models import PlackettLuce
3
4competitors = Player.create(nb=10)
5pl = BasicOS(name='Plackett-Luce', model= PlackettLuce(), players=competitors)
6pl.plot()
quality(game: SMatch) → float[source]
class rstt.BasicPlayer(name: str | None = None, level: float | None = None)[source]

Bases: object

Basic Player

BasicPlayer have a level and a name, that is it. The bare minimum for simulation to run. This class is usefull for when your player do not need to track their match history and do not have a time varying level.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelOptional[float], optional

The level/skill/strenght of the player. By default None, in this case a level is generated using a random distribution rstt.config.PLAYER_DIST with default parameters :class:`rstt.config.PLAYER_DIST_ARGS

classmethod create(nb: int, name_gen: Callable[[...], str] | None = None, name_params: Dict[str, Any] | None = None, level_dist: Callable[[...], float] | None = None, level_params: Dict | None = None)[source]

Class method to generate multiple player at once.

Customizable method to generate a bunch of players with your favorite settings.

Parameters

nbint

The amount of player to create and return.

name_genCallable[…, str], optional

A name generator. By default None, in this case names are generated using the names package.

name_paramsDict[str, Any], optional

Kwargs to pass to the name_gen function, by default None.

level_distCallable[…, float], optional

A level generator. By default None, in this case it uses a random distribution specifed by rstt.config.PLAYER_DIST.

level_paramsDict, optional

Kwargs to pass to the level_dist. By default None, in this case it uses default parameters specified by rstt.config.PLAYER_DIST_ARGS

Returns

List[BasicPlayer]

A list of player.

level() → float[source]

Getter method for the player’s level

Returns

float

The level of the player.

name() → str[source]

Getter method for the name of the player

Returns

str

The name of the player

classmethod seeded_players(nb: int, start: int = 0, inc: float = 100)[source]

Create ‘seeded’ players

Unlike the rstt.player.basicplayer.BasicPlayer.create() method, players generated have a deterministic name and level. Names are of the form f”Seed_{i}”, and the lowest i, the higher the level of the player.

Warning

The rstt package relies on player’s name to identify them - there is no ID. This method can result in name clashing which may lead to confusion and unexpected bahaviour accross simulations. It is heavly recommanded to be carefull when calling this method multiple times. Either by tuning the ‘start’ parameter or deleting previously created player.

Parameters

nbint

The amount of player to create and return.

startint, optional

The first ‘i’ for the name of players, by default 0.

incfloat, optional

The difference of level between playery Seed_i and Seed_i+1, by default 100.

Returns

List[BasicPlayer]

A list of seeded player in desceding order of level.

class rstt.BetterWin(with_draw: bool = False)[source]

Bases: object

BetterWin Solver

Implements a deterministic Score generator. BetterWin always assign a Win to the best (highest level) participant of a match.

Warning

Only Supports Duel at the moment.

Parameters

with_drawbool, optional

Wether a draw should be assigned to the game in case of equals level, by default False. When False, there is a ‘home advantage policy’ meaning that in case of equals levels, the first team of the match wins.

solve(duel: Duel, *args, **kwars) → None[source]
class rstt.BradleyTerry[source]

Bases: ScoreProb

Bradley-Terry model

Implements the famous pairwise model comparaison probabilistic model.

It is a ScoreProb Solver where the probability function that a player A with level a, beats a player B with level b, is defined as

P(A win against B) := a/(a + b)

class rstt.CoinFlip[source]

Bases: WeightedScore

Random Solver

Behave like a coin flip, a win or a lose is randomly generated with no regards to any Match details.

class rstt.Competition(name: str, seeding: ~rstt.ranking.ranking.Ranking, solver: ~rstt.stypes.Solver = <rstt.solver.solvers.BetterWin object>, cashprize: dict[int, float] | None = None)[source]

Bases: object

NOTE: In the future the competition class could evolve.

  • inherit from a Scheduler class

  • composition over inheritance:

    • PlayerManager -> dealing with seedings or ratings

    • GameManager -> dealing with Match types and matching

    • EventManager -> dealing with the event id, achivements of players, final standing

Tournament General Template & Workflow.

Abstract class handling specificity related to Competition.

In rstt Competition are ‘Scheduler bounded in time and space’. Unlike live matchmaking, it has a start, an end and a finite well defined amount of participants.

Competition generate automatically matches in a coehrent, meaningfull fashion.

Parameters

namestr

A unique name to identify the Event.

seedingRanking

A ranking used for seeding purposes.

solverSolver, optional

A Solver to generate match outcomes, by default BetterWin()

cashprizeOptional[Dict[int, float]], optional

A ‘prizepool’ rewarding player with ‘money’ for their success (placement in the final standing) during the Event, by default None

Attention

0.6.5 [attribute changes] the ‘participants’ attribute has been encapsulated, use the corresponding get method to access it. Reminder that to ‘set’ participants you can use the registration method.

edit(games: List[Duel])[source]

Handles competition state after each round

Do not use if you simply want to run the competition.

Parameters

gamesList[Duel]

The game splayed during the round.

Returns

bool

If True the round was the last one, no more game will be played and the competition will end.

games(by_rounds=False) → List[Duel] | List[List[Duel]][source]

Getter for all matches played during the event.

In many Competition, matches are organized in ‘rounds’ and follow a chronological order. This method support two query with a return values respecting or not the round structure Parameters ———- by_rounds : bool, optional

Wether to return the matches grouped by rounds or not, by default False and a flat list is returned.

Returns

Union[List[Duel], List[List[Duel]]]

All matches played during the event.

abstract generate_games() → List[Duel][source]

Function called every ‘round’ to generate games. Should return games WITHOUT scores assigned

live() → bool[source]

Indicate if a competition is being played

It means that games are being played and generated. Almost no operations are possible when live.

Returns

bool

True if competition is curretnly generating and playing matches.

name() → str[source]

Getter for the name of the Competition

Returns

str

the name of the competition (used as identifier in the package)

over() → bool[source]

Indicate that the competition has ended

When over, it means all games were played and player’s have collected their achievements.

Returns

bool

True if the competition is over, no more game will be played, the standing is final

participants() → list[SPlayer][source]

Getter for SPlayer taking part in the Competition

Returns

list[SPlayer]

competitors playing game(s).

play()[source]

Plays the competition

Do not use if you simply want to run the competition.

Raises

RuntimeError

An error is raised if the competition is not in a suited state, if it has not started yet.

play_games(games: List[Duel]) → List[Duel][source]

Assign scores to generated matches

Do not use if you simply want to run the competition.

Parameters

gamesList[Duel]

Unplayed/unsolved matches to assign a score to.

Returns

List[Duel]

the games with a scored.

registration(players: SPlayer | List[SPlayer] | Set[SPlayer])[source]

Add player to compete

The seedings do not define who participate in the event. You need to call registration to specify who plays. The method can be called anytime you want before the start of competition, but should not be called afterwards. A player can only participate once but multiple registration will have no effect for the said player. Unranked player will receive a seed corresponding to the default value - NOT ALWAYS lower seed. Unseeded player WILL NOT be added to the ranking.

Parameters

playersUnion[SPlayer, List[SPlayer], Set[SPlayer]]

Playrs taking part in the event’s matches.

run()[source]

Automated Competition execution

This is the magic methods that does all the works.

A Diagram will be added to the doc to illustrate the process better than words.

Raises

RuntimeError

An error is raised if the competition is not in a suited state, if it has already started.

standing() → Dict[SPlayer, int][source]

Getter for the standing

The standing of a competition indicate where player have finished.

Returns

Dict[SPlayer, int]

Final standing of the event

start()[source]

Starts the competition

Do not use if you simply want to run the competition

started() → bool[source]

Indicate if the competition started

Once a competition has started, calls on registration() and start() methods will have no effects.

Returns

bool

wheter the competition has started or not

top(place: int | None = None) → Dict[int, List[SPlayer]] | List[SPlayer][source]

Getter for players by their final placement

Sugar method to access a player by his placement rather than dealing with a the standing.

Parameters

placeOptional[int], optional

The place that you want to know which player(s) ended at, by default None. If None, the return value is a Dictionary where keys are int and values list of players that finished at the ‘key place’.

Returns

Union[Dict[int, List[SPlayer]], List[SPlayer]]

Either a list of player placed at the ‘place’ position in the standing, or a full dictionary with all places as key.

trophies()[source]

Closure ceremony

Establish the final standing and reward players with their respective rstt.stypes.Achievement.

Do not use if you simply want to run the competition.

class rstt.DoubleEliminationBracket(name: str, seeding: ~rstt.ranking.ranking.Ranking, solver: ~rstt.stypes.Solver = <rstt.solver.solvers.BetterWin object>, lower_policy: ~typing.Callable[[list[any]], list[any]] = <function DoubleEliminationBracket.<lambda>>, injector_policy: ~typing.Callable[[list[any], list[any]], list[any]] = <function riffle_shuffle>, cashprize: dict[int, float] = {})[source]

Bases: Competition

Double Elimination Bracket

Variation of the Single Elimination Bracket where participants have a 2nd chance after losing before elimination.

Tournament General Template & Workflow.

Abstract class handling specificity related to Competition.

In rstt Competition are ‘Scheduler bounded in time and space’. Unlike live matchmaking, it has a start, an end and a finite well defined amount of participants.

Competition generate automatically matches in a coehrent, meaningfull fashion.

Parameters

namestr

A unique name to identify the Event.

seedingRanking

A ranking used for seeding purposes.

solverSolver, optional

A Solver to generate match outcomes, by default BetterWin()

cashprizeOptional[Dict[int, float]], optional

A ‘prizepool’ rewarding player with ‘money’ for their success (placement in the final standing) during the Event, by default None

Attention

0.6.5 [attribute changes] the ‘participants’ attribute has been encapsulated, use the corresponding get method to access it. Reminder that to ‘set’ participants you can use the registration method.

games(by_rounds=False, upper=False, lower=False)[source]

Getter for all matches played during the event.

In many Competition, matches are organized in ‘rounds’ and follow a chronological order. This method support two query with a return values respecting or not the round structure Parameters ———- by_rounds : bool, optional

Wether to return the matches grouped by rounds or not, by default False and a flat list is returned.

Returns

Union[List[Duel], List[List[Duel]]]

All matches played during the event.

generate_games()[source]

Function called every ‘round’ to generate games. Should return games WITHOUT scores assigned

class rstt.Duel(player1: SPlayer, player2: SPlayer, tracking: bool | None = None)[source]

Bases: Match

Duel class

Duel is a special type of rstt.game.match.Match with only two teams each consisiting of one player. In other words, two players facing each others.

Parameters

player1SPlayer

A player considered at ‘home’.

player2SPlayer

A player considered as ‘visitor’

trackingbool, optional

If true, the duel will try to add itself (once it has been assigned a score) to the both player’s game history, by default None.

isdraw() → bool[source]

Getter method indicating a draw

A draw is a match where both player have the same scores, ranks.

Returns

bool

True if both player have the same score, in that case the rstt.game.match.Duel.winner() and rstt.game.match.Match.loser() return None. False if the duel has a winner and a loser.

loser() → SPlayer[source]

Getter method for the loser of the duel

The loser is the player with the lowest score value, highest rank.

Returns

SPlayer

The loser of the duel. Can be None if the duel has not yet been played or in the case of a draw.

opponent(player: SPlayer) → SPlayer[source]

Getter method for the opponent of a player in a duel

Suger method that returns the same value has rstt.game.match.Match.opponents(), but grammatically more correct has there is only one opponent in a duel.

Parameters

playerSPlayer

A player to get the opponent.

Returns

Splayer

The opponent of the parameter player.

Raises:

KeyError

When the parameter player is not a participant of the duel.

player1() → SPlayer[source]

Getter method for player 1

Player1 can also be refer has the one playing at ‘home’.

Returns

SPlayer

the first player of the duel.

player2() → SPlayer[source]

Getter method for palyer 2

Player2 - the opponent of player1 - can also be refered as ‘visitor’ or playing ‘away’.

Returns

SPlayer

the 2nd player of the duel.

winner() → SPlayer[source]

Getter method for the winner of the duel

In a direct confrontation between two competitors, there is usually a winner (the one with the highest score, lowest rank) and a loser.

Returns

SPlayer

The winner of the duel. Can be None if the duel has not yet been played or in the case of a draw.

class rstt.GaussianPlayer(name: str | None = None, mu: float | None = None, sigma: float | None = None)[source]

Bases: PlayerTVS

Player with a level following a gaussian distribution

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

mufloat, optional

The player’s mean level, also considered as the ‘original’ level. By default None, in this case a level is generated using a random distribution rstt.config.GAUSSIAN_PLAYER_MEAN_DIST with default parameters :class:`rstt.config.GAUSSIAN_PLAYER_MEAN_ARGS

sigmafloat, optional

The player’s level standard deviation. By default None, in this case a random value is generated using a random distribution rstt.config.GAUSSIAN_PLAYER_SIGMA_DIST with default parameters :class:`rstt.config.GAUSSIAN_PLAYER_SIGMA_ARGS

Example

The figure below shows a population of 10 players generated with .create() without specifics params.

_images/GaussianPlayer.pdf
class rstt.LogSolver(base: float | None = None, lc: float | None = None)[source]

Bases: ScoreProb

Elo like Solver

The LogSolver implements a standard reparametrization of the Bradley-Terry model that matches Elo rating system. In practice it is a ScoreProb with a probability function illustrated on wismuth. FOr a player A with level a, and a Player B with level b, it is defined by the logistic function: P(A wins against B) = 1/(1+base^( (b-a) / lc))

Parameters

baseOptional[float], optional

The base in the logistic function, by default 10

lcOptional[float], optional

The constant in the logistic function, by default 400

Note

Default constant in the RSTT package ensure that the LogSolver probabilities matches the expected Score by rstt.ranking.inferer.Elo. Which means that perfectly accurate predictions are possible when combining both in simulation.

class rstt.Match(teams: list[list[SPlayer]], tracking: bool | None = None)[source]

Bases: object

Match base Class

General purpose match class. It can be used to create arbitrary game mode such as Many-versus-Many or Free-For-All games.

Parameters

teamsList[List[SPlayer]]

Participants of the match organized in a list of list. Players in the same sublist are part of the same team.

trackingbool, optional

If true, the match will try to add itself to the participants game history, by default None.

Raises

ValueError:

A Splayer can not be an element of two distinct sublist in the parameter teams.

live() → bool[source]

Getter method for the match status

A live match is a match that has not yet been assigned an outcome/result.

Returns

bool

True if the match has yet to be played. False if the match has a scores assigned.

opponents(player: SPlayer) → list[SPlayer][source]

Getter method for opponents

Opponents are participants of the match that or not in the same team as the given player.

Parameters

playerSPlayer

A player to get the opponents

Returns

List[SPlayer]

A list of opponents playing against the player, in a single list, not grouped by teams

players() → list[SPlayer][source]

Getter method for player

Unlike rstt.game.match.Match.teams(), it returns a simple list of SPlayer, without grouping them by teams.

Returns

List[SPlayer]

All the participants of the match.

ranks() → list[int][source]

Getter method for the team ranks

The ranks method is an alternative to the scores method. For a Match between n teams, the return list contains the values 1,…,n. The higher the score of a team, the lower the value in the return list.

Returns

List[int]

The rank of each team.

Raises

RuntimeError

This method can only be called when the match has been played and assigned a score.

score(player: SPlayer) → float[source]

Getter method for the score of a given player.

Unlike the rstt.game.match.Match.scores(), this function return a single float value representing the success the parameter player had.

Parameters

playerSPlayer

A player to get the score.

Returns

float

A value representing the score, result of the player.

Raises

RuntimeError

This method can only be called when the match has been played and assigned a score.

scores() → list[float][source]

Getter method for the match outcome

The result/outcome of the match. A rstt.stypes.Score is a list of float. The length of the Score is equal to the number of teams (i.e the length of the return value of :func: rstt.game.match.Match.teams).

Returns

Score

The outcom of the match. None if the match has not been played yet. Ordering of the float value matches the ordering of the teams as return by rstt.game.match.Match.teams()

teammates(player: SPlayer) → list[SPlayer][source]

Getter method for teammates

Teammates of a player are other players in the same teams

Parameters

playerSPlayer

A player to get teammates

Returns

List[SPlayer]

All the player’s teammates

teams() → list[list[SPlayer]][source]

Getter method for teams

Returns

List[List[SPlayer]]

All the players participating in the match grouped by teams.

class rstt.Player(name: str | None = None, level: float | None = None)[source]

Bases: BasicPlayer

Player with match history.

Player extends rstt.player.basicPlayer.BasicPlayer with the possibility to track games it played in and by collecting results achieved in rstt.stypes.Achievement.

Parameters

namestr, optional

A unique name to identify the player. By default None, in this case a name is randomly generated.

levelfloat, optional

The level/skill/strenght of the player. By default None, in this case a level is randomly generated. using a random distribution rstt.config.PLAYER_DIST with default parameters :class:`rstt.config.PLAYER_DIST_ARGS

achievements() → List[Achievement][source]

Getter method for achievement

rstt.stypes.Achievement represent tournament result of the player.

Returns

List[Achievement]

All past success of the player in chronological order, from the oldest to the most recent.

add_game(match: Match) → None[source]

Adds match to the player history

Parameters

matchMatch

A match to track.

Raises

ValueError

The match needs to be a game in which the player partipiated in and not already tracked. Either condition violated will raise an Error.

collect(achievement: Achievement | List[Achievement])[source]

Adds achivement(s) to the player history.

Parameters

achievementUnion[Achievement, List[Achievement]]

Achievement(s) passed must have a different event_name attribute that the one already stored.

Raises

ValueError

Raised when attempting to collect an event with an event_name already present in the player history.

earnings() → float[source]

Getter method for the earnings

Sugar method that returns the sum of earnings specified by the player achievements.

Returns

float

All the money earned in competitif event.

games() → List[Match][source]

Getter method for match the player participated in

Returns

List[Match]

All the matches the player played in chronolgical order, from oldest to the most recent.

reset(games: bool = True, achievement: bool = True) → None[source]

Clean the player history

Removes all matchs and achievements from the players history.

Parameters

gamesbool, optional

Wether matchs should be removed, by default True.

achievementbool, optional

Wether achievements should be removed, by default True.

class rstt.RandomRound(name: str, seeding: ~rstt.ranking.ranking.Ranking, solver: ~rstt.stypes.Solver = <rstt.solver.solvers.BetterWin object>, cashprize: dict[int, float] = {}, rounds: int = 1, amount: int = 1)[source]

Bases: RoundRobin

Random tournament

Class to generate a bunch of arbitrary matches.

This is not a real ‘competition’ as it is not intended to determine a winner. But the class works as a competition and thus produces a final standing the same way a RoundRobin does - by summing matches scores. It is however ‘unfair’ in the sense that there is no guarantee that participants play the same amount of games. It is even possible some registered participant do not play a single match.

Parameters

namestr

A unique name to identify the Event.

seedingRanking

A ranking used for seeding.

solverSolver, optional

A Solver to generate match outcomes, by default BetterWin()

cashprizeOptional[Dict[int, float]], optional

A ‘prizepool’ rewarding player with ‘money’ for their success (placement in the final standing) during the Event, by default None

roundsint, optional

Number of rounds to be played, by default 1. Participants play at most one match per rounds.

amount: int, optional

Number of game to produce by rounds, by default 1.

Note

Calling with amount=1 and rounds=n makes it a pure random scheduler that generates n matches.

class rstt.Ranking(name: str, datamodel: RatingSystem, backend: Inference, handler: Observer, players: List[SPlayer] | None = None)[source]

Bases: object

Ranking for players

The rstt package implements its own definition of a ranking.

Formally an rstt ranking consist of a

  • A standing: An ordered sequence of players associated with an indication of their skills.

  • A rating system - storing player’s rating.

  • A statistical inference system - set of equations.

  • An update procedure

And two ‘hidden’ notions:

  • Observables: the set of ‘update triggers’ justifying a change of ratings. (what can be processed by the handler)

  • An ordinal function converting rating into float values (provided by the rating system)

Parameters

namestr

A name to identify the ranking

datamodelRatingSystem

A container storing rating of players and providing an orinal() funtion to convert rating into floating values.

backendInference

The ‘math’ behind the ranking system.

handlerObserver

A workflow handling the ranking update procedure

playersOptional[List[SPlayer]], optional

Players to register in the ranking, by default None

add(*args: Any, **kwargs: Any) → Any[source]
fit(*args: Any, **kwars: Any) → Any[source]
forward(*args, **kwargs)[source]

Internal ‘update’ function

This method calls the handler rstt.stypes.handle_observations() with the parameters of the update function.

Note

FOR RANKING DESIGNER ONLY method designed for devellopers who wants to modify the ranking.update function’s behavivous. In most cases, it is sufficient to write an apropriate observer as the ranking.handler.

However, sometimes it is relevant to do some ranking preprocessing before any rating updates. This would not always be possible to do inside the handle_observations method as the observer do not have access to all ranking attributes.

players() → List[SPlayer][source]

Get method of all keys

Alias for Ranking.standing.keys()

Returns

List[Player]

A list of all player in descending order of their associated values.

plot(*args: Any, **kwars: Any) → Any[source]
point(player: SPlayer) → float[source]

Get the point associated to a key

Alias for Ranking.standing.value(player)

Returns

float

the associated value.

points() → List[float][source]

Get method of all values

Alias for Ranking.standing.values()

Returns

List[float]

A list of all associated values in descending order.

rank(player: SPlayer) → int[source]

Getter for player Rank

Equivalent to ranking.standing[player].

Parameters

playerSPlayer

A player to get his rank.

Returns

int

The rank of the player

ranks(players: List[SPlayer]) → List[int][source]

Getter for players Rank

Equivalent to ranking.standing[players].

Parameters

playersSPlayer

Player to get their ranks.

Returns

List[int]

The corresponding ranks of the players

rating(player: SPlayer) → Any[source]

Get method for rating

Rating object is the internal model associated to a key. Ratings are used to automaticly compute values for the sorting feature of a Standing.

Parameters

playerPlayer

A key in the Ranking

Returns

Any

The associated model to the provided key. The type is defined by Ranking.RatingSystem.rtype

Raises

KeyError

ratings() → List[Any][source]

Get method for all ratings

Returns

list[Any]

A list of all rating object present in the Ranking, in order of the Standing.

rerank(*args: Any, **kwargs: Any) → Any[source]
set_rating(*args: Any, **kwargs: Any) → Any[source]
update(*args: Any, **kwargs: Any) → Any[source]
class rstt.RoundRobin(name: str, seeding: ~rstt.ranking.ranking.Ranking, solver: ~rstt.stypes.Solver = <rstt.solver.solvers.BetterWin object>, cashprize: ~typing.Dict[int, float] = {})[source]

Bases: Competition

Round-Robin Tournament

Implements the famous tournament system. The matching technique used to generate matches is the ‘circle’ algorithm illustrated here.

A simpl specification of the tournament reads like this:

  • a total of n x (n-1) matche is played in n-1 rounds.

  • each rounds every participants play exactly one opponent.

  • every players faces each others exactly once

  • standing is based on the player’s matches scores.

generate_games()[source]

Function called every ‘round’ to generate games. Should return games WITHOUT scores assigned

next_round()[source]
class rstt.SingleEliminationBracket(name: str, seeding: ~rstt.ranking.ranking.Ranking, solver: ~rstt.stypes.Solver = <rstt.solver.solvers.BetterWin object>, cashprize: dict[int, float] = {})[source]

Bases: Competition

Single Elimination Bracket or tournament

One of the most famous and used competition model, specialy in internationl events, Participants are placed in a binary tree where the winner of a confrontation advance to the next stage and the loser is eliminated.

More detail on the single-elimination-bracket wikipedia page.

Note

Currently the first round matching is the standard policy. for example with 8 participants: Seed1 versus Seed8; Seed4 versus Seed5; Seed2 versus Seed7; Seed3 versus Seed6.

Future version will support custom first round matching. In the mean time, to fine tune the first round, it is possible to reorder a ranking with a permutation using the rstt.ranking.ranking.Ranking.rerank() method. This needs to be called on a ranking before passing it to a competition.

Tournament General Template & Workflow.

Abstract class handling specificity related to Competition.

In rstt Competition are ‘Scheduler bounded in time and space’. Unlike live matchmaking, it has a start, an end and a finite well defined amount of participants.

Competition generate automatically matches in a coehrent, meaningfull fashion.

Parameters

namestr

A unique name to identify the Event.

seedingRanking

A ranking used for seeding purposes.

solverSolver, optional

A Solver to generate match outcomes, by default BetterWin()

cashprizeOptional[Dict[int, float]], optional

A ‘prizepool’ rewarding player with ‘money’ for their success (placement in the final standing) during the Event, by default None

Attention

0.6.5 [attribute changes] the ‘participants’ attribute has been encapsulated, use the corresponding get method to access it. Reminder that to ‘set’ participants you can use the registration method.

generate_games()[source]

Function called every ‘round’ to generate games. Should return games WITHOUT scores assigned

class rstt.Snake(*args, **kwars)[source]

Bases: Competition

The Snake Tournament

This format is not a standard one. It is a model I detail and justify the interest in my master thesis and should be the subject of a paper in an hopefully near future.

It does have some ressamblances with the Ladder tournament. I am aware of two practical instances of uses:

Quick Overview:

  • For n participants it produces n-1 matches.

  • Every participants plays at least one match.

  • The final standing is an untied ranking.

  • Matches are all ‘a priori balanced’.

Tournament General Template & Workflow.

Abstract class handling specificity related to Competition.

In rstt Competition are ‘Scheduler bounded in time and space’. Unlike live matchmaking, it has a start, an end and a finite well defined amount of participants.

Competition generate automatically matches in a coehrent, meaningfull fashion.

Parameters

namestr

A unique name to identify the Event.

seedingRanking

A ranking used for seeding purposes.

solverSolver, optional

A Solver to generate match outcomes, by default BetterWin()

cashprizeOptional[Dict[int, float]], optional

A ‘prizepool’ rewarding player with ‘money’ for their success (placement in the final standing) during the Event, by default None

Attention

0.6.5 [attribute changes] the ‘participants’ attribute has been encapsulated, use the corresponding get method to access it. Reminder that to ‘set’ participants you can use the registration method.

generate_games() → List[Duel][source]

Function called every ‘round’ to generate games. Should return games WITHOUT scores assigned

class rstt.Standing(default: float = 0.0, lower: float = -2147483648, upper: float = 2147483647, step: float = 1.0, protocol: str = 'set')[source]

Bases: object

A Standing object emulate a value-based ordered dictionary.

The Standing also act as a <list> and a <dict> and the following relationship exist:

  • Index -> Key

  • Key -> Index

Keys oredring is descedning and based on the associated value of the key, i.e Standing.point(key).

The key ordering is maintain by internal mechanism as long as the Standing is manipulate with the provided methods and functionnalities.

Examples

Note

Ordering is computationaly demanding, which means that repeated operations on a large Standing could result in performances issues. It is possible to turn off the ordering features. This break the whole point of the class. Do it only if needed and if you know what your are doing

In its current form Key are intended to be of Type <Player> and Value of type <float>. This may change in the future to support a more general case such as: Key of type <Hasable> -> Value of type <Comarapble>.

Parameters

defaultfloat, optional

A key added to the standing without an associated value will be assign this default value, by default 0.0

minfloat, optional

The minimal boundary for values, by default np.iinfo(np.int32).min

maxfloat, optional

The maximal boundary for values, by default np.iinfo(np.int32).max

stepfloat, optional

An interval used for insertion operation , by default 1.0 NOTE: not completely supported, could disapear in futur version.

fit(keys: List[SPlayer])[source]

Create a new Standing instance containing only the given Keys

The Keys will have the same value as in the current Standing if present otherwise the default value will be assigned.

Parameters

keysList[Player]

list of <Player> to be present in the new Standing

Returns

Standing

class rstt.SuccessRanking(name: str, window_range: int = 1, tops: int = 1, buffer: int | None = None, nb: int | None = None, players: list[SPlayer] | None = None, default: dict[int, float] | None = None)[source]

Bases: Ranking

Merit Based Ranking

Usefull to implement Ranking system like the one in tennis for example.

Attributes

datamodel: rstt.ranking.datamodel.KeyModel (int as rating) backend: rstt.ranking.inferer.EventScoring handler: rstt.ranking.observer.PlayerChecker

Parameters

namestr, optional

A name to identify the ranking, by default ‘’

bufferint

Backend parameter. The number of event to consider for the rating, starting from the last.

nbint

Backend parameter. The actual number of event in the buffer to use for the ratings computation.

defaultOptional[Dict[int, float]], optional

Backend Parameter. Mapping placement in event to points for the rating, by default None

playersOptional[List[SPlayer]], optional

Players to register in the ranking, by default None

forward(event: Event | None = None, events: list[Event] | None = None)[source]

Internal ‘update’ function

This method calls the handler rstt.stypes.handle_observations() with the parameters of the update function.

Note

FOR RANKING DESIGNER ONLY method designed for devellopers who wants to modify the ranking.update function’s behavivous. In most cases, it is sufficient to write an apropriate observer as the ranking.handler.

However, sometimes it is relevant to do some ranking preprocessing before any rating updates. This would not always be possible to do inside the handle_observations method as the observer do not have access to all ranking attributes.

class rstt.SwissBracket(name: str, seeding: ~rstt.ranking.ranking.Ranking, solver: ~rstt.stypes.Solver = <rstt.solver.solvers.BetterWin object>, matchings: ~typing.Dict[~typing.Tuple[int, int], ~rstt.stypes.Shuffler] | None = None, seeders: ~typing.Dict[~typing.Tuple[int, int], ~rstt.stypes.Seeder] | None = None, generators: ~typing.Dict[~typing.Tuple[int, int], ~rstt.stypes.Generator] | None = None, evaluators: ~typing.Dict[~typing.Tuple[int, int], ~rstt.stypes.Evaluator] | None = None, def_matching: ~rstt.stypes.Shuffler = <class 'rstt.scheduler.tournament.swissbracket.DummyParam'>, def_seeder: ~rstt.stypes.Seeder = <class 'rstt.scheduler.tournament.swissbracket.DummyParam'>, def_generator: ~rstt.stypes.Generator = <class 'rstt.scheduler.tournament.swissbracket.DummyParam'>, def_evaluator: ~rstt.stypes.Evaluator = <class 'rstt.scheduler.tournament.swissbracket.DummyParam'>, cashprize: ~typing.Dict[int, float] | None = None)[source]

Bases: Competition

The Swiss Bracket

The format is mention in the esports variation of the Swiss Round wikipedia page and was originaly introduce for Counter-Strike event in 2016. Hower both format differ drastically in many regards, one being their usage and output.

  • In Swiss Round there is a single undefeated participant, thus is great to crown a winner among many participants.

  • In Swiss Bracket, 16 teams are split into 8 qualified and 8 eliminated participants.

The name choice come from the Valve rule book for Counter-Strike major competition, that specify a matching policy.

Parameters

namestr

A unique name to identify the Event.

seedingRanking

A ranking used for seeding purposes.

solverSolver, optional

A Solver to generate match outcomes, by default BetterWin()

matchingsOptional[Dict[Tuple[int, int], Shuffler]], optional

A collection of matching strategy for rounds, by default None Keys are tuple (number of win, number of lose) to indicate when the strategy is used.

seedersOptional[Dict[Tuple[int, int], Seeder]], optional

A scollection of eeding strategy for rounds, by default None Keys are tuple (number of win, number of lose) to indicate when the strategy is used.

generatorsOptional[Dict[Tuple[int, int], Generator]], optional

A collection of generator for rounds, by default None Keys are tuple (number of win, number of lose) to indicate when the generator is used.

evaluatorsOptional[Dict[Tuple[int, int], Evaluator]], optional

A collection of evaluators for rounds, by default None Keys are tuple (number of win, number of lose) to indicate when the strategy is used.

def_matchingShuffler, optional

A default matching strategy for rounds where the matchings param does not provide one, by default DummyParam

def_seederSeeder, optional

A default seeding strategy for rounds where the seeders param does not provide one, by default DummyParam

def_generatorGenerator, optional

A default generator for rounds where the generator param does not provide one, by default DummyParam

def_evaluatorEvaluator, optional

A default evaluator for rounds where the evaluators param does not provide one, by default DummyParam

cashprizeOptional[Dict[int, float]], optional

A ‘prizepool’ rewarding player with ‘money’ for their success (placement in the final standing) during the Event, by default None

Note

The design of the class alows extreme customization on the matching at any point of the competition. If you do not provide a matching, seeders, genrators, evaluators and their associated default, the class uses a DummyParam for all.

Refer to the rstt.stypes documentation for the parameters type and impact on the tournament games.

draws(group: List[SPlayer]) → List[List[Duel]][source]
generate_games()[source]

Function called every ‘round’ to generate games. Should return games WITHOUT scores assigned

results()[source]
round_scores() → List[Tuple[int, int]][source]
score(player: SPlayer) → Tuple[int, int][source]
class rstt.SwissRound(name: str, seeding: ~rstt.ranking.ranking.Ranking, solver: ~rstt.stypes.Solver = <rstt.solver.solvers.BetterWin object>, cashprize: ~typing.Dict[int, float] = {})[source]

Bases: RoundRobin

Swiss Round

Also known as Swiss System.

It is a variation of the Round-Robin system, that fixes some issues:

  • ~ n X log2(n) matches played, which for large n (participants) is significantly faster than round-robin.

  • each rounds every participants play exactly one opponent with the same score. Which creates more interesting and balance game overall.

  • every players should face at most once other players (not always possible).

Warning

  • Undefined behaviour when the number of registered player is not a power of 2.

  • The current matching strategy (greedy) has some issues and may lead to errors, this has been observed for number of participants above 256.

draws(players)[source]
make_groups()[source]
next_round()[source]
class rstt.WinRate(name: str, default: float = -1.0, scope: int = 2147483647, players: list[SPlayer] | None = None)[source]

Bases: Ranking

Ranking based on Win rate

Ranking that tracks the winrate of rstt.player.player.Player. The update function does not take any parameters, win rate is computed directly with the player’s game history.

Attributes

datamodel rstt.ranking.datamodel.KeyModel (float as rating) backend rstt.ranking.inferer.PlayerWinPRC handler rstt.ranking.observer.PlayerChecker

Parameters

namestr, optional

A name to identify the ranking, by default ‘’

defaultfloat, optional

A default rating value for when player have no game in their history, by default -1.0

playersOptional[List[SPlayer]], optional

Players to register in the ranking, by default None

forward(*args, **kwargs)[source]

Internal ‘update’ function

This method calls the handler rstt.stypes.handle_observations() with the parameters of the update function.

Note

FOR RANKING DESIGNER ONLY method designed for devellopers who wants to modify the ranking.update function’s behavivous. In most cases, it is sufficient to write an apropriate observer as the ranking.handler.

However, sometimes it is relevant to do some ranking preprocessing before any rating updates. This would not always be possible to do inside the handle_observations method as the observer do not have access to all ranking attributes.