mutation-game 0.1.0__tar.gz

mutation_game-0.1.0/.claude/settings.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(ls /home/acortis/my_codes/mutation_game/*.py)",
+      "Bash(ls /home/acortis/my_codes/mutation_game/.venv/bin/python*)",
+      "Bash(/home/acortis/my_codes/mutation_game/.venv/bin/python -c \"import numpy; print\\('numpy ok'\\); import networkx; print\\('nx ok'\\); import matplotlib; print\\('mpl ok'\\)\")"
+    ]
+  }
+}

mutation_game-0.1.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+docs/_build/
+.pytest_cache/
+*.egg-info/

mutation_game-0.1.0/.python-version

@@ -0,0 +1 @@
+3.11

mutation_game-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrea Cortis
+
+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.

mutation_game-0.1.0/PKG-INFO

@@ -0,0 +1,119 @@
+Metadata-Version: 2.4
+Name: mutation-game
+Version: 0.1.0
+Summary: Root system explorer via the combinatorial mutation game on graphs
+Project-URL: Homepage, https://github.com/andreacortis/mutation_game
+Project-URL: Repository, https://github.com/andreacortis/mutation_game
+Author: Andrea Cortis
+License-Expression: MIT
+License-File: LICENSE
+Keywords: dynkin-diagrams,lie-algebras,mutation-game,root-systems,weyl-group
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: networkx>=3.0
+Requires-Dist: numpy>=1.24
+Description-Content-Type: text/markdown
+
+# Mutation Game
+
+A Python library for exploring root systems through the combinatorial mutation game on graphs.
+
+Given a graph (or a Dynkin diagram name like `A3`, `D5`, `E8`), the library computes the full root system via iterated mutations and visualizes the mutation graph.
+
+## Quick start
+
+```bash
+git clone git@github.com:andreacortis/mutation_game.git
+cd mutation_game
+uv sync
+```
+
+```python
+from mutation import MutationGame
+
+game = MutationGame.from_dynkin("A3")
+roots = game.calculate_roots()
+print(f"A3 has {len(roots)} roots")  # 12
+
+fig = game.plot_root_orbits()
+fig.savefig("a3_positive.png", bbox_inches="tight", dpi=150)
+```
+
+![A3 positive roots](docs/_static/a3_positive.png)
+
+## Features
+
+- **Dynkin diagram support** -- create games from `A_n`, `D_n`, `E_6`, `E_7`, `E_8` by name
+- **Matrix-based mutations** -- each mutation is a precomputed matrix multiply (`v' = M_k @ v`)
+- **Cartan matrix analysis** -- eigenvalues, eigenvectors, and automatic finite-type detection via positive definiteness
+- **Root system computation** -- full BFS enumeration with verified root counts for all ADE types
+- **Mutation path finding** -- shortest path between any two roots via BFS on the mutation graph
+- **Path tables** -- all-pairs shortest mutation paths in a formatted table
+- **Visualization** -- side-by-side Dynkin diagram and mutation graph with color-coded simple roots
+
+## Finite-type detection
+
+The library checks whether the Cartan matrix `C = 2I - A` is positive definite before attempting to enumerate roots. Infinite-type graphs are rejected early with a clear error:
+
+```python
+cycle = MutationGame([[0,1,1],[1,0,1],[1,1,0]])
+cycle.is_finite_type()  # False
+cycle.calculate_roots()  # RuntimeError: Cartan matrix is not positive definite
+```
+
+## Mutation path table
+
+```python
+game = MutationGame.from_dynkin("A3")
+game.print_mutation_path_table()
+```
+
+```
+Source     Target     Mutations         Len
+-------------------------------------------
+(0, 0, 1)  (0, 1, 0)  1 -> 2            2
+(0, 0, 1)  (0, 1, 1)  1                 1
+(0, 0, 1)  (1, 0, 0)  1 -> 2 -> 0 -> 1  4
+(0, 0, 1)  (1, 1, 0)  1 -> 2 -> 0       3
+(0, 0, 1)  (1, 1, 1)  1 -> 0            2
+...
+```
+
+Each path is reversible: to go from B back to A, apply the same mutations in reverse order.
+
+## Tests
+
+```bash
+uv run pytest test_mutation.py -v
+```
+
+43 tests covering Dynkin construction, mutation rule, root counts for all ADE types, Cartan matrix properties, mutation paths, and plotting.
+
+## Documentation
+
+Full Sphinx documentation with mathematical background:
+
+```bash
+cd docs
+uv run sphinx-build -b html . _build/html
+```
+
+Then open `docs/_build/html/index.html`.
+
+## Dependencies
+
+- `numpy` -- linear algebra and matrix operations
+- `networkx` -- graph construction and layout
+- `matplotlib` -- visualization
+
+## License
+
+See [LICENSE](LICENSE).

mutation_game-0.1.0/README.md

@@ -0,0 +1,95 @@
+# Mutation Game
+
+A Python library for exploring root systems through the combinatorial mutation game on graphs.
+
+Given a graph (or a Dynkin diagram name like `A3`, `D5`, `E8`), the library computes the full root system via iterated mutations and visualizes the mutation graph.
+
+## Quick start
+
+```bash
+git clone git@github.com:andreacortis/mutation_game.git
+cd mutation_game
+uv sync
+```
+
+```python
+from mutation import MutationGame
+
+game = MutationGame.from_dynkin("A3")
+roots = game.calculate_roots()
+print(f"A3 has {len(roots)} roots")  # 12
+
+fig = game.plot_root_orbits()
+fig.savefig("a3_positive.png", bbox_inches="tight", dpi=150)
+```
+
+![A3 positive roots](docs/_static/a3_positive.png)
+
+## Features
+
+- **Dynkin diagram support** -- create games from `A_n`, `D_n`, `E_6`, `E_7`, `E_8` by name
+- **Matrix-based mutations** -- each mutation is a precomputed matrix multiply (`v' = M_k @ v`)
+- **Cartan matrix analysis** -- eigenvalues, eigenvectors, and automatic finite-type detection via positive definiteness
+- **Root system computation** -- full BFS enumeration with verified root counts for all ADE types
+- **Mutation path finding** -- shortest path between any two roots via BFS on the mutation graph
+- **Path tables** -- all-pairs shortest mutation paths in a formatted table
+- **Visualization** -- side-by-side Dynkin diagram and mutation graph with color-coded simple roots
+
+## Finite-type detection
+
+The library checks whether the Cartan matrix `C = 2I - A` is positive definite before attempting to enumerate roots. Infinite-type graphs are rejected early with a clear error:
+
+```python
+cycle = MutationGame([[0,1,1],[1,0,1],[1,1,0]])
+cycle.is_finite_type()  # False
+cycle.calculate_roots()  # RuntimeError: Cartan matrix is not positive definite
+```
+
+## Mutation path table
+
+```python
+game = MutationGame.from_dynkin("A3")
+game.print_mutation_path_table()
+```
+
+```
+Source     Target     Mutations         Len
+-------------------------------------------
+(0, 0, 1)  (0, 1, 0)  1 -> 2            2
+(0, 0, 1)  (0, 1, 1)  1                 1
+(0, 0, 1)  (1, 0, 0)  1 -> 2 -> 0 -> 1  4
+(0, 0, 1)  (1, 1, 0)  1 -> 2 -> 0       3
+(0, 0, 1)  (1, 1, 1)  1 -> 0            2
+...
+```
+
+Each path is reversible: to go from B back to A, apply the same mutations in reverse order.
+
+## Tests
+
+```bash
+uv run pytest test_mutation.py -v
+```
+
+43 tests covering Dynkin construction, mutation rule, root counts for all ADE types, Cartan matrix properties, mutation paths, and plotting.
+
+## Documentation
+
+Full Sphinx documentation with mathematical background:
+
+```bash
+cd docs
+uv run sphinx-build -b html . _build/html
+```
+
+Then open `docs/_build/html/index.html`.
+
+## Dependencies
+
+- `numpy` -- linear algebra and matrix operations
+- `networkx` -- graph construction and layout
+- `matplotlib` -- visualization
+
+## License
+
+See [LICENSE](LICENSE).

mutation_game-0.1.0/docs/Makefile

@@ -0,0 +1,12 @@
+SPHINXOPTS    =
+SPHINXBUILD   = sphinx-build
+SOURCEDIR     = .
+BUILDDIR      = _build
+
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)
+
+.PHONY: help Makefile
+
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS)

mutation_game-0.1.0/docs/api.rst

@@ -0,0 +1,7 @@
+API Reference
+=============
+
+.. autoclass:: mutation.MutationGame
+   :members:
+   :undoc-members:
+   :show-inheritance:

mutation_game-0.1.0/docs/background.rst

@@ -0,0 +1,259 @@
+Mathematical Background
+=======================
+
+The mutation game is a combinatorial process on graphs that naturally produces
+the root systems of Lie algebras. It was introduced by N. J. Wildberger
+[Wild2003]_ and later published in a generalized form in [Wild2020]_.
+This section describes the mathematical setting.
+
+The mutation game
+-----------------
+
+The game is set on a network of cities on Mars, as described by Wildberger
+[Wild2003]_. Consider a simple undirected graph *G* with *n* nodes, described
+by its adjacency matrix *A* (where :math:`A_{ij} = 1` if nodes *i* and *j* are
+connected, and 0 otherwise).
+
+A **state** of the game is an integer vector :math:`v \in \mathbb{Z}^n`, where
+each component :math:`v_i` represents the population at node *i*. Populations
+can be positive ("Martians") or negative ("Anti-Martians") -- Wildberger's
+original terminology.
+
+A **mutation at node** *k* transforms the state according to the rule:
+
+.. math::
+
+   v_k' = -v_k + \sum_{j \sim k} v_j
+
+where the sum runs over all neighbors *j* of *k*. All other components remain
+unchanged: :math:`v_i' = v_i` for :math:`i \neq k`.
+
+Equivalently, the mutation at node *k* is the linear map :math:`v \mapsto M_k v`
+where :math:`M_k` is the identity matrix with row *k* replaced:
+
+.. math::
+
+   (M_k)_{ij} = \begin{cases}
+     -1             & \text{if } i = k \text{ and } j = k \\
+     A_{kj}         & \text{if } i = k \text{ and } j \neq k \\
+     \delta_{ij}    & \text{if } i \neq k
+   \end{cases}
+
+Each mutation is an **involution**: :math:`M_k^2 = I`. Applying the same
+mutation twice returns the state to its original value.
+
+Root systems
+------------
+
+The **simple roots** are the standard basis vectors :math:`e_1, \ldots, e_n`.
+Starting from these seeds, the **root system** :math:`\Phi` is the set of all
+distinct vectors reachable by applying any sequence of mutations:
+
+.. math::
+
+   \Phi = \{ M_{k_m} \cdots M_{k_2} M_{k_1} \, e_i
+           \mid i \in \{1, \ldots, n\},\;
+           k_1, \ldots, k_m \in \{1, \ldots, n\},\;
+           m \geq 0 \}
+
+The root system decomposes into **positive roots** (all components
+:math:`\geq 0`) and **negative roots** (all components :math:`\leq 0`). Every
+root is either positive or negative, and :math:`v \in \Phi` implies
+:math:`-v \in \Phi`.
+
+Roots vs. bases
+^^^^^^^^^^^^^^^
+
+The simple roots :math:`e_1, \ldots, e_n` form a **basis** of
+:math:`\mathbb{R}^n` -- they are linearly independent and span the space. The
+root system, however, is much larger than a basis. For example, the A3 root
+system lives in :math:`\mathbb{R}^3` (which needs only 3 basis vectors) but
+contains 12 roots.
+
+Every root can be written as an integer linear combination of simple roots:
+positive roots have all non-negative coefficients, negative roots all
+non-positive. But the roots are far from independent -- the root system is a
+highly structured, symmetric set of vectors that the Weyl group permutes.
+
+The Weyl group as a group of symmetries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The mutation matrices :math:`M_1, \ldots, M_n` generate a **group** under
+matrix multiplication: the **Weyl group** :math:`W`. This group is finite for
+ADE-type graphs and acts on the root system.
+
+The group axioms are satisfied as follows:
+
+- **Closure**: the product of any two mutation matrices (or compositions
+  thereof) is another element of *W*. In particular, for any root
+  :math:`v \in \Phi` and any mutation :math:`M_k`, the image
+  :math:`M_k v` is again a root in :math:`\Phi`.
+- **Identity**: the identity matrix *I* is the "do nothing" mutation (apply
+  zero mutations).
+- **Inverses**: each mutation is its own inverse (:math:`M_k^2 = I`), so
+  every generator is an involution. Arbitrary products are inverted by
+  reversing the order:
+  :math:`(M_{k_1} M_{k_2} \cdots M_{k_m})^{-1} = M_{k_m} \cdots M_{k_2} M_{k_1}`.
+- **Associativity**: inherited from matrix multiplication.
+
+The root system :math:`\Phi` is then an **orbit** of the simple roots under
+this group action: :math:`\Phi = W \cdot \{e_1, \ldots, e_n\}` (together with
+their negatives). The root system itself is *not* a group (it is not closed
+under addition), but it is the set on which the Weyl group acts faithfully.
+
+Finite and infinite types
+-------------------------
+
+Whether the root system is finite depends on the graph:
+
+- **Finite type** -- The graph is a simply-laced Dynkin diagram (types A, D, E).
+  The mutation game terminates with a finite root system whose size is
+  determined by the type:
+
+  .. list-table::
+     :header-rows: 1
+
+     * - Type
+       - Graph structure
+       - Positive roots
+       - Total roots
+     * - :math:`A_n`
+       - Path on *n* nodes
+       - :math:`\frac{n(n+1)}{2}`
+       - :math:`n(n+1)`
+     * - :math:`D_n` (:math:`n \geq 4`)
+       - Path with a fork at one end
+       - :math:`n(n-1)`
+       - :math:`2n(n-1)`
+     * - :math:`E_6`
+       - See below
+       - 36
+       - 72
+     * - :math:`E_7`
+       - See below
+       - 63
+       - 126
+     * - :math:`E_8`
+       - See below
+       - 120
+       - 240
+
+- **Infinite type** -- For any other connected graph (e.g. a cycle, or a tree
+  not of ADE type), the mutation process generates infinitely many distinct
+  roots.
+
+The Cartan matrix and finite-type classification
+-------------------------------------------------
+
+The **Cartan matrix** of the graph is:
+
+.. math::
+
+   C = 2I - A
+
+The type of the root system is determined entirely by the spectrum of *C*:
+
+- **Positive definite** (all eigenvalues :math:`> 0`): the root system is
+  **finite**. This happens exactly for the ADE Dynkin diagrams.
+- **Positive semi-definite** (smallest eigenvalue :math:`= 0`): the root system
+  is **affine** (infinite, but with controlled growth). Example: a cycle graph.
+- **Indefinite** (a negative eigenvalue): the root system is **infinite** with
+  no finiteness structure.
+
+The library uses this criterion directly: ``is_finite_type()`` checks whether
+the Cartan matrix is positive definite. Methods that require the full root
+system (``calculate_roots``, ``plot_root_orbits``, etc.) raise a
+``RuntimeError`` early if the graph is not finite type, rather than running
+an unbounded BFS.
+
+.. code-block:: pycon
+
+   >>> from mutation import MutationGame
+   >>> game = MutationGame.from_dynkin("D4")
+   >>> game.is_finite_type()
+   True
+   >>> print(game.cartan_eigenvalues())
+   [0.58578644 2.         2.         3.41421356]
+
+   >>> cycle = MutationGame([[0,1,1],[1,0,1],[1,1,0]])
+   >>> cycle.is_finite_type()
+   False
+   >>> print(cycle.cartan_eigenvalues())
+   [0. 3. 3.]
+
+Eigenvectors of the Cartan matrix
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Since :math:`C = 2I - A`, the eigenvectors of *C* are exactly the eigenvectors
+of the adjacency matrix *A* (only the eigenvalues shift: if
+:math:`A v = \lambda v` then :math:`C v = (2 - \lambda) v`).
+
+The bilinear form :math:`\langle v, w \rangle = v^T C \, w` is the natural
+**inner product** on the root lattice. The Weyl group preserves this form --
+every mutation matrix satisfies :math:`M_k^T C \, M_k = C`. For simple roots,
+:math:`\langle e_i, e_j \rangle = C_{ij}`, so the Cartan matrix is literally
+the **Gram matrix** of the simple roots under this inner product.
+
+The **Perron--Frobenius eigenvector** (the eigenvector of *A* with the largest
+eigenvalue, equivalently the eigenvector of *C* with the smallest eigenvalue)
+has all positive entries and is closely related to the **highest root** -- the
+positive root with the largest height in the system.
+
+.. code-block:: pycon
+
+   >>> game = MutationGame.from_dynkin("A3")
+   >>> vals, vecs = game.cartan_eigenvectors()
+   >>> print("Eigenvalues:", vals)
+   Eigenvalues: [0.58578644 2.         3.41421356]
+   >>> print("Perron-Frobenius eigenvector:", vecs[:, 0])
+   Perron-Frobenius eigenvector: [ 0.5         0.70710678  0.5       ]
+
+Connection to Lie theory
+------------------------
+
+The mutation game is a combinatorial realization of the **Weyl group** action
+on a root system [Wild2003]_ [Wild2020]_. The mutation matrices :math:`M_k`
+are the **simple reflections** :math:`s_k` of the Weyl group *W(G)*, and the
+root system :math:`\Phi` produced by the game coincides with the root system of
+the corresponding simply-laced Lie algebra. Wildberger showed that the graphs
+for which the mutation game produces a finite root system are precisely the
+Dynkin diagrams of finite-dimensional complex simple Lie algebras. A related
+purely combinatorial construction of the Lie algebras themselves for
+simply-laced diagrams is given in [Wild2003b]_.
+
+The simple reflection at node *k* acts on the weight lattice as:
+
+.. math::
+
+   s_k(v) = v - (C v)_k \, e_k = v - (2 v_k - \sum_{j \sim k} v_j) \, e_k
+
+which is precisely the mutation rule:
+:math:`v_k \mapsto -v_k + \sum_{j \sim k} v_j`.
+
+The mutation graph
+------------------
+
+The **mutation graph** has the roots as vertices and an edge between two roots
+whenever one can be obtained from the other by a single mutation. Each edge is
+labeled with the index of the mutated node.
+
+For finite-type graphs, the mutation graph is a finite connected graph whose
+structure encodes the combinatorics of the Weyl group. The shortest path
+between two roots in this graph gives the minimal sequence of mutations (simple
+reflections) needed to transform one into the other.
+
+References
+----------
+
+.. [Wild2003] N. J. Wildberger, "The Mutation Game, Coxeter Graphs, and
+   Partially Ordered Multisets," preprint, UNSW, 2003.
+   https://web.maths.unsw.edu.au/~norman/papers/MutationGameCoxeterGraphs.pdf
+
+.. [Wild2020] N. J. Wildberger, "The Mutation Game, Coxeter--Dynkin Graphs,
+   and Generalized Root Systems," *Algebra Colloquium*, vol. 27, no. 1,
+   pp. 55--78, 2020.
+
+.. [Wild2003b] N. J. Wildberger, "A Combinatorial Construction for
+   Simply-Laced Lie Algebras," *Advances in Applied Mathematics*, vol. 30,
+   no. 1--2, pp. 385--396, 2003.
+   doi:`10.1016/S0196-8858(02)00541-9 <https://doi.org/10.1016/S0196-8858(02)00541-9>`_

mutation_game-0.1.0/docs/conf.py

@@ -0,0 +1,14 @@
+project = "Mutation Game"
+copyright = "2026"
+author = ""
+
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.napoleon",
+]
+
+html_theme = "sphinx_rtd_theme"
+html_static_path = ["_static"]
+
+import os, sys
+sys.path.insert(0, os.path.abspath(os.path.join("..", "src")))

mutation_game-0.1.0/docs/generate_images.py

@@ -0,0 +1,28 @@
+"""Generate example images for the documentation."""
+import sys, os
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
+import matplotlib
+matplotlib.use("Agg")
+
+from mutation_game import MutationGame
+
+# A3 positive roots
+game = MutationGame.from_dynkin("A3")
+fig = game.plot_root_orbits(positive_only=True)
+fig.savefig("_static/a3_positive.png", bbox_inches="tight", dpi=150)
+
+# A3 all roots
+fig = game.plot_root_orbits(positive_only=False)
+fig.savefig("_static/a3_all.png", bbox_inches="tight", dpi=150)
+
+# D4 positive roots
+game = MutationGame.from_dynkin("D4")
+fig = game.plot_root_orbits(positive_only=True)
+fig.savefig("_static/d4_positive.png", bbox_inches="tight", dpi=150)
+
+# E6 positive roots
+game = MutationGame.from_dynkin("E6")
+fig = game.plot_root_orbits(positive_only=True)
+fig.savefig("_static/e6_positive.png", bbox_inches="tight", dpi=150)
+
+print("Images generated.")