perfect-strangers 0.1.0__tar.gz

perfect_strangers-0.1.0/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#   Usually these files are written by a python script from a template
+#   before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+# Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+# uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+# poetry.lock
+# poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+# pdm.lock
+# pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+# pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# Redis
+*.rdb
+*.aof
+*.pid
+
+# RabbitMQ
+mnesia/
+rabbitmq/
+rabbitmq-data/
+
+# ActiveMQ
+activemq-data/
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#   JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#   be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#   and can be added to the global gitignore or merged into this file.  For a more nuclear
+#   option (not recommended) you can uncomment the following to ignore the entire idea folder.
+# .idea/
+
+# Abstra
+#   Abstra is an AI-powered process automation framework.
+#   Ignore directories containing user credentials, local state, and settings.
+#   Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#   Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#   that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#   and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#   you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Streamlit
+.streamlit/secrets.toml
+
+.DS_Store

perfect_strangers-0.1.0/LICENSE.txt

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (c) 2025-present Sean Enderby <sean.enderby@gmail.com>
+
+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.

perfect_strangers-0.1.0/PKG-INFO

@@ -0,0 +1,45 @@
+Metadata-Version: 2.4
+Name: perfect-strangers
+Version: 0.1.0
+Summary: Non-search based routines for perfect stranger matching in behavioural studies.
+Project-URL: Documentation, https://senderby.co.uk/perfect-strangers
+Project-URL: Issues, https://github.com/seanlikeskites/perfect-strangers/issues
+Project-URL: Source, https://github.com/seanlikeskites/perfect-strangers
+Author-email: Sean Enderby <sean.enderby@gmail.com>
+License-Expression: MIT
+License-File: LICENSE.txt
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Programming Language :: Python :: Implementation :: PyPy
+Requires-Python: >=3.10
+Requires-Dist: galois~=0.4
+Requires-Dist: numpy~=2.0
+Description-Content-Type: text/markdown
+
+# perfect_strangers
+
+[![PyPI - Version](https://img.shields.io/pypi/v/perfect-strangers.svg)](https://pypi.org/project/perfect-strangers)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/perfect-strangers.svg)](https://pypi.org/project/perfect-strangers)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [License](#license)
+
+## Installation
+
+```console
+pip install perfect-strangers
+```
+
+## License
+
+`perfect-strangers` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

perfect_strangers-0.1.0/README.md

@@ -0,0 +1,21 @@
+# perfect_strangers
+
+[![PyPI - Version](https://img.shields.io/pypi/v/perfect-strangers.svg)](https://pypi.org/project/perfect-strangers)
+[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/perfect-strangers.svg)](https://pypi.org/project/perfect-strangers)
+
+-----
+
+## Table of Contents
+
+- [Installation](#installation)
+- [License](#license)
+
+## Installation
+
+```console
+pip install perfect-strangers
+```
+
+## License
+
+`perfect-strangers` is distributed under the terms of the [MIT](https://spdx.org/licenses/MIT.html) license.

perfect_strangers-0.1.0/junk.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "perfect-strangers"
+dynamic = ["version"]
+description = "Non-search based routines for perfect stranger matching in behavioural studies."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = []
+authors = [
+  { name = "Sean Enderby", email = "sean.enderby@gmail.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = [
+  "numpy~=2.0",
+  "galois~=0.4"
+]
+
+[project.urls]
+Documentation = "https://senderby.co.uk/perfect-strangers"
+Issues = "https://github.com/seanlikeskites/perfect-strangers/issues"
+Source = "https://github.com/seanlikeskites/perfect-strangers"
+
+[tool.hatch.version]
+path = "src/perfect_strangers/__about__.py"
+
+[[tool.hatch.envs.hatch-test.matrix]]
+python = ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+[tool.hatch.envs.types]
+extra-dependencies = [
+  "mypy>=1.0.0",
+  "pytest"
+]
+
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/perfect_strangers tests}"
+
+[tool.coverage.run]
+source_pkgs = ["perfect_strangers"]
+branch = true
+parallel = true
+omit = [
+  "src/perfect_strangers/__about__.py",
+]
+
+[tool.coverage.paths]
+perfect_strangers = ["src/perfect_strangers", "*/perfect-strangers/src/perfect_strangers"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]
+
+[tool.hatch.envs.docs]
+dependencies = [
+  "mkdocstrings-python",
+  "zensical"
+]
+
+[tool.hatch.envs.docs.scripts]
+serve = "zensical serve"
+build = "zensical build"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  "/.github",
+  "/docs",
+  "/mkdocs.yml",
+  "/site"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/perfect-strangers"]

perfect_strangers-0.1.0/pyproject.toml

@@ -0,0 +1,88 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "perfect-strangers"
+dynamic = ["version"]
+description = "Non-search based routines for perfect stranger matching in behavioural studies."
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+keywords = []
+authors = [
+  { name = "Sean Enderby", email = "sean.enderby@gmail.com" },
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Programming Language :: Python",
+  "Programming Language :: Python :: 3.10",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Programming Language :: Python :: 3.14",
+  "Programming Language :: Python :: Implementation :: CPython",
+  "Programming Language :: Python :: Implementation :: PyPy",
+]
+dependencies = [
+  "numpy~=2.0",
+  "galois~=0.4"
+]
+
+[project.urls]
+Documentation = "https://senderby.co.uk/perfect-strangers"
+Issues = "https://github.com/seanlikeskites/perfect-strangers/issues"
+Source = "https://github.com/seanlikeskites/perfect-strangers"
+
+[tool.hatch.version]
+path = "src/perfect_strangers/__about__.py"
+
+[[tool.hatch.envs.hatch-test.matrix]]
+python = ["3.10", "3.11", "3.12", "3.13", "3.14"]
+
+[tool.hatch.envs.types]
+extra-dependencies = [
+  "mypy>=1.0.0",
+  "pytest"
+]
+
+[tool.hatch.envs.types.scripts]
+check = "mypy --install-types --non-interactive {args:src/perfect_strangers tests}"
+
+[tool.coverage.run]
+source_pkgs = ["perfect_strangers"]
+branch = true
+parallel = true
+omit = [
+  "src/perfect_strangers/__about__.py",
+]
+
+[tool.coverage.paths]
+perfect_strangers = ["src/perfect_strangers", "*/perfect-strangers/src/perfect_strangers"]
+
+[tool.coverage.report]
+exclude_lines = [
+  "no cov",
+  "if __name__ == .__main__.:",
+  "if TYPE_CHECKING:",
+]
+
+[tool.hatch.envs.docs]
+dependencies = [
+  "mkdocstrings-python",
+  "zensical"
+]
+
+[tool.hatch.envs.docs.scripts]
+serve = "zensical serve"
+build = "zensical build"
+
+[tool.hatch.build.targets.sdist]
+exclude = [
+  "/.github",
+  "/docs",
+  "/mkdocs.yml"
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/perfect_strangers"]

perfect_strangers-0.1.0/src/perfect_strangers/__about__.py

@@ -0,0 +1,4 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+__version__ = "0.1.0"

perfect_strangers-0.1.0/src/perfect_strangers/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+from perfect_strangers.__about__ import __version__
+from perfect_strangers.base_matcher import BaseMatcher
+from perfect_strangers.column_shift_matcher import ColumnShiftMatcher
+from perfect_strangers.kirkman_triple_matcher import KirkmanTripleMatcher
+from perfect_strangers.round_robin_matcher import RoundRobinMatcher
+
+__all__ = ("__version__", "create_matcher")
+
+
+def create_matcher(groups_per_round: int, group_size: int) -> BaseMatcher:
+    """
+    Create a groups matcher for the given experiment parameters.
+
+    :param groups_per_round: The number of groups per round of the experiment.
+    :param group_size: The number of participants in each group.
+
+    :return: A matcher object of a type which inherits from [`BaseMatcher`][perfect_strangers.BaseMatcher].
+    """
+    if group_size == 2:
+        return RoundRobinMatcher(groups_per_round)
+
+    if group_size == 3:
+        matcher = KirkmanTripleMatcher.create_matcher(groups_per_round)
+
+        if matcher is not None:
+            return matcher
+
+    return ColumnShiftMatcher(groups_per_round, group_size)

perfect_strangers-0.1.0/src/perfect_strangers/base_matcher.py

@@ -0,0 +1,93 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from random import shuffle
+
+import numpy as np
+
+from perfect_strangers.util import is_round_pair_valid, is_round_valid
+
+RoundSequence = Sequence[np.typing.NDArray]
+
+class BaseMatcher:
+    """
+    Base class for all group matching methods.
+    """
+    def __init__(self, groups_per_round: int, group_size: int):
+        self.groups_per_round = groups_per_round
+        self.group_size = group_size
+        self.n_participants = groups_per_round * group_size
+
+        self.group_matrices = [
+            np.arange(self.n_participants).reshape(self.groups_per_round, self.group_size)
+        ]
+
+        self._generate_rounds()
+        self.shuffle_sequence()
+
+    @property
+    def max_rounds(self) -> int:
+        """
+        The maximum number of rounds this matcher will produce under perfect stranger matching conditions.
+        """
+        return len(self.group_matrices)
+
+    def groups_for_next_round(self) -> list[list[int]] | None:
+        """
+        Get the groups for the next round.
+
+        :return: A list of participants groupings for the next round, or None if there a no more rounds possible.
+        """
+        if self.next_round >= self.max_rounds:
+            return None
+
+        g = self.group_matrices[self.next_round].tolist()
+        self.next_round += 1
+        return g
+
+    def restart(self):
+        """
+        Reset the matcher to the first round.
+        """
+        self.next_round = 0
+
+    def shuffle_sequence(self):
+        """
+        Shuffle the list of rounds produced by this matcher.
+        """
+        shuffle(self.group_matrices)
+        self.restart()
+
+    def _generate_rounds(self):
+        pass
+
+    def _append_round(self, g):
+        if not is_round_valid(g, self.groups_per_round, self.group_size):
+            return False
+
+        for r in self.group_matrices:
+            if not is_round_pair_valid(r, g):
+                return False
+
+        self.group_matrices.append(g)
+        return True
+
+    def validate_rounds(self) -> bool:
+        for i, current_round in enumerate(self.group_matrices):
+            # Check current round include all participants.
+            if not is_round_valid(current_round, self.groups_per_round, self.group_size):
+                return False
+
+            # Check all subsequent rounds preserve perfect stranger matching with
+            # current round.
+            for j in range(i + 1, self.max_rounds):
+                next_round = self.group_matrices[j]
+
+                if not is_round_pair_valid(current_round, next_round):
+                    return False
+
+        return True

perfect_strangers-0.1.0/src/perfect_strangers/column_shift_matcher.py

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import math
+
+import numpy as np
+
+from perfect_strangers.base_matcher import BaseMatcher, RoundSequence
+from perfect_strangers.util import least_prime_factor
+
+
+def _shift_columns(base_matrix: np.typing.NDArray, stride: int) -> RoundSequence:
+    g = base_matrix.copy()
+    n_blocks = g.shape[0] // stride
+    group_size = g.shape[1]
+
+    if n_blocks < group_size:
+        return []
+
+    lpf = least_prime_factor(n_blocks) or 0
+
+    if group_size <= lpf:
+        n_shifts = n_blocks - 1
+    else:
+        # In some cases we can get away with more shifts. Need to work out a good
+        # way of calculating this.
+        n_shifts = math.ceil(n_blocks / (group_size - 1)) - 1
+
+    shifts = []
+
+    for _ in range(n_shifts):
+        for c in range(1, group_size):
+            g[:, c] = np.roll(g[:, c], c * stride)
+
+        shifts.append(g.copy())
+
+    return shifts
+
+class ColumnShiftMatcher(BaseMatcher):
+    def __init__(self, groups_per_round: int, group_size: int):
+        super().__init__(groups_per_round, group_size)
+
+    def _generate_rounds(self):
+        # Apply initial column shifts.
+        self.group_matrices += _shift_columns(self.group_matrices[0], 1)
+
+        # Apply submatrix transposition.
+        block_size = self.groups_per_round
+        n_blocks = 1
+
+        while block_size % self.group_size == 0:
+            g = self.group_matrices[0].copy()
+
+            stride = block_size // self.group_size
+
+            for block in range(n_blocks):
+                block_start = block * block_size
+
+                for sub in range(stride):
+                    start_col = block_start + sub
+                    end_col = start_col + self.group_size * stride
+                    g[start_col:end_col:stride, :] = g[start_col:end_col:stride, :].transpose()
+
+            self.group_matrices.append(g)
+            self.group_matrices += _shift_columns(g, block_size)
+
+            block_size = stride
+            n_blocks *= self.group_size
+

perfect_strangers-0.1.0/src/perfect_strangers/kirkman_triple_matcher.py

@@ -0,0 +1,174 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from collections.abc import Callable
+
+import galois
+import numpy as np
+
+from perfect_strangers.base_matcher import BaseMatcher, RoundSequence
+
+ParameterFuncReturn = tuple[int, int] | None
+RoundGenerator = Callable[[int, int], RoundSequence]
+
+#######################################################################
+# Theorem 5 from Ray-Chaudhuri and Wilson (1971):
+#   Where q = 6t + 1 is a prime power construct a Kirkman triple
+#   system for 3q total participants.
+#######################################################################
+def _get_t_from_q(q: int) -> ParameterFuncReturn:
+    """
+    Check q is a prime power of the form 6t + 1 and return t and q if it is.
+
+        :return: Tuple of (t, q) if q is a prime power of the form 6t + 1, None otherwise.
+    """
+    if not galois.is_prime_power(q) or q % 6 != 1:
+        return None
+
+    t = (q - 1) // 6
+
+    return t, q
+
+def _galois_field_elements(order: int) -> tuple[list[galois.FieldArray], galois.FieldArray]:
+    gf = galois.GF(order)
+    elements = [gf(i) for i in range(order)]
+    primitive_element = gf.primitive_element
+
+    return elements, primitive_element
+
+def _three_q_params(groups_per_round: int) -> ParameterFuncReturn:
+    return _get_t_from_q(groups_per_round)
+
+def _three_q_rounds(t: int, q: int) -> RoundSequence:
+    labels = np.arange(3 * q).reshape(q, 3)
+    field_elements, g = _galois_field_elements(q)
+
+    def next_group(shift, i, j=None):
+        return [labels[shift + g ** (i + 2 * x * t), j if j is not None else x] for x in range(3)]
+
+    rounds = []
+
+    for shift in field_elements:
+        new_round = np.empty((q, 3))
+        new_round[0, :] = labels[shift, :]
+        group_idx = 1
+
+        for i in range(t):
+            for j in range(3):
+                new_round[group_idx, :] = next_group(shift, i, j)
+                group_idx += 1
+
+        for i in range(6 * t):
+            if (i // t) % 2 == 0:
+                continue
+
+            new_round[group_idx, :] = next_group(shift, i)
+            group_idx += 1
+
+        rounds.append(new_round)
+
+    for i in range(6 * t):
+        if (i // t) % 2 != 0:
+            continue
+
+        new_round = np.empty((q, 3))
+
+        for shift in field_elements:
+            new_round[shift, :] = next_group(shift, i)
+
+        rounds.append(new_round)
+
+    return rounds
+
+#######################################################################
+# Theorem 6 from Ray-Chaudhuri and Wilson (1971)
+#   Where q = 6t + 1 is a prime power construct a Kirkman triple
+#   system for 2q + 1 total participants.
+#######################################################################
+def _two_q_less_one_params(groups_per_round: int) -> ParameterFuncReturn:
+    if groups_per_round % 2 == 0:
+        return None
+
+    q = (3 * groups_per_round - 1) // 2
+
+    return _get_t_from_q(q)
+
+def _two_q_less_one_rounds(t: int, q: int) -> RoundSequence:
+    groups_per_round = (2 * q + 1) // 3
+    labels = np.arange(2 * q).reshape(q, 2)
+    inf = 2 * q
+
+    field_elements, g = _galois_field_elements(q)
+
+    # Find m.
+    target = (g ** t + field_elements[1]) / field_elements[2]
+    m = target.log(g)
+
+    rounds = []
+
+    for shift in field_elements:
+        new_round = np.empty((groups_per_round, 3))
+
+        new_round[0, :] = [
+            labels[shift, 0],
+            labels[shift, 1],
+            inf
+        ]
+
+        group_idx = 1
+
+        for i in range(t):
+            for j in range(3):
+                new_round[group_idx, :] = [
+                    labels[shift + g ** (i + 2 * j * t), 0],
+                    labels[shift + g ** (i + 2 * j * t + t), 0],
+                    labels[shift + g ** (i + 2 * j * t + m), 1]
+                ]
+
+                group_idx += 1
+
+            new_round[group_idx, :] = [
+                labels[shift + g ** (i + m + t), 1],
+                labels[shift + g ** (i + m + 3 * t), 1],
+                labels[shift + g ** (i + m + 5 * t), 1]
+            ]
+
+            group_idx += 1
+
+        rounds.append(new_round)
+
+    return rounds
+
+#######################################################################
+# Matcher
+#######################################################################
+class KirkmanTripleMatcher(BaseMatcher):
+    """ Implementation as per https://math.stackexchange.com/a/4510645"""
+    def __init__(self, groups_per_round: int, t: int, q: int, round_generator: RoundGenerator):
+        self.t = t
+        self.q = q
+        self.round_generator = round_generator
+
+        super().__init__(groups_per_round, 3)
+
+    def _generate_rounds(self):
+        self.group_matrices = self.round_generator(self.t, self.q)
+
+    @classmethod
+    def create_matcher(cls, groups_per_round: int):
+        methods = [
+            (_three_q_params, _three_q_rounds),
+            (_two_q_less_one_params, _two_q_less_one_rounds)
+        ]
+
+        for parameter_func, round_generator in methods:
+            params = parameter_func(groups_per_round)
+
+            if params is not None:
+                t, q = params
+                return KirkmanTripleMatcher(groups_per_round, t, q, round_generator)
+
+        return None

perfect_strangers-0.1.0/src/perfect_strangers/radix_matcher.py

@@ -0,0 +1,62 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+from collections.abc import Generator
+
+from perfect_strangers.base_matcher import BaseMatcher
+
+
+def _round_increments(group_size, exponent) -> Generator[int]:
+    for n in range(1, exponent):
+        leading_one = group_size ** n
+
+        for i in range(leading_one):
+            yield leading_one + i
+
+def _non_carry_add_base_s(a: int, b: int, s: int) -> int:
+    n = 0
+    c = 0
+
+    while a + b > 0:
+        c += s**n * (((a % s) + (b % s)) % s)
+        n += 1
+        a //= s
+        b //= s
+
+    return c
+
+def _make_group(group_size: int, first_member: int, increment: int) -> list[int]:
+    m = first_member
+    remaining = group_size
+
+    group = []
+
+    while remaining > 0:
+        group.append(m)
+        m = _non_carry_add_base_s(m, increment, group_size)
+        remaining -= 1
+
+    return group
+
+class RadixMatcher(BaseMatcher):
+    def __init__(self, group_size: int, exponent: int):
+        self.exponent = exponent
+        super().__init__(group_size ** (exponent - 1), group_size)
+
+    def _generate_rounds(self):
+        participants = set(range(self.n_participants))
+
+        for i in _round_increments(self.group_size, self.exponent):
+            allocated = set()
+            g = self.group_matrices[0].copy()
+
+            for j in range(self.groups_per_round):
+                first_member = min(participants - allocated)
+                next_group = _make_group(self.group_size, first_member, i)
+                g[j, :] = next_group
+                allocated.update(set(next_group))
+
+            self._append_round(g)

perfect_strangers-0.1.0/src/perfect_strangers/round_robin_matcher.py

@@ -0,0 +1,24 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+import numpy as np
+
+from perfect_strangers.base_matcher import BaseMatcher
+
+
+class RoundRobinMatcher(BaseMatcher):
+    def __init__(self, groups_per_round: int):
+        # Round robin matching works with a group size of 2.
+        super().__init__(groups_per_round, 2)
+
+    def _generate_rounds(self):
+        def _rotate_groups(g):
+            flat = g.flatten("F")
+            flat[1:self.groups_per_round] = np.flip(flat[1:self.groups_per_round])
+            flat[1:] = np.roll(flat[1:], 1)
+            flat[1:self.groups_per_round] = np.flip(flat[1:self.groups_per_round])
+            return flat.reshape(g.shape, order="F")
+
+        for _ in range(self.n_participants - 2):
+            self.group_matrices.append(_rotate_groups(self.group_matrices[-1]))

perfect_strangers-0.1.0/src/perfect_strangers/util.py

@@ -0,0 +1,48 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+from __future__ import annotations
+
+import math
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    import numpy.typing as npt
+
+
+def is_round_valid(g: npt.NDArray, groups_per_round: int, group_size: int) -> bool:
+    n_groups_check = g.shape[0] == groups_per_round
+    group_size_check = g.shape[1] == group_size
+    participants_check = set(g.flatten()) == set(range(g.size))
+
+    return n_groups_check and group_size_check and participants_check
+
+def is_round_pair_valid(r1: npt.NDArray, r2: npt.NDArray) -> bool:
+    for i in range(r1.shape[0]):
+        g1 = set(r1[i, :])
+
+        for j in range(r2.shape[0]):
+            g2 = set(r2[j, :])
+
+            if len(g1 & g2) > 1:
+                return False
+
+    return True
+
+def least_prime_factor(n: int) -> int | None:
+    if n < 2:
+        return None
+
+    if n % 2 == 0:
+        return 2
+
+    f = 3
+
+    while f <= math.sqrt(n):
+        if n % f == 0:
+            return f
+
+        f += 2
+
+    return n

perfect_strangers-0.1.0/tests/__init__.py

@@ -0,0 +1,3 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT

perfect_strangers-0.1.0/tests/matcher_validation.py

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+def verify_n_rounds(matcher):
+    n_rounds = 0
+
+    while matcher.groups_for_next_round() is not None:
+        n_rounds += 1
+
+    assert n_rounds == matcher.max_rounds
+
+
+def validate_matcher(matcher):
+    if matcher.groups_per_round >= matcher.group_size:
+        assert matcher.max_rounds > 1
+    else:
+        assert matcher.max_rounds == 1
+
+    verify_n_rounds(matcher)
+
+    assert matcher.validate_rounds()

perfect_strangers-0.1.0/tests/test_column_shift_matching.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+import pytest
+
+from perfect_strangers import ColumnShiftMatcher
+from tests.matcher_validation import validate_matcher
+
+
+@pytest.mark.parametrize("group_size", range(3, 7))
+@pytest.mark.parametrize("groups_per_round", range(2, 31))
+def test_column_shifts(groups_per_round, group_size):
+    matcher = ColumnShiftMatcher(groups_per_round, group_size)
+
+    # Validate generated rounds
+    validate_matcher(matcher)

perfect_strangers-0.1.0/tests/test_kirkman_triple_matching.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+import pytest
+
+from perfect_strangers import KirkmanTripleMatcher
+from tests.matcher_validation import validate_matcher
+
+
+@pytest.mark.parametrize("groups_per_round", range(2, 31))
+def test_round_robin(groups_per_round):
+    matcher = KirkmanTripleMatcher.create_matcher(groups_per_round)
+
+    if matcher is not None:
+        # Kirkman triple matching should always give the maximum possible rounds.
+        assert matcher.max_rounds == (3 * groups_per_round - 1) // 2
+
+        # Validate generated rounds
+        validate_matcher(matcher)

perfect_strangers-0.1.0/tests/test_number_theory.py

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+import galois
+import pytest
+
+from perfect_strangers.util import least_prime_factor
+
+
+@pytest.mark.parametrize("n", range(101))
+def test_least_prime_factor(n):
+    test_value = least_prime_factor(n)
+
+    if n < 2:
+        assert test_value is None
+
+    else:
+        truth = min(galois.factors(n)[0])
+        assert test_value == truth

perfect_strangers-0.1.0/tests/test_radix_matching.py

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+import pytest
+
+from perfect_strangers.radix_matcher import RadixMatcher
+from tests.matcher_validation import validate_matcher
+
+
+@pytest.mark.parametrize("exponent", range(2, 4))
+@pytest.mark.parametrize("group_size", range(3, 7))
+def test_radix_matching(group_size, exponent):
+    matcher = RadixMatcher(group_size, exponent)
+
+    # Validate generated rounds
+    validate_matcher(matcher)

perfect_strangers-0.1.0/tests/test_round_robin_matching.py

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2025-present Sean Enderby <sean.enderby@gmail.com>
+#
+# SPDX-License-Identifier: MIT
+
+import pytest
+
+from perfect_strangers import RoundRobinMatcher
+from tests.matcher_validation import validate_matcher
+
+
+@pytest.mark.parametrize("groups_per_round", range(2, 31))
+def test_round_robin(groups_per_round):
+    matcher = RoundRobinMatcher(groups_per_round)
+
+    # Round robin matching should always give the maximum possible rounds.
+    assert matcher.max_rounds == 2 * groups_per_round - 1
+
+    # Validate generated rounds
+    validate_matcher(matcher)