.. gramag documentation master file, created by
   sphinx-quickstart on Mon Jun 19 15:02:05 2023.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

gramag --- Python Docs
=======================

Theory
-------

We use the notation introduced in Chapter 2 of `Hepworth and Willerton <https://arxiv.org/abs/1505.04125>`_ to denote the magnitude chain groups :math:`\mathrm{MC}_{k, l}` and magnitude homology groups :math:`\mathrm{MH}_{k, l}`.
We note that for each :math:`l`, the magnitude chain complex splits as a direct sum of chain complexes

.. math::
   \mathrm{MC}_{\ast, l} = \bigoplus_{(s, t) \in V\times V} \mathrm{MC}_{\ast,l}^{(s, t)}

where :math:`\mathrm{MC}_{k, l}^{(s, t)}` is the subgroup of :math:`\mathrm{MC}_{k, l}` freely generated by tuples :math:`(x_0, \dots, x_k)` satisfying

* :math:`x_0 \neq x_1 \neq \dots \neq x_k`,
* :math:`\ell(x_0, \dots, x_k) = l`,
* :math:`x_0=s` and :math:`x_k=t`.

It is easy to check that the boundary operators respects this decomposition, mapping :math:`\partial: \mathrm{MC}_{k, l}^{(s, t)} \to \mathrm{MC}_{k-1, l}^{(s, t)}` and hence the chain complex splits as described above.
Moreover, given an arbitrary subset :math:`\mathcal{P}\subseteq V\times V`, we introduce the notation

.. math::
   \mathrm{MC}_{\ast, l}^{\mathcal{P}} = \bigoplus_{(s, t) \in \mathcal{P}} \mathrm{MC}_{\ast,l}^{(s, t)}.

Since the chain complex splits, the magnitude homology also splits and hence we introduce the notation

.. math::
   \mathrm{MH}_{k, l}^{(s, t)} := H_k( \mathrm{MC}_{\ast, l}^{(s, t)} )

and

.. math::
   \mathrm{MH}_{k, l}^{\mathcal{P}} := H_k( \mathrm{MC}_{\ast, l}^{\mathcal{P}} ) = \bigoplus_{(s, t)\in\mathcal{P}} \mathrm{MH}_{k, l}^{(s, t)} 

where :math:`H_k` is the homology functor in degree `k`.

Python API
---------------

.. automodule:: gramag
   :members:
   :undoc-members:

   .. literalinclude:: examples/simple.py
      :language: python

   .. code-block::
   
      Rank of MC:
      ╭─────┬─────────────────────╮
      │ k=  │ 0  1  2  3  4  5  6 │
      ├─────┼─────────────────────┤
      │ l=0 │ 7                   │
      │ l=1 │ .  8                │
      │ l=2 │ .  4  5             │
      │ l=3 │ .  2  4  2          │
      │ l=4 │ .  .  3  3  1       │
      │ l=5 │ .  .  .  .  .  .    │
      │ l=6 │ .  .  .  .  .  .  . │
      ╰─────┴─────────────────────╯
      Rank of MH:
      ╭─────┬─────────────────────╮
      │ k=  │ 0  1  2  3  4  5  6 │
      ├─────┼─────────────────────┤
      │ l=0 │ 7                   │
      │ l=1 │ .  8                │
      │ l=2 │ .  .  1             │
      │ l=3 │ .  .  .  .          │
      │ l=4 │ .  .  1  .  .       │
      │ l=5 │ .  .  .  .  .  .    │
      │ l=6 │ .  .  .  .  .  .  . │
      ╰─────┴─────────────────────╯
      Rank of MH^{(0, 6)}:
      ╭─────┬─────────────────────╮
      │ k=  │ 0  1  2  3  4  5  6 │
      ├─────┼─────────────────────┤
      │ l=0 │ .                   │
      │ l=1 │ .  .                │
      │ l=2 │ .  .  1             │
      │ l=3 │ .  .  .  .          │
      │ l=4 │ .  .  1  .  .       │
      │ l=5 │ .  .  .  .  .  .    │
      │ l=6 │ .  .  .  .  .  .  . │
      ╰─────┴─────────────────────╯
      Representatives for MH_{2, 4}:
      [[[0, 5, 6]]

Doctests
---------------

.. doctest::

   >>> from gramag import MagGraph, format_rank_table
   >>> mg = MagGraph([(0, 1), (0, 2), (1, 4), (2, 3), (3, 4)])
   >>> mg.populate_paths(l_max=3)
   >>> print(format_rank_table(mg.rank_homology()))
   ╭─────┬────────────╮
   │ k=  │ 0  1  2  3 │
   ├─────┼────────────┤
   │ l=0 │ 5          │
   │ l=1 │ .  5       │
   │ l=2 │ .  .  .    │
   │ l=3 │ .  .  1  . │
   ╰─────┴────────────╯