Rank Module

Rank calculation for divisors on chip-firing graphs.

This module provides functionality to calculate the rank of divisors on chip-firing graphs, which is an important invariant in the theory of divisors on graphs. The rank measures how much freedom you have to move chips around while keeping the divisor effective.

The implementation uses the Efficient Winnability Detection (EWD) algorithm as a building block and provides both standard and optimized calculation modes.

class chipfiring.CFRank.CFRank

Bases: object

A class that holds the result of a rank calculation.

This class stores both the computed rank value of a divisor and the detailed logs of the calculation process. It is typically created and returned by the rank() function rather than being instantiated directly.

Variables:

• logs (List[str]) – Sequential log messages from the rank calculation process.

• rank (int) – The computed rank value, accessible as a property.

Example

>>> result = rank(divisor)
>>> print(f"The rank is: {result.rank}")
>>> for log in result.logs:
...     print(log)

__init__()

Internal constructor to initialize the CFRank object.

log(message: str)

Internal method to add a log message to the logs list.

property rank: int

Retrieve the calculated rank value.

Returns:

The rank value of the divisor.

Return type:

int

Raises:

ValueError – If no rank calculation has been performed yet.

_calculate_rank(divisor: CFDivisor, optimized: bool = False) → CFRank

Internal method to calculate the rank of a given divisor.

get_log_summary() → str

Get a complete log of the rank calculation process.

Returns:

A string containing all log messages from the calculation.

If no logs are available, returns “No calculation logs available.”

Return type:

str

Example

>>> result = rank(divisor)
>>> print(result.get_log_summary())

chipfiring.CFRank.rank(divisor: CFDivisor, optimized: bool = False) → CFRank

Calculate the rank of a given divisor.

In divisor theory, the rank r(D) of a divisor D is defined as the largest integer r such that D-E is equivalent to an effective divisor for all effective divisors E of degree r. If D is not equivalent to an effective divisor, then r(D) = -1.

The rank is computed as follows:

1. If EWD(divisor) is not winnable, return -1.

2. Starting with k = 1, consider all effective divisors E of degree k.

3. For each such divisor E, check if D-E is winnable using the EWD algorithm. These checks are performed in parallel for a given k.

4. If all checks for the current k are winnable, increment k and repeat step 2.

5. Otherwise (if any check for D-E returns not winnable), the rank is k-1.

Parameters:

• divisor – The CFDivisor object for which to calculate the rank.

• optimized – Whether to use optimized rank calculation. (default: False) If True, theoretical shortcuts like Corollary 4.4.3 from Dhyey Mavani’s thesis will be used when applicable to speed up calculations. The log will indicate when these optimizations are used.

Returns:

An object with the calculated rank accessible via .rank property

and calculation logs accessible via .logs attribute. One can also access the full log summary using .get_log_summary().

Return type:

CFRank

Example

>>> result = rank(divisor)
>>> print(f"Rank: {result.rank}")
>>> print(result.get_log_summary())

chipfiring.CFRank.r(divisor: CFDivisor, optimized: bool = False) → int

Calculate the rank of the given divisor, as in the funciton “rank.” This funcion returns only the rank itself, as an integer, without the logs. Implemented as a wrapper around “rank.”

Parameters:

• divisor – The CFDivisor object for which to calculate the rank.

• optimized – Whether to use optimized rank calculation. (default: False) If True, theoretical shortcuts like Corollary 4.4.3 from Dhyey Mavani’s thesis will be used when applicable to speed up calculations. The log will indicate when these optimizations are used.

Returns:

The rank of the divisor.

Return type:

int

Example

>>> result = r(divisor)
>>> print(f"Rank: {result}")