Competitors

Elo Competitor

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

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.

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_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.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current 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.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

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

Glicko Competitor

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

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.

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_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.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

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.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

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

DWZ Competitor

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

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.

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_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.

property rating: float

Get the current rating of this competitor.

Returns:

float: The current rating.

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.

to_json() → str

Convert this competitor’s state to a JSON string.

Returns:

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

ECF Competitor

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

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.

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 (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_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.

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.

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.

BlendedCompetitor

class elote.competitors.ensemble.BlendedCompetitor(competitors: List[Dict[str, Any]], blend_mode: str = 'mean')

Ensemble rating system that combines multiple rating algorithms.

The BlendedCompetitor allows combining multiple rating systems to leverage their individual strengths while mitigating their weaknesses. By aggregating predictions from different rating algorithms, it can potentially provide more robust and accurate predictions than any single rating system alone.

Supported blend modes:

• “mean”: Average the expected scores from all sub-competitors.

Initialize a BlendedCompetitor with multiple rating systems.

Args:

competitors (List[Dict[str, Any]]): List of dictionaries specifying the

sub-competitors to use. Each dictionary should have a “type” key with the name of the competitor class and a “competitor_kwargs” key with the arguments to pass to the constructor.

blend_mode (str, optional): The method to use for blending the ratings.

Currently only “mean” is supported. Default: “mean”.

Raises:

InvalidParameterException: If the blend_mode is not supported or if any

competitor specification is invalid.

beat(competitor: BaseCompetitor) → None

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

This method updates the ratings of all sub-competitors based on the match outcome.

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 (probability of winning) against another competitor.

For a BlendedCompetitor, the expected score is calculated by blending the expected scores from all sub-competitors according to the blend_mode.

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. NotImplementedError: If the blend_mode is not supported.

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_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.

property rating: float

Get the combined rating of this competitor.

For a BlendedCompetitor, the rating is the sum of all sub-competitor ratings. This is a simple way to represent the overall strength, but the expected_score method provides a more accurate way to compare competitors.

Returns:

float: The combined rating.

tied(competitor: BaseCompetitor) → None

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

This method updates the ratings of all sub-competitors based on the 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.

Serialization

All competitor types in Elote support a standardized serialization format that allows for saving and loading competitor states. The serialization format includes the following fields:

• type: The class name of the competitor

• version: The version of the serialization format

• created_at: 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

• class_vars: Class variables for backward compatibility

To serialize a competitor to JSON:

# Create a competitor
competitor = EloCompetitor(initial_rating=1500)

# Serialize to JSON
json_str = competitor.to_json()

To deserialize a competitor from JSON:

# Deserialize from JSON
competitor = EloCompetitor.from_json(json_str)

For backward compatibility, the serialized format also includes flattened parameters and state variables at the top level of the dictionary.