Competitors API Reference

This page provides detailed API documentation for all competitor classes in Elote.

Base Competitor

class elote.competitors.base.BaseCompetitor(**kwargs: Any)

Bases: ABC

Base abstract class for all rating system competitors.

This class defines the interface that all rating system implementations must follow. Each competitor represents an entity with a rating that can be compared against other competitors of the same type.

All rating system implementations should inherit from this class and implement the abstract methods. This ensures a consistent API across all rating systems.

Class Attributes:

_minimum_rating (float): The minimum allowed rating value. Default: 100.

This prevents ratings from becoming negative or unreasonably low.

Initialize base competitor state.

abstract __init__(**kwargs: Any) → None

Initialize base competitor state.

abstract beat(competitor: BaseCompetitor) → None

Update ratings after this competitor has won against the given competitor.

This method updates the ratings of both this competitor and the opponent based on the match outcome where this competitor won.

Args:

competitor (BaseCompetitor): The opponent competitor that lost.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

configure(**kwargs: Any) → None

Configure instance-level parameters for this competitor.

This method allows setting instance-level parameters that affect only this competitor.

Args:

**kwargs: Keyword arguments for instance-level parameters.

Raises:

InvalidParameterException: If any parameter is invalid.

classmethod configure_class(**kwargs: Any) → None

Configure class-level parameters for this rating system.

This method allows setting class-level parameters that affect all instances of this rating system.

Args:

**kwargs: Keyword arguments for class-level parameters.

Raises:

InvalidParameterException: If any parameter is invalid.

abstract expected_score(competitor: BaseCompetitor) → float

Calculate the expected score (probability of winning) against another competitor.

Args:

competitor (BaseCompetitor): The opponent competitor to compare against.

Returns:

float: The probability of winning (between 0 and 1).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

This method exports the competitor’s state in a standardized format that can be used to recreate the competitor with the same state. The format includes: - type: The class name of the competitor - version: The version of the serialization format - created_at: The timestamp when the state was exported - id: A unique identifier for this state export - parameters: The parameters used to initialize the competitor - state: The current state variables of the competitor

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_json(json_str: str) → T

Create a new competitor from a JSON string.

Args:

json_str (str): A JSON string representing a competitor’s state.

Returns:

BaseCompetitor: A new competitor with the state from the JSON string.

Raises:

InvalidStateException: If the JSON string is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

classmethod from_state(state: Dict[str, Any]) → T

Create a new competitor from a state dictionary.

Args:

state: A dictionary containing the state of a competitor, including its type and parameters.

Returns:

A new competitor of the same type as the exported one.

Raises:

InvalidStateException: If the state format is invalid or missing required fields.

classmethod get_competitor_class(class_name: str) → Type[BaseCompetitor]

Get a competitor class by name.

Args:

class_name (str): The name of the competitor class.

Returns:

Type[BaseCompetitor]: The competitor class.

Raises:

InvalidParameterException: If the class name is not registered.

import_state(state: Dict[str, Any]) → None

Import the competitor’s state from a dictionary.

This method updates the competitor’s state based on the provided dictionary, including parameters and current state variables.

Args:

state (dict): A dictionary containing the state of a competitor.

Raises:

InvalidStateException: If the state dictionary is invalid or incompatible. InvalidParameterException: If any parameter in the state is invalid.

classmethod list_competitor_types() → List[str]

List all registered competitor types.

Returns:

List[str]: A list of registered competitor type names.

lost_to(competitor: BaseCompetitor) → None

Update ratings after this competitor has lost to the given competitor.

This is a convenience method that calls beat() on the winning competitor.

Args:

competitor (BaseCompetitor): The opponent competitor that won.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

abstract property rating: float

Get the current rating value of this competitor.

Returns:

float: The current rating value.

abstract reset() → None

Reset the competitor’s state to its initial configuration.

This method should revert any changes made through updates (beat, lost_to, tied) and re-import the initial parameters and state. Note: Actual implementation might be needed depending on how initial state is stored.

abstract tied(competitor: BaseCompetitor) → None

Update ratings after this competitor has tied with the given competitor.

This method updates the ratings of both this competitor and the opponent based on a drawn match outcome.

Args:

competitor (BaseCompetitor): The opponent competitor that tied.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

str: A JSON string representing this competitor’s state.

verify_competitor_types(competitor: BaseCompetitor) → None

Verify that the competitor types match.

Args:

competitor (BaseCompetitor): The competitor to verify.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

exception elote.competitors.base.InvalidParameterException

Bases: Exception

Exception raised when an invalid parameter is provided.

This exception is raised when a parameter value is outside the acceptable range or of an incorrect type for a particular rating system.

exception elote.competitors.base.InvalidRatingValueException

Bases: Exception

Exception raised when an invalid rating value is provided.

This exception is raised when a rating value is outside the acceptable range for a particular rating system.

exception elote.competitors.base.InvalidStateException

Bases: Exception

Exception raised when an invalid state is provided for deserialization.

This exception is raised when a state dictionary is missing required fields or contains invalid values.

exception elote.competitors.base.MissMatchedCompetitorTypesException

Bases: Exception

Exception raised when attempting to compare or update competitors of different types.

This exception is raised when operations are attempted between competitors that use different rating systems, which would lead to invalid results.

Elo Competitor

class elote.competitors.elo.EloCompetitor(initial_rating: float = 400, k_factor: float | None = None)

Bases: BaseCompetitor

Elo rating system competitor.

The Elo rating system is a method for calculating the relative skill levels of players in zero-sum games such as chess. It is named after its creator Arpad Elo, a Hungarian-American physics professor and chess master.

In the Elo system, each player’s rating changes based on the outcome of games and the rating of their opponents. The difference in ratings between two players determines the expected outcome of a match, and the actual outcome is used to update the ratings.

Class Attributes:

_base_rating (float): Base rating divisor used in the transformed rating calculation. Default: 400. _k_factor (float): Factor that determines how much ratings change after each match. Default: 32.

Initialize an Elo competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 400. k_factor (float, optional): The K-factor to use for this competitor. If None,

the class K-factor will be used. Default: None.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating. InvalidParameterException: If the k_factor is negative.

__init__(initial_rating: float = 400, k_factor: float | None = None)

Initialize an Elo competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 400. k_factor (float, optional): The K-factor to use for this competitor. If None,

the class K-factor will be used. Default: None.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating. InvalidParameterException: If the k_factor is negative.

beat(competitor: BaseCompetitor) → None

Update ratings after this competitor has won against the given competitor.

This method updates the ratings of both this competitor and the opponent based on the match outcome where this competitor won.

Args:

competitor (BaseCompetitor): The opponent competitor that lost.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score against another competitor.

Args:

competitor (BaseCompetitor): The competitor to compare against.

Returns:

float: The expected score (probability of winning).

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_state(state: Dict[str, Any]) → T

Create a new competitor from a previously exported state.

Args:

state (dict): A dictionary containing the state of a competitor,

as returned by export_state().

Returns:

EloCompetitor: A new competitor with the same state as the exported one.

Raises:

InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

reset() → None

Reset this competitor to its initial state.

This method resets the competitor’s rating to the initial rating.

tied(competitor: BaseCompetitor) → None

Update ratings after this competitor has tied with the given competitor.

This method updates the ratings of both this competitor and the opponent based on a drawn match outcome.

Args:

competitor (BaseCompetitor): The opponent competitor that tied.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

property transformed_rating: float

Get the transformed rating for this competitor.

Returns:

float: The transformed rating.

Glicko Competitor

class elote.competitors.glicko.GlickoCompetitor(initial_rating: float = 1500, initial_rd: float = 350, initial_time: datetime | None = None)

Bases: BaseCompetitor

Glicko rating system competitor.

The Glicko rating system is an improvement on the Elo rating system that takes into account the reliability of a rating. It was developed by Mark Glickman as an improvement to the Elo system.

In addition to a rating, each competitor has a rating deviation (RD) that measures the reliability of the rating. A higher RD indicates a less reliable rating.

Class Attributes:

_c (float): Rating volatility constant that determines how quickly the RD increases over time.

Default: 34.6, which is calibrated so that it takes about 100 rating periods for a player’s RD to grow from 50 to 350 (maximum uncertainty).

_q (float): Scaling factor used in the rating calculation. Default: 0.0057565. _rating_period_days (float): Number of days that constitute one rating period.

Default: 1.0 (one day per rating period).

Initialize a Glicko competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 1500. initial_rd (float, optional): The initial rating deviation of this competitor. Default: 350. initial_time (datetime, optional): The initial timestamp for this competitor. Default: current time.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating. InvalidParameterException: If the initial RD is not positive.

__init__(initial_rating: float = 1500, initial_rd: float = 350, initial_time: datetime | None = None)

Initialize a Glicko competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 1500. initial_rd (float, optional): The initial rating deviation of this competitor. Default: 350. initial_time (datetime, optional): The initial timestamp for this competitor. Default: current time.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating. InvalidParameterException: If the initial RD is not positive.

beat(competitor: GlickoCompetitor, match_time: datetime | None = None) → None

Update ratings after this competitor has won against the given competitor.

This method updates the ratings of both this competitor and the opponent based on the match outcome where this competitor won.

Args:

competitor (GlickoCompetitor): The opponent competitor that lost. match_time (datetime, optional): The time when the match occurred. Default: current time.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score (probability of winning) against another competitor.

Args:

competitor (BaseCompetitor): The opponent competitor to compare against.

Returns:

float: The probability of winning (between 0 and 1).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_state(state: Dict[str, Any]) → T

Create a new competitor from a previously exported state.

Args:

state (dict): A dictionary containing the state of a competitor,

as returned by export_state().

Returns:

GlickoCompetitor: A new competitor with the same state as the exported one.

Raises:

InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

reset() → None

Reset this competitor to its initial state.

This method resets the competitor’s rating and RD to their initial values.

tied(competitor: GlickoCompetitor, match_time: datetime | None = None) → None

Update ratings after this competitor has tied with the given competitor.

This method updates the ratings of both this competitor and the opponent based on a drawn match outcome.

Args:

competitor (GlickoCompetitor): The opponent competitor that tied. match_time (datetime, optional): The time when the match occurred. Default: current time.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

property tranformed_rd: float

Get the transformed rating deviation of this competitor.

The transformed RD is used in the rating calculation and is capped at 350.

Returns:

float: The transformed rating deviation.

update_competitor_rating(competitor: GlickoCompetitor, s: float) → Tuple[float, float]

Update the rating and RD of this competitor based on a match result.

Args:

competitor (GlickoCompetitor): The opponent competitor. s (float): The score of this competitor (1 for win, 0.5 for draw, 0 for loss).

Returns:

tuple: A tuple containing the new rating and RD.

update_rd_for_inactivity(current_time: datetime | None = None) → None

Update the rating deviation based on time elapsed since last activity.

This implements Glickman’s formula for increasing uncertainty in ratings over time when a player is inactive. The RD increase is controlled by the _c parameter and the number of rating periods that have passed.

Args:

current_time (datetime, optional): The current time to calculate inactivity against.

If None, uses the current system time.

DWZ Competitor

class elote.competitors.dwz.DWZCompetitor(initial_rating: float = 400)

Bases: BaseCompetitor

Deutsche Wertungszahl (DWZ) rating system competitor.

The DWZ is the German chess rating system, similar to Elo but with some differences in how ratings are updated after matches, including factors based on player age and performance.

Class Attributes:

_J (int): Development coefficient. Default: 10.

Initialize a DWZ competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 400.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating.

__init__(initial_rating: float = 400)

Initialize a DWZ competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 400.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating.

beat(competitor: BaseCompetitor, age: int | None = None) → None

Update ratings after this competitor wins against another.

Args:

competitor (BaseCompetitor): The opponent competitor. age (Optional[int]): The age of this competitor at the time of the match.

Used for DWZ calculation. Defaults to 26 (adult).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score (probability of winning) against another competitor.

Args:

competitor (BaseCompetitor): The opponent competitor to compare against.

Returns:

float: The probability of winning (between 0 and 1).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_state(state: Dict[str, Any]) → T

Create a new competitor from a previously exported state.

Args:

state (dict): A dictionary containing the state of a competitor,

as returned by export_state().

Returns:

DWZCompetitor: A new competitor with the same state as the exported one.

Raises:

InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

reset() → None

Reset this competitor to its initial state.

This method resets the competitor’s rating and count to their initial values.

tied(competitor: BaseCompetitor, age: int | None = None) → None

Update ratings after this competitor ties with another.

Args:

competitor (BaseCompetitor): The opponent competitor. age (Optional[int]): The age of this competitor at the time of the match.

Used for DWZ calculation. Defaults to 26 (adult).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

ECF Competitor

class elote.competitors.ecf.ECFCompetitor(initial_rating: float = 100)

Bases: BaseCompetitor

English Chess Federation (ECF) rating system competitor.

The ECF rating system is used by the English Chess Federation to rate chess players. It uses a moving average of performance ratings over a number of periods.

Class Attributes:

_delta (float): Maximum rating difference considered for updates. Default: 50. _n_periods (int): Number of periods to consider for the moving average. Default: 30.

Initialize an ECF competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 100.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating.

__init__(initial_rating: float = 100)

Initialize an ECF competitor.

Args:

initial_rating (float, optional): The initial rating of this competitor. Default: 100.

Raises:

InvalidRatingValueException: If the initial rating is below the minimum rating.

beat(competitor: BaseCompetitor) → None

Update ratings after this competitor has won against the given competitor.

This method updates the ratings of both this competitor and the opponent based on the match outcome where this competitor won.

Args:

competitor (BaseCompetitor): The opponent competitor that lost.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

property elo_conversion: float

Convert the ECF rating to an approximate Elo rating.

Returns:

float: The approximate Elo rating.

expected_score(competitor: BaseCompetitor) → float

Calculate the expected score (probability of winning) against another competitor.

Args:

competitor (BaseCompetitor): The opponent competitor to compare against.

Returns:

float: The probability of winning (between 0 and 1).

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

export_state() → Dict[str, Any]

Export the current state of this competitor for serialization.

Returns:

dict: A dictionary containing all necessary information to recreate

this competitor’s current state.

classmethod from_state(state: Dict[str, Any]) → T

Create a new competitor from a previously exported state.

Args:

state (dict): A dictionary containing the state of a competitor,

as returned by export_state().

Returns:

ECFCompetitor: A new competitor with the same state as the exported one.

Raises:

InvalidParameterException: If any parameter in the state is invalid.

property rating: float

Get the current rating of this competitor.

The rating is the average of all scores in the deque.

Returns:

float: The current rating.

reset() → None

Reset this competitor to its initial state.

This method resets the competitor’s scores deque to contain only the initial rating.

tied(competitor: BaseCompetitor) → None

Update ratings after this competitor has tied with the given competitor.

This method updates the ratings of both this competitor and the opponent based on a drawn match outcome.

Args:

competitor (BaseCompetitor): The opponent competitor that tied.

Raises:

MissMatchedCompetitorTypesException: If the competitor types don’t match.

property transformed_elo_rating: float

Get the transformed Elo rating of this competitor.

The transformed rating is used in the expected score calculation.

Returns:

float: The transformed Elo rating.

Blended Competitor