pairwise-combinatorial 0.1.0__tar.gz

pairwise_combinatorial-0.1.0/.gitignore

@@ -0,0 +1,159 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$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
+*.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
+.python-version
+
+# pipenv
+Pipfile.lock
+
+# poetry
+poetry.lock
+
+# pdm
+.pdm.toml
+
+# PEP 582
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.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/
+
+# UV
+uv.lock
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+
+# Testing
+.tox/
+.pytest_cache/
+test-env/
+
+# PyPI
+dist/
+build/
+*.egg-info/
+
+PUBLISHING.md

pairwise_combinatorial-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+   MIT License
+
+   Copyright (c) 2025 Daniil Olekh
+
+   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.

pairwise_combinatorial-0.1.0/PKG-INFO

@@ -0,0 +1,299 @@
+Metadata-Version: 2.4
+Name: pairwise-combinatorial
+Version: 0.1.0
+Summary: Combinatorial method for pairwise comparison aggregation using Prüfer sequences with parallel processing
+Project-URL: Homepage, https://github.com/scape76/pairwise-combinatorial
+Project-URL: Repository, https://github.com/yourusername/pairwise-combinatorial
+Project-URL: Issues, https://github.com/yourusername/pairwise-combinatorial/issues
+Author-email: Daniil Olekh <danyaolekhq@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: ahp,combinatorial-optimization,decision-making,pairwise-comparison,prufer-sequences
+Classifier: Development Status :: 3 - Alpha
+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: Topic :: Scientific/Engineering :: Mathematics
+Requires-Python: >=3.11
+Requires-Dist: numpy>=2.3.4
+Description-Content-Type: text/markdown
+
+# Pairwise Combinatorial
+
+[English version](README.en.md)
+
+Python бібліотека для агрегації парних порівнянь з використанням комбінаторного методу та послідовностей Прюфера. Ця реалізація забезпечує ідеальну паралелізацію для майже лінійного прискорення з декількома робочими процесами.
+
+## Особливості
+
+- **Комбінаторний метод**: Агрегує матриці парних порівнянь через перерахування остовних дерев
+- **Паралельна обробка**: Використовує послідовності Прюфера для ідеального розподілу роботи між процесами
+- **Гнучка агрегація**: Підтримує зважене та просте середнє геометричне
+- **Підтримка неповних матриць**: Обробляє неповні матриці парних порівнянь за допомогою LLSM
+- **Генерація матриць**: Вбудовані утиліти для генерації тестових матриць порівнянь
+
+## Встановлення
+
+Встановити за допомогою `uv`:
+
+```bash
+uv pip install pairwise-combinatorial
+```
+
+Або встановити з джерела:
+
+```bash
+git clone https://github.com/danolekh/pairwise_combinatorial
+cd pairwise-combinatorial
+uv pip install -e .
+```
+
+## Швидкий старт
+
+```python
+import numpy as np
+from pairwise_combinatorial import (
+    combinatorial_method,
+    weighted_geometric_mean,
+    generate_comparison_matrix,
+)
+
+# Генеруємо випадкову матрицю порівнянь
+n = 9  # Кількість критеріїв
+A = generate_comparison_matrix(n, missing_ratio=0.0)
+
+# Застосовуємо комбінаторний метод з паралельною обробкою
+result = combinatorial_method(
+    A,
+    n_workers=10,  # Кількість паралельних робочих процесів
+    aggregator=weighted_geometric_mean,
+)
+
+print(f"Вектор пріоритетів: {result}")
+```
+
+## Довідник API
+
+### Основні функції
+
+#### `combinatorial_method(A, n_workers, aggregator)`
+
+Основний комбінаторний метод з використанням послідовностей Прюфера.
+
+**Параметри:**
+
+- `A` (np.ndarray): Матриця парних порівнянь (n × n)
+- `n_workers` (int | Callable): Кількість робочих процесів або функція, що повертає їх кількість
+  - За замовчуванням: `smart_worker_count` (автоматично визначає на основі розміру матриці та кількості CPU)
+- `aggregator` (Callable): Функція для агрегації векторів пріоритетів
+  - Геометричні: `weighted_geometric_mean` (за замовчуванням), `simple_geometric_mean`
+  - Арифметичні: `weighted_arithmetic_mean`, `simple_arithmetic_mean`
+
+**Повертає:**
+
+- `np.ndarray`: Фінальний агрегований вектор пріоритетів
+
+### Функції агрегації
+
+#### Геометричне середнє
+
+#### `weighted_geometric_mean(results)`
+
+Агрегує вектори пріоритетів за допомогою зваженого середнього геометричного.
+
+#### `simple_geometric_mean(results)`
+
+Агрегує вектори пріоритетів за допомогою простого середнього геометричного (рівні ваги).
+
+#### Арифметичне середнє
+
+#### `weighted_arithmetic_mean(results)`
+
+Агрегує вектори пріоритетів за допомогою зваженого середнього арифметичного.
+
+#### `simple_arithmetic_mean(results)`
+
+Агрегує вектори пріоритетів за допомогою простого середнього арифметичного (рівні ваги).
+
+### Допоміжні функції
+
+#### `generate_comparison_matrix(n, missing_ratio, generator)`
+
+Генерує матрицю парних порівнянь.
+
+**Параметри:**
+
+- `n` (int): Розмірність матриці (кількість критеріїв)
+- `missing_ratio` (float): Частка відсутніх порівнянь (від 0.0 до 1.0)
+- `generator` (Callable): Функція, що генерує значення порівнянь
+  - За замовчуванням: `saaty_generator` (використовує шкалу Сааті 1-9)
+
+**Повертає:**
+
+- `np.ndarray`: Матриця парних порівнянь
+
+#### `is_full(A)`
+
+Перевіряє, чи матриця порівнянь не має відсутніх значень.
+
+#### `is_connected(A)`
+
+Перевіряє, чи граф матриці порівнянь є зв'язним.
+
+#### `calculate_consistency_ratio(A, w)`
+
+Обчислює коефіцієнт узгодженості (CR) для матриці парних порівнянь.
+
+#### `llsm_incomplete(A)`
+
+Заповнює неповні матриці за допомогою методу логарифмічних найменших квадратів.
+
+### Вибір кількості робочих процесів
+
+#### `smart_worker_count(n)`
+
+Інтелектуально визначає кількість робочих процесів на основі розміру матриці та кількості CPU.
+
+#### `auto_detect_workers()`
+
+Автоматично визначає кількість робочих процесів лише на основі кількості CPU.
+
+## Приклади
+
+### Приклад з повною матрицею
+
+```python
+import numpy as np
+from pairwise_combinatorial import combinatorial_method, weighted_geometric_mean
+
+# Створюємо просту матрицю порівнянь 4x4
+A = np.array([
+    [1.0, 3.0, 5.0, 7.0],
+    [1/3, 1.0, 2.0, 4.0],
+    [1/5, 1/2, 1.0, 2.0],
+    [1/7, 1/4, 1/2, 1.0]
+])
+
+# Обчислюємо вектор пріоритетів
+weights = combinatorial_method(A, n_workers=4)
+print(f"Ваги: {weights}")
+```
+
+### Приклад з неповною матрицею
+
+```python
+import numpy as np
+from pairwise_combinatorial import (
+    combinatorial_method,
+    generate_comparison_matrix,
+    is_connected,
+)
+
+# Генеруємо матрицю з 30% відсутніх значень
+A = generate_comparison_matrix(n=6, missing_ratio=0.3)
+
+if is_connected(A):
+    # Застосовуємо комбінаторний метод
+    weights = combinatorial_method(A, n_workers=4)
+    print(f"Ваги: {weights}")
+else:
+    print("Матриця не є зв'язною!")
+```
+
+### Власна агрегація
+
+```python
+from pairwise_combinatorial import (
+    combinatorial_method,
+    simple_geometric_mean,
+    weighted_arithmetic_mean,
+    simple_arithmetic_mean,
+)
+
+# Використовуємо просте середнє геометричне
+weights = combinatorial_method(
+    A,
+    n_workers=8,
+    aggregator=simple_geometric_mean
+)
+
+# Використовуємо зважене середнє арифметичне
+weights = combinatorial_method(
+    A,
+    n_workers=8,
+    aggregator=weighted_arithmetic_mean
+)
+
+# Використовуємо просте середнє арифметичне
+weights = combinatorial_method(
+    A,
+    n_workers=8,
+    aggregator=simple_arithmetic_mean
+)
+```
+
+### Перевірка узгодженості
+
+```python
+from pairwise_combinatorial import (
+    combinatorial_method,
+    calculate_consistency_ratio,
+    generate_comparison_matrix,
+)
+
+A = generate_comparison_matrix(n=5)
+weights = combinatorial_method(A)
+
+cr = calculate_consistency_ratio(A, weights)
+print(f"Коефіцієнт узгодженості: {cr:.4f}")
+
+if cr < 0.10:
+    print("Матриця має прийнятну узгодженість (за критерієм Сааті)")
+else:
+    print("Узгодженість матриці викликає сумніви")
+```
+
+## Продуктивність
+
+Бібліотека використовує послідовності Прюфера для ідеальної паралелізації:
+
+- **Розмір матриці n=5**: ~125 остовних дерев, < 1 секунди
+- **Розмір матриці n=7**: ~16,807 остовних дерев, ~1 секунда
+- **Розмір матриці n=8**: ~262,144 остовних дерев, ~10 секунд (8 робочих процесів)
+- **Розмір матриці n=9**: ~4,782,969 остовних дерев, ~3 хвилини (10 робочих процесів)
+
+Продуктивність масштабується майже лінійно з кількістю робочих процесів до кількості критеріїв (n).
+
+## Деталі алгоритму
+
+Комбінаторний метод:
+
+1. Перераховує всі остовні дерева за допомогою послідовностей Прюфера
+2. Для кожного дерева будує ідеально узгоджену МПП (ICPCM)
+3. Обчислює вектори пріоритетів з кожної ICPCM
+4. Агрегує всі вектори пріоритетів за допомогою середнього геометричного
+
+Послідовності Прюфера забезпечують ідеальну паралелізацію через розподіл префіксів послідовностей між робочими процесами.
+
+## Ліцензія
+
+MIT
+
+## Внесок
+
+Внески вітаються! Будь ласка, не соромтеся відправляти Pull Request.
+
+## Цитування
+
+Якщо ви використовуєте цю бібліотеку у своїх дослідженнях, будь ласка, процитуйте:
+
+```
+@software{pairwise_combinatorial,
+  title = {Pairwise Combinatorial: Паралельний комбінаторний метод для агрегації парних порівнянь},
+  author = {Your Name},
+  year = {2024},
+  url = {https://github.com/danolekh/pairwise_combinatorial}
+}
+```