ludics 0.1.0__tar.gz

ludics-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Harry Foster, Vince Knight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

ludics-0.1.0/PKG-INFO

@@ -0,0 +1,70 @@
+Metadata-Version: 2.3
+Name: ludics
+Version: 0.1.0
+Summary: A python library for the study of heterogenous population dynamics
+License: MIT License
+         
+         Copyright (c) 2025 Harry Foster, Vince Knight
+         
+         Permission is hereby granted, free of charge, to any person obtaining a copy
+         of this software and associated documentation files (the "Software"), to deal
+         in the Software without restriction, including without limitation the rights
+         to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+         copies of the Software, and to permit persons to whom the Software is
+         furnished to do so, subject to the following conditions:
+         
+         The above copyright notice and this permission notice shall be included in all
+         copies or substantial portions of the Software.
+         
+         THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+         IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+         FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+         AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+         LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+         OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+         SOFTWARE.
+Requires-Dist: black>=25.9.0
+Requires-Dist: numpy>=2.3.3
+Requires-Dist: sympy>=1.14.0
+Requires-Dist: scipy>=1.16.3
+Requires-Dist: pandas>=3.0.0
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+
+# Ludics
+
+A library for the study of heterogeneous population dynamics.
+
+## Usage
+
+To run tests:
+
+For source code:
+
+```
+$ uv run pytest tests
+```
+
+For docs:
+
+```
+$ uv run pytest --doctest-glob="*.md" docs
+```
+
+To run benchmarks:
+
+```
+$ uv run pytest benchmarks
+```
+
+To run ruff:
+
+```
+$ uv run ruff format
+```
+
+To check ruff:
+
+```
+$ uv run ruff check
+```

ludics-0.1.0/README.md

@@ -0,0 +1,37 @@
+# Ludics
+
+A library for the study of heterogeneous population dynamics.
+
+## Usage
+
+To run tests:
+
+For source code:
+
+```
+$ uv run pytest tests
+```
+
+For docs:
+
+```
+$ uv run pytest --doctest-glob="*.md" docs
+```
+
+To run benchmarks:
+
+```
+$ uv run pytest benchmarks
+```
+
+To run ruff:
+
+```
+$ uv run ruff format
+```
+
+To check ruff:
+
+```
+$ uv run ruff check
+```

ludics-0.1.0/pyproject.toml

@@ -0,0 +1,34 @@
+[project]
+name = "ludics"
+version = "0.1.0"
+description = "A python library for the study of heterogenous population dynamics"
+readme = "README.md"
+license = { file = "LICENSE" }
+requires-python = ">=3.13"
+dependencies = [
+    "black>=25.9.0",
+    "numpy>=2.3.3",
+    "sympy>=1.14.0",
+    "scipy>=1.16.3",
+    "pandas>=3.0.0",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-cov>=7.0.0",
+    "pytest-benchmark>=5.2.3",
+    "ruff>=0.9.0",
+    "ty>=0.0.1a1",
+]
+docs = [
+    "mkdocs>=1.6.0",
+    "pymdown-extensions>=10.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.7,<0.11.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+target-version = "py314"

ludics-0.1.0/src/ludics/__init__.py

@@ -0,0 +1,47 @@
+from ludics.main import (
+    get_state_space,
+    compute_moran_transition_probability,
+    fermi_imitation_function,
+    compute_fermi_transition_probability,
+    compute_imitation_introspection_transition_probability,
+    compute_introspection_transition_probability,
+    compute_aspiration_transition_probability,
+    apply_mutation_probability,
+    generate_transition_matrix,
+    get_absorbing_state_index,
+    get_absorbing_states,
+    get_absorption_probabilities,
+    extract_Q,
+    extract_R_numerical,
+    extract_R_symbolic,
+    compute_absorption_matrix,
+    calculate_absorption_matrix,
+    compute_steady_state,
+    calculate_steady_state,
+    get_neighbourhood_states,
+    simulate_markov_chain,
+)
+
+__all__ = [
+    "get_state_space",
+    "compute_moran_transition_probability",
+    "fermi_imitation_function",
+    "compute_fermi_transition_probability",
+    "compute_imitation_introspection_transition_probability",
+    "compute_introspection_transition_probability",
+    "compute_aspiration_transition_probability",
+    "apply_mutation_probability",
+    "generate_transition_matrix",
+    "get_absorbing_state_index",
+    "get_absorbing_states",
+    "get_absorption_probabilities",
+    "extract_Q",
+    "extract_R_numerical",
+    "extract_R_symbolic",
+    "compute_absorption_matrix",
+    "calculate_absorption_matrix",
+    "compute_steady_state",
+    "calculate_steady_state",
+    "get_neighbourhood_states",
+    "simulate_markov_chain",
+]

ludics-0.1.0/src/ludics/fitness_functions.py

@@ -0,0 +1,105 @@
+import numpy as np
+import sympy as sym
+
+
+def heterogeneous_contribution_pgg_fitness_function(
+    state, r, contribution_vector, **kwargs
+):
+    """Public goods fitness function where players contribute a different
+    amount.
+
+    Parameters
+    -----------
+
+    state: numpy.array, the ordered set of actions each player takes; 1 for
+    contributing, 0 for free-riding.
+
+    r: float, the parameter which the public goods is multiplied by
+
+    contribution_vector: numpy.array, the value which each player contributes
+
+    Returns
+    -------
+
+    numpy.array: an ordered vector of each player's fitness."""
+
+    total_goods = (
+        r
+        * sum(
+            action * contribution
+            for action, contribution in zip(state, contribution_vector)
+        )
+        / len(state)
+    )
+
+    payoff_vector = np.array(
+        [
+            total_goods - (action * contribution)
+            for action, contribution in zip(state, contribution_vector)
+        ]
+    )
+
+    return payoff_vector
+
+
+def homogeneous_pgg_fitness_function(state, alpha, r, **kwargs):
+    """
+    Public goods fitness function where all players contribute the same amount.
+    They therefore have a return of 1 + (selection_intensity * payoff), This
+    is the selection intensity $\epsilon$, which determines the effect of
+    payoff on a player's fitness.
+
+    Parameters
+    -----------
+    state: numpy.array, the ordered set of actions each player takes
+
+    alpha: float, each player's contribution
+
+    r: float, the parameter which the public goods is multiplied by
+
+    epsilon: float, the selection intensity determining the effect of payoff on
+    a player's fitness. Must satisfy $0 < \epsilon < \frac{N}{(N-r)\alpha}$ if r<N
+
+    Returns
+    -------
+    numpy.array: an ordered array of each player's fitness"""
+    homogeneous_contribution_vector = np.array([alpha for _ in enumerate(state)])
+    return heterogeneous_contribution_pgg_fitness_function(
+        state=state,
+        r=r,
+        contribution_vector=homogeneous_contribution_vector,
+        **kwargs,
+    )
+
+
+def general_four_state_fitness_function(state, **kwargs):
+    """
+    Returns a general fitness function for each player in a general 2 player population,
+    according to the rule
+    $f_i(x)$ is the fitness of player i in state x, indexed from 1.
+
+    In this case, the states correspond to:
+    $a=(0,0)$, $b=(0,1)$, $c=(1,0)$, $d=(1,1)$
+    This is the same state space as we have in the Population Dynamics section
+    of main.tex.
+
+    Parameters
+    -----------
+    state: numpy.array, the ordered set of actions each player takes
+
+    Returns
+    -------
+    numpy.array: an ordered array of each player's fitness"""
+
+    if (state == np.array([0, 0])).all():
+        state_symbol = sym.Symbol("a")
+    if (state == np.array([0, 1])).all():
+        state_symbol = sym.Symbol("b")
+    if (state == np.array([1, 0])).all():
+        state_symbol = sym.Symbol("c")
+    if (state == np.array([1, 1])).all():
+        state_symbol = sym.Symbol("d")
+
+    return np.array(
+        [sym.Function(f"f_{i + 1}")(state_symbol) for i, j in enumerate(state)]
+    )

ludics-0.1.0/src/ludics/main.py

@@ -0,0 +1,873 @@
+"""
+Code for the general heterogeneous Moran process
+
+This corresponds to the model described in `main.tex`
+
+Assume we have N ordered individuals of k types: $A_1$, ... $A_K$
+
+We have a state v \in S = [$v_1$, .... $v_n$] as the set of types of individuals in the population, so that $v_i$ is the type of individual i. |S| = $k^N$
+
+There is also a fitness function f: S -> $R^N$, giving us an array of the fitness of individuals
+"""
+
+import itertools
+import numpy as np
+import sympy as sym
+import scipy
+import collections
+
+
+def get_state_space(N, k):
+    """
+    Return state space for a given N and K
+
+    Parameters:
+    -----------
+    N: integer, number of individuals
+
+    k: integer, number of possible types
+
+    Returns:
+    --------
+    Array of possible states within the system, sorted based on the
+    total values of the rows, in order to ensure a consistent result
+    """
+    state_space = np.array(list(itertools.product(range(k), repeat=N)))
+
+    return state_space
+
+
+def compute_moran_transition_probability(
+    source, target, fitness_function, selection_intensity, **kwargs
+):
+    """
+    Given two states and a fitness function, returns the transition probability
+    when moving from the source state to the target state. Must move between
+    states with a Hamming distance of 1.
+
+    Returns 0 if Hamming distance > 1.
+    Returns None if Hamming distance = 0.
+
+
+    $\frac{\sum_{v_i = u_{i*}}{f(v_i)}}{\sum_{v_i}f(v_i)}$
+
+    Parameters
+    ----------
+    source: numpy.array, the starting state
+
+    target: numpy.array, what the source transitions to
+
+    fitness_function: func, The fitness function which maps a state to a
+    numpy.array where each entry represents the fitness of the given individual
+
+    selection_intensity: float, the selection intensity $\epsilon$ of the
+    system
+
+    Returns
+    ---------
+    Float: the transition pobability from source to target
+    """
+    different_indices = np.where(source != target)
+    if len(different_indices[0]) > 1:
+        return 0
+    if len(different_indices[0]) == 0:
+        return None
+    fitness = 1 + (selection_intensity * fitness_function(source, **kwargs))
+    denominator = fitness.sum() * len(source)
+    numerator = fitness[source == target[different_indices]].sum()
+    return numerator / denominator
+
+
+def fermi_imitation_function(delta, choice_intensity=0.5, **kwargs):
+    """
+    Given the fitness of the focal individual who changes action type, and the
+    target individual who is being copied, as well as the choice intensity,
+    returns $\phi(a_i, a_j) = \frac{1}{1 + \exp({\frac{f(a_{i}) - f(a_{j})
+    }{\beta}})}$
+
+    choice intensity is set to 0.5 by default, as is common according to:
+
+    Xiaojian Maa, Ji Quana, Xianjia Wang (2021): Effect of reputation-based
+    heterogeneous investment on cooperation in spatial public goods games
+
+
+    Parameters
+    -----------
+
+    delta: float or sym.Symbol, the difference between the current fitness of
+    an individual and the considered fitness.
+
+    choice_intensity: float or sym.Symbol, a parameter which determines the
+    effect the difference in fitness has on the transition probability. As
+    choice_intensity goes to infinity, the probability of transitioning goes
+    to $\frac{1}{2}$
+    """
+    return 1 / (1 + sym.E ** (choice_intensity * (delta)))
+
+
+def compute_fermi_transition_probability(
+    source, target, fitness_function, choice_intensity, **kwargs
+):
+    """
+    Given two states, a fitness function, and a choice intensity, returns
+    the transition probability when moving from the source state to the target
+    state. Must move between states with a Hamming distance of 1.
+
+    Returns 0 if Hamming distance > 1.
+    Returns None if Hamming distance = 0.
+
+    The following equation is the subject of this function:
+
+    $\sum_{a_j=b_{i^*}}^N\frac{1}{N(N-1)}\phi(f_i(a) - f(a_j))$
+
+    where $\phi(f_i(a) - f(a_j)) = \frac{1}{1 + \exp({\frac{f(a_{i}) - f(a_{j})
+    }{\beta}})}$
+
+    Parameters
+    ----------
+    source: numpy.array, the starting state
+
+    target: numpy.array, what the source transitions to
+
+    fitness_function: func, The fitness function which maps a state to a
+    numpy.array
+
+    choice_intensity: float or sympy.Symbol: the choice intensity of the
+    function. The lower the value, the higher the probability that a player
+    will choose the higher fitness strategy in $\phi$
+
+    Returns
+    ---------
+    Float: the transition pobability from source to target"""
+
+    different_indices = np.where(source != target)
+    if len(different_indices[0]) > 1:
+        return 0
+    if len(different_indices[0]) == 0:
+        return None
+    fitness = fitness_function(source, **kwargs)
+
+    changes = [
+        fermi_imitation_function(
+            delta=fitness[different_indices] - fitness[i],
+            choice_intensity=choice_intensity,
+            **kwargs,
+        )
+        for i in np.where(source == target[different_indices])
+    ]
+
+    scalar = 1 / (len(source) * (len(source) - 1))
+    return (scalar * np.array(changes)).sum()
+
+
+def compute_imitation_introspection_transition_probability(
+    source, target, fitness_function, choice_intensity, selection_intensity, **kwargs
+):
+    """
+    Given two states, a fitness function, and a choice intensity, returns
+    the transition probability when moving from the source state to the target
+    state in introspective imitation dynamics. Must move between states with a
+    Hamming distance of 1.
+
+    Returns 0 if Hamming distance > 1.
+    Returns None if Hamming distance = 0.
+
+    The following equation is the subject of this function:
+
+    $\frac{1}{N}\frac{\sum_{a_{j} = b_{I(\textbf{a}, \textbf{b})}}f_j(\textbf{a})}{\sum_{k}f_k(\textbf{a})}\phi(\Delta(f_{I(\textbf{a,b})}))$
+
+    Parameters
+    ----------
+    source: numpy.array, the starting state
+
+    target: numpy.array, what the source transitions to
+
+    fitness_function: func, The fitness function which maps a state to a
+    numpy.array
+
+    choice_intensity: float or sympy.Symbol: the choice intensity of the
+    function. The lower the value, the higher the probability that a player
+    will choose the higher fitness strategy in $\phi$
+
+    selection_intensity: float or sympy.Symbol: the selection intensity
+    $\epsilon$ of the system
+
+    Returns
+    ---------
+    Float: the transition pobability from source to target"""
+
+    different_indices = np.where(source != target)
+    if len(different_indices[0]) > 1:
+        return 0
+    if len(different_indices[0]) == 0:
+        return None
+
+    fitness = fitness_function(source, **kwargs)
+    fitness_before = fitness[different_indices][0]
+    fitness_after = fitness_function(target, **kwargs)[different_indices][0]
+
+    selection_fitness = 1 + (selection_intensity * fitness)
+    selection_denominator = selection_fitness.sum() * len(source)
+    selection_numerator = selection_fitness[source == target[different_indices]].sum()
+    selection_probability = selection_numerator / selection_denominator
+
+    delta = fitness_before - fitness_after
+
+    return selection_probability * fermi_imitation_function(
+        delta=delta, choice_intensity=choice_intensity
+    )
+
+
+def compute_introspection_transition_probability(
+    source, target, fitness_function, choice_intensity, number_of_strategies, **kwargs
+):
+    """
+    Given two states, a fitness function, and a choice intensity, returns
+    the transition probability when moving from the source state to the target
+    state under introspective imitation dynamics. Must move between states with
+    Hamming distance of 1.
+
+    Returns 0 if Hamming distance > 1.
+    Returns None if Hamming distance = 0.
+
+    The following equation is the subject of this function:
+    $\frac{1}{N(m_j - 1)}\phi(f_i(a) - f_i(b))$
+
+    Parameters
+    ----------
+    source: numpy.array, the starting state
+
+    target: numpy.array, what the source transitions to
+
+    fitness_function: func, The fitness function which maps a state to a
+    numpy.array
+
+    choice_intensity: float or sympy.Symbol: the choice intensity of the
+    function. The lower the value, the higher the probability that a player
+    will choose the higher fitness strategy in $\phi$
+
+    number_of_strategies: the number of strategies available to each player in
+    the population. What we call "k" in the get_state_space function
+
+    Returns
+    ---------
+    Float: the transition pobability from source to target"""
+
+    different_indices = np.where(source != target)
+    if len(different_indices[0]) > 1:
+        return 0
+    if len(different_indices[0]) == 0:
+        return None
+
+    fitness = fitness_function(source, **kwargs)
+    fitness_before = fitness[different_indices][0]
+    fitness_after = fitness_function(target, **kwargs)[different_indices][0]
+
+    selection_probability = 1 / (len(source) * ((number_of_strategies) - 1))
+
+    delta = fitness_before - fitness_after
+
+    return selection_probability * fermi_imitation_function(
+        delta=delta, choice_intensity=choice_intensity
+    )
+
+
+def compute_aspiration_transition_probability(
+    source, target, fitness_function, choice_intensity, aspiration_vector, **kwargs
+):
+    """
+    Given two states, a fitness function, and a choice intensity, returns
+    the transition probability when moving from the source state to the target
+    state under aspiration dynamics. This dynamic takes the aspiration of a
+    given player and they will change action type with a probability
+    proportional to the difference between their current payoff, and their
+    aspired payoff.
+
+    Returns 0 if Hamming distance > 1.
+    Returns None if Hamming distance = 0.
+
+    Parameters
+    ----------
+    source: numpy.array, the starting state
+
+    target: numpy.array, what the source transitions to
+
+    fitness_function: func, The fitness function which maps a state to a
+    numpy.array
+
+    choice_intensity: float or sympy.Symbol: the choice intensity of the
+    function. The lower the value, the higher the probability that a player
+    will choose the higher fitness strategy in $\phi$
+
+    aspiration_vector: numpy.array: the aspiration of each player in a state.
+
+    returns
+    ---------
+    float: the transition pobability from source to target
+    """
+
+    if len(np.unique(source)) > 2:
+        raise ValueError("Aspiration Dynamics only supports 2 action types")
+    if len(np.unique(target)) > 2:
+        raise ValueError("Aspiration Dynamics only supports 2 action types")
+
+    different_indices = np.where(source != target)
+    if len(different_indices[0]) > 1:
+        return 0
+    if len(different_indices[0]) == 0:
+        return None
+
+    fitness = fitness_function(source, **kwargs)
+    fitness_before = fitness[different_indices][0]
+
+    selection_probability = 1 / (len(source))
+
+    delta = fitness_before - aspiration_vector[different_indices][0]
+
+    return selection_probability * fermi_imitation_function(
+        delta=delta, choice_intensity=choice_intensity
+    )
+
+
+def apply_mutation_probability(
+    source, target, individual_to_action_mutation_probability, transition_probability
+):
+    """
+    Given two states and the probability of transitioning between them without
+    mutation, returns the probability of transitioning between them under
+    mutation.
+
+    Parameters
+    -----------
+    source: numpy.array, the starting state
+
+    target: numpy.array, the state which the source transitions to
+
+    individual_to_action_mutation_probability: numpy.array or None: the probability of each player
+    mutating to each action type. Row 0 corresponds to player 0, column 0
+    corresponds to action type 0. Action types must be written in the form of
+    0,1,2,etc.
+
+    transition_probability: float - the probability of transitioning between
+    source and target without mutation.
+
+    returns
+    --------
+    float: the transition probability between source and target under mutation
+
+    """
+
+    different_indices = np.where(source != target)[0]
+
+    if len(different_indices) == 1:
+        index_of_difference = different_indices[0]
+        new_type = target[index_of_difference]
+
+        return transition_probability * (
+            1
+            - np.sum(individual_to_action_mutation_probability, axis=1)[
+                different_indices
+            ].item()
+        ) + (
+            individual_to_action_mutation_probability[
+                different_indices, new_type
+            ].item()
+            / len(source)
+        )
+    return transition_probability
+
+
+def generate_transition_matrix(
+    state_space,
+    fitness_function,
+    compute_transition_probability,
+    individual_to_action_mutation_probability=None,
+    **kwargs,
+):
+    """
+    Given a state space and a fitness function, returns the transition matrix
+
+    for the heterogeneous Moran process.
+
+    Parameters
+    ----------
+    state_space: numpy.array, the state space for the transition matrix
+
+    fitness_function: function, should return a size N numpy.array when passed
+    a state
+
+    compute_transition_probability: function, takes a source state, a target
+    state, and a fitness function, and returns the probability of transitioning
+    from the source state to the target state
+
+    individual_to_action_mutation_probability: numpy.array or None: the probability of each player
+    mutating to each action type. Row 0 corresponds to player 0, column 0
+    corresponds to action type 0. Action types must be written in the form of
+    0,1,2,etc. If None, this will assume a vector of 0 probabilities.
+
+    Returns
+    ----------
+    numpy.array: the transition matrix
+    """
+    N = len(state_space)
+    transition_matrix = np.zeros(shape=(N, N))
+    if individual_to_action_mutation_probability is None:
+        individual_to_action_mutation_probability = np.zeros(shape=(N, N))
+    for row_index, source in enumerate(state_space):
+        for col_index, target in enumerate(state_space):
+            if row_index != col_index:
+                try:
+                    transition_matrix[row_index, col_index] = (
+                        apply_mutation_probability(
+                            source=source,
+                            target=target,
+                            individual_to_action_mutation_probability=individual_to_action_mutation_probability,
+                            transition_probability=(
+                                compute_transition_probability(
+                                    source=source,
+                                    target=target,
+                                    fitness_function=fitness_function,
+                                    **kwargs,
+                                )
+                            ),
+                        )
+                    )
+                except TypeError:
+                    transition_matrix = transition_matrix.astype(object)
+
+                    transition_matrix[row_index, col_index] = (
+                        apply_mutation_probability(
+                            source=source,
+                            target=target,
+                            individual_to_action_mutation_probability=individual_to_action_mutation_probability,
+                            transition_probability=(
+                                compute_transition_probability(
+                                    source=source,
+                                    target=target,
+                                    fitness_function=fitness_function,
+                                    **kwargs,
+                                )
+                            ),
+                        )
+                    )
+
+    np.fill_diagonal(transition_matrix, 1 - transition_matrix.sum(axis=1))
+    return transition_matrix
+
+
+def get_absorbing_state_index(state_space):
+    """Given a state space, returns the indexes of the absorbing states
+    (i.e, states with only one value repeated).
+
+    Parameters
+    -------------
+    state_space: numpy.array, an array of states
+
+    Returns
+    --------------
+    numpy.array of index values for the absorbing states"""
+
+    absorbing_index = np.where(np.all(state_space == state_space[:, [0]], axis=1))[0]
+
+    return absorbing_index if len(absorbing_index) >= 1 else None
+
+
+def get_absorbing_states(state_space):
+    """Given a state space, returns the absorbing states
+
+    Parameters
+    -----------
+    state_space: numpy.array, a state space
+
+    Returns
+    ---------
+    numpy.array, a list of absorbing states, in order"""
+
+    index_array = get_absorbing_state_index(state_space=state_space)
+
+    return (
+        None
+        if index_array is None
+        else np.array([state_space[index] for index in index_array])
+    )
+
+
+def get_absorption_probabilities(
+    transition_matrix, state_space, exponent_coefficient=50
+):
+    """Given a transition matrix and a corresponding state space
+
+    generate the absorption probabilities. This does not yet support a
+
+    symbolic transition matrix input
+
+    Parameters
+    -------------
+    state_space: numpy.array, a state space
+
+    transition matrix: numpy.array, a matrix of transition probabilities corresponding to the state space
+
+    Returns
+    -------------
+    Dictionary of values: tuple([starting state]): [[absorbing state 1, absorption probability 1], [absorbing state 2, absorption probability 2]]
+    """
+
+    absorption_index = get_absorbing_state_index(state_space=state_space)
+
+    absorbing_transition_matrix = np.linalg.matrix_power(
+        transition_matrix, exponent_coefficient
+    )
+
+    # TODO this method of getting absorption probabilities will change, but we need to set up benchmarks first
+
+    absorbing_collums = np.array(
+        [absorbing_transition_matrix[:, index] for index in absorption_index]
+    )
+
+    combined_values = np.array(
+        [
+            np.ravel(np.column_stack((absorption_index, absorbing_collums[:, k])))
+            for k, y in enumerate(absorbing_collums.transpose())
+        ]
+    )
+
+    return {
+        state_index: combined_values[state_index]
+        for state_index, state in enumerate(state_space)
+    }
+
+
+def extract_Q(transition_matrix):
+    """
+    For a transition matrix, compute the corresponding matrix Q
+
+    Parameters
+    ----------
+    transition_matrix: numpy.array, the transition matrix
+
+    Returns
+    -------
+    np.array, the matrix Q
+    """
+    indices_without_1_in_diagonal = np.where(transition_matrix.diagonal() != 1)[0]
+    Q = transition_matrix[
+        indices_without_1_in_diagonal.reshape(-1, 1), indices_without_1_in_diagonal
+    ]
+    return Q
+
+
+def extract_R_numerical(transition_matrix):
+    """
+    For a transition matrix, compute the corresponding matrix R
+
+    Parameters
+    ----------
+    transition_matrix: numpy.array, the transition matrix
+
+    Returns
+    ----------
+    np.array, the matrix R
+    """
+
+    # TODO merge with symbolic version and Q as function: obtain canonical form
+
+    absorbing_states = np.isclose(np.diag(transition_matrix), 1.0)
+    non_absorbing_states = ~absorbing_states
+    R = transition_matrix[np.ix_(non_absorbing_states, absorbing_states)]
+
+    return R
+
+
+def extract_R_symbolic(transition_matrix):
+
+    n = transition_matrix.shape[0]
+
+    absorbing_states = np.array(
+        [sym.simplify(transition_matrix[i, i] - 1) in (0, float(0)) for i in range(n)],
+        dtype=bool,
+    )
+
+    non_absorbing_states = ~absorbing_states
+
+    R = transition_matrix[np.ix_(non_absorbing_states, absorbing_states)]
+
+    return R
+
+
+def compute_absorption_matrix(transition_matrix):
+    """
+    Given a transition matrix, NOT allowing for symbolic values,
+
+    returns the absorption matrix
+
+
+    Parameters:
+    ------------
+
+    transition_matrix: numpy.array: a transition matrix with no symbolic values
+
+
+    Returns:
+    -----------
+
+    numpy.array: the probability of transitioning from
+
+    each transitive state (row) to each absorbing state(column).
+    """
+
+    Q = extract_Q(transition_matrix=transition_matrix)
+
+    R = extract_R_numerical(transition_matrix=transition_matrix)
+
+    B = scipy.linalg.solve(np.eye(Q.shape[0]) - Q, R)
+
+    return B
+
+
+def calculate_absorption_matrix(transition_matrix):
+    """
+    Given a transition matrix, allowing for symbolic values,
+
+    returns the absorption matrix
+
+
+    Parameters:
+    ------------
+
+    transition_matrix: numpy.array: a transition matrix allowing for symbolic
+
+    values, that has at least 1 symbolic value.
+
+    symbolic: boolean, states whether symbolic values appear in the matrix
+
+
+    Returns:
+    -----------
+
+    sympy.Matrix: the probability of transitioning from
+
+    each transitive state (row) to each absorbing state(column).
+    """
+
+    Q = extract_Q(transition_matrix=transition_matrix)
+
+    R = extract_R_symbolic(transition_matrix=transition_matrix)
+
+    Q_symbolic = sym.Matrix(Q)
+    R_symbolic = sym.Matrix(R)
+
+    identity = sym.eye(Q_symbolic.shape[0])
+    B = (identity - Q_symbolic) ** -1 * R_symbolic
+
+    return sym.Matrix(B)
+
+def compute_steady_state(transition_matrix, tolerance=10**-6, initial_dist=None):
+    """
+    Returns the steady state vector of a given transition matrix that is
+    entirely numeric.
+
+    Parameters
+    ----------
+    transition_matrix - numpy.array, a transition matrix.
+
+    tolerance - float. The maximum change when taking next_pi = pi @
+    transition_matrix
+
+    initial_dist - numpy.array: the starting state distribution.
+
+    Returns
+    ----------
+    numpy.array - steady state of transition_matrix."""
+    N, _ = transition_matrix.shape
+    if initial_dist is None:
+        pi = np.ones(N) / N
+    else:
+        pi = initial_dist
+    while np.max(np.abs((next_pi := pi @ transition_matrix) - pi)) > tolerance:
+        pi = next_pi
+    return pi
+
+
+def calculate_steady_state(transition_matrix):
+    """
+    Returns the steady state vectors of a given transition matrix. The steady
+    state is calculated as the left eigenvector of the transition matrix of a
+    Markov chain. This is achieved by noticing that this is equivalent to
+    solving $xA = x$ is equivalent to $(A^T - I)x^T = 0$. Thus, we find the
+    right-nullspace of $(A^T - I)$.
+
+    Parameters
+    ----------
+    transition_matrix - numpy.array or sympy.Matrix, a transition matrix.
+
+    Returns
+    ----------
+    numpy.array - steady state of transition_matrix. For the symbolic case,
+    this will always be simplified.
+    """
+    transition_matrix = sym.Matrix(transition_matrix)
+
+    nullspace = (transition_matrix.T - sym.eye(transition_matrix.rows)).nullspace()
+
+    try:
+        one_eigenvector = nullspace[0]
+    except Exception:
+        raise ValueError("No eigenvector found")
+
+    return np.array(sym.simplify(one_eigenvector / sum(one_eigenvector)).T)[0]
+
+
+def get_neighbourhood_states(state, number_of_strategies):
+    """
+    Given a state, returns a numpy.array of neighbouring states. That is, the
+    set of states which differ at 1 position from the current state.
+
+    Parameters:
+    ------------
+
+    state: numpy.array - the state to be considered
+
+    number_of_strategies: int - the number of actions available to each player
+
+    extrinsic: bool - whether or not the players can only change to a type
+    within the state.
+
+    returns:
+    ---------
+    numpy.array: the set of states in the neighbourhood of the passed state"""
+
+    action_set = np.arange(number_of_strategies)
+
+    neighbours = []
+
+    for player, player_type in enumerate(state):
+        for action in action_set:
+            if player_type != action:
+                adjacent_state = state.copy()
+                adjacent_state[player] = action
+                neighbours.append(adjacent_state)
+
+    return np.array(neighbours)
+
+
+def simulate_markov_chain(
+    initial_state,
+    number_of_strategies,
+    fitness_function,
+    compute_transition_probability,
+    seed,
+    individual_to_action_mutation_probability=None,
+    warmup=0,
+    iterations=10000,
+    **kwargs,
+):
+    """
+    Given an initial state, simulates a markov chain under a fitness function
+    and a population dynamic. Moves between neighbouring states and returns the
+    sets in the order they were visited in, and the number of times each state
+    was visited.
+
+    Parameters
+    -----------
+    initial_state: numpy.array - the state that our markov chain is in at $t=0$
+
+    number_of_strategies: int - the number of actions available to each player
+
+    fitness_function: func - takes a state and returns the fitness of each
+    individual
+
+    compute_transition_probability: func - takes two states and returns the
+    probability of transitioning from one state to another.
+
+    seed: int - the seed for the random process.
+
+    individual_to_action_mutation_probability: numpy.array - an N x (number of
+    strategies) array where $\mu_{ik}$ gives the probability of player $i$
+    mutating to type $k$. By default, set to None, which gives an array of all
+    zeros.
+
+    warmup: int - the number of iterations before we begin tracking the
+    distribution of steps
+
+    iterations: int - the number of iterations in the simulation. By default,
+    this is set to 10000
+
+    returns
+    --------
+    tuple - (the states in the order visited, the count of how often each state
+    was visited)"""
+
+    np.random.seed(seed)
+
+    if individual_to_action_mutation_probability is None:
+        individual_to_action_mutation_probability = np.zeros(
+            shape=(len(initial_state), number_of_strategies)
+        )
+
+    states_over_time = []
+    if warmup == 0:
+        states_over_time.append(tuple(initial_state))
+
+    current_state = initial_state
+
+    state_to_neighourhood_and_transition_probabilities = {}
+
+    for time_step in range(iterations - 1):
+        current_state_key = tuple(current_state.tolist())
+        try:
+            neighbourhood, transition_probabilities = (
+                state_to_neighourhood_and_transition_probabilities[current_state_key]
+            )
+
+        except KeyError:
+            neighbourhood = list(
+                get_neighbourhood_states(
+                    state=current_state, number_of_strategies=number_of_strategies
+                )
+            )
+
+            kwargs_with_strategies = {
+                **kwargs,
+                "number_of_strategies": number_of_strategies,
+            }
+
+            transition_probabilities = np.array(
+                [
+                    apply_mutation_probability(
+                        source=current_state,
+                        target=next_state,
+                        transition_probability=compute_transition_probability(
+                            source=current_state,
+                            target=next_state,
+                            fitness_function=fitness_function,
+                            **kwargs_with_strategies,
+                        ),
+                        individual_to_action_mutation_probability=individual_to_action_mutation_probability,
+                    )
+                    for next_state in neighbourhood
+                ],
+                dtype=float,
+            )
+
+            neighbourhood.append(current_state)
+            transition_probabilities = np.append(
+                transition_probabilities, 1 - transition_probabilities.sum()
+            )
+
+            state_to_neighourhood_and_transition_probabilities[current_state_key] = (
+                neighbourhood,
+                transition_probabilities,
+            )
+
+        next_state_index = np.random.choice(
+            len(neighbourhood), p=transition_probabilities
+        )
+
+        current_state = neighbourhood[next_state_index]
+
+        if time_step >= warmup - 1:
+            states_over_time.append(tuple(current_state.tolist()))
+
+    state_distribution = collections.Counter(states_over_time)
+
+    return (states_over_time, state_distribution)