pairwise-combinatorial 0.1.0__py3-none-any.whl

pairwise_combinatorial/__init__.py

@@ -0,0 +1,51 @@
+"""
+Pairwise Combinatorial - Combinatorial method for pairwise comparison aggregation.
+
+This library implements the combinatorial method using Prüfer sequence enumeration
+for perfect parallelization, achieving near-linear speedup with multiple workers.
+"""
+
+from .combinatorial import (
+    combinatorial_method,
+    weighted_geometric_mean,
+    simple_geometric_mean,
+    weighted_arithmetic_mean,
+    simple_arithmetic_mean,
+    smart_worker_count,
+    auto_detect_workers,
+)
+from .llsm import llsm_incomplete
+from .helpers import (
+    is_full,
+    is_connected,
+    calculate_consistency_ratio,
+)
+from .gen import (
+    generate_comparison_matrix,
+    saaty_generator,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    # Main method
+    "combinatorial_method",
+    # Aggregation functions - Geometric
+    "weighted_geometric_mean",
+    "simple_geometric_mean",
+    # Aggregation functions - Arithmetic
+    "weighted_arithmetic_mean",
+    "simple_arithmetic_mean",
+    # Worker selection
+    "smart_worker_count",
+    "auto_detect_workers",
+    # LLSM
+    "llsm_incomplete",
+    # Helper functions
+    "is_full",
+    "is_connected",
+    "calculate_consistency_ratio",
+    # Matrix generation
+    "generate_comparison_matrix",
+    "saaty_generator",
+]

pairwise_combinatorial/combinatorial.py

@@ -0,0 +1,433 @@
+"""
+Combinatorial Method for Pairwise Comparison Aggregation using Prüfer Sequences.
+
+This implementation uses Prüfer sequence enumeration for perfect parallelization,
+achieving near-linear speedup with multiple workers.
+"""
+
+import numpy as np
+from typing import Callable, List, Tuple, Dict, Iterator
+import time
+import os
+from concurrent.futures import ProcessPoolExecutor, as_completed
+from itertools import product
+from .llsm import llsm_incomplete
+from .helpers import is_full
+
+# ============================================================================
+# PRÜFER SEQUENCE ENUMERATION
+# ============================================================================
+
+def prufer_to_edges(sequence: List[int], n: int) -> List[Tuple[int, int]]:
+    """
+    Convert Prüfer sequence to tree edge list.
+
+    Algorithm: Standard Prüfer decoding in O(n) time.
+
+    Args:
+        sequence: Prüfer sequence of length (n-2)
+        n: Number of nodes
+
+    Returns:
+        List of edges representing the spanning tree
+    """
+    # Initialize degree array: degree[i] = 1 + count of i in sequence
+    degree = [1] * n
+    for node in sequence:
+        degree[node] += 1
+
+    edges = []
+
+    # Process each element in the Prüfer sequence
+    for node in sequence:
+        # Find first node with degree 1
+        for i in range(n):
+            if degree[i] == 1:
+                # Add edge
+                edges.append((i, node))
+                # Update degrees
+                degree[i] -= 1
+                degree[node] -= 1
+                break
+
+    # Add final edge between last two nodes with degree 1
+    remaining = [i for i in range(n) if degree[i] == 1]
+    if len(remaining) == 2:
+        edges.append(tuple(remaining))
+
+    return edges
+
+
+def generate_prufer_sequences_with_prefix(n: int, prefix: List[int]) -> Iterator[List[int]]:
+    """
+    Generate all Prüfer sequences of length (n-2) starting with given prefix.
+
+    Args:
+        n: Number of nodes
+        prefix: Prefix that all sequences should start with
+
+    Yields:
+        Prüfer sequences as lists
+    """
+    sequence_length = n - 2
+    remaining_length = sequence_length - len(prefix)
+
+    if remaining_length < 0:
+        return
+
+    if remaining_length == 0:
+        yield prefix
+        return
+
+    # Generate all combinations for remaining positions
+    for suffix in product(range(n), repeat=remaining_length):
+        yield prefix + list(suffix)
+
+
+def calculate_work_distribution(n: int, num_workers: int) -> List[List[List[int]]]:
+    """
+    Calculate prefix distribution for each worker to ensure balanced load.
+
+    Returns a list where each element is a list of prefixes that worker should process.
+
+    For n=8, workers=1: [[[]] ]  (one worker, one empty prefix = all trees)
+    For n=8, workers=2: [ [[0],[1],[2],[3]], [[4],[5],[6],[7]] ]  (each worker gets 4 prefixes)
+    For n=8, workers=8: [ [[0]], [[1]], ..., [[7]] ]  (each worker gets 1 prefix)
+
+    Args:
+        n: Matrix size
+        num_workers: Number of parallel workers
+
+    Returns:
+        List of prefix lists, one list per worker. Each prefix list contains one or more prefixes.
+    """
+    # Special case: 1 worker
+    if num_workers == 1:
+        return [[[]]]  # One worker with one empty prefix (all trees)
+
+    # Find optimal prefix length
+    # We want enough prefixes to distribute evenly among workers
+    prefix_length = 1
+    while n ** prefix_length < num_workers:
+        prefix_length += 1
+
+    # Generate all prefixes
+    all_prefixes = [list(p) for p in product(range(n), repeat=prefix_length)]
+
+    # Distribute prefixes among workers
+    num_prefixes = len(all_prefixes)
+    prefixes_per_worker = num_prefixes // num_workers
+    extra = num_prefixes % num_workers
+
+    result = []
+    start_idx = 0
+    for i in range(num_workers):
+        # Some workers get one extra prefix if there's a remainder
+        count = prefixes_per_worker + (1 if i < extra else 0)
+        worker_prefixes = all_prefixes[start_idx:start_idx + count]
+        result.append(worker_prefixes)
+        start_idx += count
+
+    return result
+
+
+# ============================================================================
+# ICPCM CONSTRUCTION FROM EDGES
+# ============================================================================
+
+def build_icpcm_from_edges(edges: List[Tuple[int, int]], A: np.ndarray, n: int) -> np.ndarray:
+    """
+    Build Ideally Consistent PCM from tree edges using transitivity.
+
+    Args:
+        edges: List of tree edges
+        A: Original comparison matrix (for edge weights)
+        n: Number of criteria
+
+    Returns:
+        Complete ICPCM matrix
+    """
+    # Build adjacency list from edges
+    adj = [[] for _ in range(n)]
+    for u, v in edges:
+        adj[u].append(v)
+        adj[v].append(u)
+
+    icpcm = np.ones((n, n), dtype=float)
+
+    # For each node, BFS to compute all pairwise comparisons
+    for start in range(n):
+        visited = {start: 1.0}  # node -> accumulated product from start
+        queue = [start]
+
+        while queue:
+            current = queue.pop(0)
+            current_product = visited[current]
+
+            for neighbor in adj[current]:
+                if neighbor not in visited:
+                    # Get comparison value from original matrix
+                    if current < neighbor:
+                        weight = A[current, neighbor]
+                    else:
+                        weight = A[neighbor, current]
+                        weight = 1.0 / weight if weight != 0 else 1.0
+
+                    visited[neighbor] = current_product * weight
+                    queue.append(neighbor)
+
+        # Fill ICPCM row
+        for j, product in visited.items():
+            icpcm[start, j] = product
+
+    return icpcm
+
+
+# ============================================================================
+# PRIORITY VECTOR CALCULATION
+# ============================================================================
+
+def calculate_priority_vector(icpcm: np.ndarray) -> np.ndarray:
+    """
+    Calculate priority vector from ICPCM using geometric mean method.
+
+    Formula: w_j = (∏_i a_ij)^(1/n)
+    Then normalize: w = w / sum(w)
+
+    Args:
+        icpcm: Ideally Consistent Pairwise Comparison Matrix
+
+    Returns:
+        Normalized priority vector
+    """
+    n = icpcm.shape[0]
+    w = np.prod(icpcm, axis=0) ** (1.0 / n)
+    w = w / w.sum()
+    return w
+
+
+# ============================================================================
+# TREE QUALITY RATING
+# ============================================================================
+
+def calculate_tree_quality_from_edges(edges: List[Tuple[int, int]], n: int) -> float:
+    """
+    Calculate quality rating for a spanning tree based on diameter.
+
+    Lower diameter = less error propagation = higher quality.
+
+    Args:
+        edges: Tree edge list
+        n: Number of nodes
+
+    Returns:
+        Quality rating (higher is better)
+    """
+    # Build adjacency list
+    adj = [[] for _ in range(n)]
+    for u, v in edges:
+        adj[u].append(v)
+        adj[v].append(u)
+
+    # Calculate diameter using two BFS
+    # First BFS from node 0
+    def bfs_farthest(start):
+        visited = {start: 0}
+        queue = [start]
+        farthest = start
+        max_dist = 0
+
+        while queue:
+            node = queue.pop(0)
+            dist = visited[node]
+
+            for neighbor in adj[node]:
+                if neighbor not in visited:
+                    visited[neighbor] = dist + 1
+                    queue.append(neighbor)
+                    if dist + 1 > max_dist:
+                        max_dist = dist + 1
+                        farthest = neighbor
+
+        return farthest, max_dist
+
+    # Find one end of diameter
+    farthest1, _ = bfs_farthest(0)
+    # Find other end and actual diameter
+    _, diameter = bfs_farthest(farthest1)
+
+    return 1.0 / (diameter + 1)  # +1 to avoid division by zero
+
+
+# ============================================================================
+# AGGREGATION FUNCTIONS
+# ============================================================================
+
+def simple_geometric_mean(results: List[Tuple[np.ndarray, float]]) -> np.ndarray:
+    """Simple geometric mean aggregation (equal weight for all trees)."""
+    vectors = np.array([v for v, q in results])
+    log_vectors = np.log(vectors + 1e-10)
+    log_mean = np.mean(log_vectors, axis=0)
+    w_agg = np.exp(log_mean)
+    return w_agg / w_agg.sum()
+
+
+def weighted_geometric_mean(results: List[Tuple[np.ndarray, float]]) -> np.ndarray:
+    """Weighted geometric mean aggregation using quality ratings."""
+    vectors = np.array([v for v, q in results])
+    qualities = np.array([q for v, q in results])
+    qualities = qualities / qualities.sum()
+
+    log_vectors = np.log(vectors + 1e-10)
+    log_weighted_mean = np.sum(log_vectors * qualities[:, np.newaxis], axis=0)
+    w_agg = np.exp(log_weighted_mean)
+    return w_agg / w_agg.sum()
+
+
+def simple_arithmetic_mean(results: List[Tuple[np.ndarray, float]]) -> np.ndarray:
+    """Simple arithmetic mean aggregation (equal weight for all trees)."""
+    vectors = np.array([v for v, q in results])
+    w_agg = np.mean(vectors, axis=0)
+    return w_agg / w_agg.sum()
+
+
+def weighted_arithmetic_mean(results: List[Tuple[np.ndarray, float]]) -> np.ndarray:
+    """Weighted arithmetic mean aggregation using quality ratings."""
+    vectors = np.array([v for v, q in results])
+    qualities = np.array([q for v, q in results])
+    qualities = qualities / qualities.sum()
+
+    w_agg = np.sum(vectors * qualities[:, np.newaxis], axis=0)
+    return w_agg / w_agg.sum()
+
+
+# ============================================================================
+# WORKER COUNT SELECTION
+# ============================================================================
+
+def smart_worker_count(n: int) -> int:
+    """Intelligently select number of workers based on matrix size."""
+    cpu_count = os.cpu_count() or 8
+
+    # For Prüfer-based approach, use n workers for perfect distribution
+    # But don't exceed available CPUs
+    optimal = min(n, cpu_count)
+    return optimal
+
+
+def auto_detect_workers(n: int = None) -> int:
+    """Auto-detect number of workers based on CPU count."""
+    return os.cpu_count() or 4
+
+
+# ============================================================================
+# PARALLEL WORKER FUNCTION
+# ============================================================================
+
+def _process_prufer_range(
+    prefixes: List[List[int]],
+    A_data: bytes,
+    n: int,
+    quality_fn_name: str
+) -> List[Tuple[np.ndarray, float]]:
+    """
+    Worker function: process all Prüfer sequences with given prefixes.
+
+    Args:
+        prefixes: List of Prüfer sequence prefixes to process
+        A_data: Serialized comparison matrix
+        n: Matrix size
+        quality_fn_name: Name of quality function (unused for now)
+
+    Returns:
+        List of (priority_vector, quality) tuples
+    """
+    # Deserialize matrix
+    A = np.frombuffer(A_data, dtype=np.float64).reshape(n, n).copy()
+
+    results = []
+
+    # Process all sequences for each prefix
+    for prefix in prefixes:
+        for sequence in generate_prufer_sequences_with_prefix(n, prefix):
+            # Convert Prüfer sequence to edges
+            edges = prufer_to_edges(sequence, n)
+
+            # Build ICPCM
+            icpcm = build_icpcm_from_edges(edges, A, n)
+
+            # Calculate priority vector
+            priority_vector = calculate_priority_vector(icpcm)
+
+            # Calculate quality
+            quality = calculate_tree_quality_from_edges(edges, n)
+
+            results.append((priority_vector, quality))
+
+    return results
+
+
+
+# ============================================================================
+# MAIN COMBINATORIAL METHOD
+# ============================================================================
+
+def combinatorial_method(
+    A: np.ndarray,
+    n_workers: int | Callable = smart_worker_count,
+    aggregator: Callable = weighted_geometric_mean
+) -> Dict:
+    """
+    Combinatorial method using Prüfer sequence enumeration.
+
+    For incomplete matrices, uses LLSM to fill missing values first.
+
+    Args:
+        A: Pairwise comparison matrix (n × n)
+        n_workers: Number of workers or function returning worker count
+        aggregator: Function to aggregate priority vectors
+
+    Returns:
+        Dictionary with results:
+        - 'weights': Final aggregated priority vector
+        - 'tree_count': Number of spanning trees processed
+        - 'time_elapsed': Total time in seconds
+        - 'workers_used': Number of workers used
+    """
+    n = A.shape[0]
+
+    num_workers = n_workers(n) if callable(n_workers) else n_workers
+
+    # Calculate work distribution
+    work_distribution = calculate_work_distribution(n, num_workers)
+
+    # Serialize matrix for workers
+    A_data = A.astype(np.float64).tobytes()
+
+    all_results = []
+
+    if num_workers == 1:
+        # Serial execution
+        results = _process_prufer_range(work_distribution[0], A_data, n, "default")
+        all_results.extend(results)
+    else:
+        # Parallel execution
+        with ProcessPoolExecutor(max_workers=num_workers) as executor:
+            futures = []
+
+            for i, worker_prefixes in enumerate(work_distribution):
+                future = executor.submit(
+                    _process_prufer_range,
+                    worker_prefixes,
+                    A_data,
+                    n,
+                    "default"
+                )
+                futures.append((i, future))
+
+            # Collect results as they complete
+            for i, future in futures:
+                results = future.result()
+                all_results.extend(results)
+
+    return aggregator(all_results)

pairwise_combinatorial/gen.py

@@ -0,0 +1,55 @@
+import numpy as np
+from typing import Callable
+
+_rng = np.random.default_rng()
+
+def saaty_generator(i: int, j: int) -> float:
+    """
+    Generates random values from Saaty scale (1, 2, 3, 4, 5, 6, 7, 8, 9).
+
+    Args:
+        i: row index
+        j: column index
+
+    Returns:
+        Random value from Saaty scale
+    """
+    saaty_scale = np.array([1, 2, 3, 4, 5, 6, 7, 8, 9], dtype=float)
+    return _rng.choice(saaty_scale)
+
+def generate_comparison_matrix(
+    n: int,
+    missing_ratio: float = 0.0,
+    generator: Callable[[int, int], float] = saaty_generator
+) -> np.ndarray:
+    """
+    Generates a pairwise comparison matrix.
+
+    Args:
+        n: matrix dimension (number of criteria)
+        missing_ratio: ratio of missing comparisons (0.0 to 1.0)
+        generator: lambda function that accepts (i, j) and returns comparison value
+                   If None, uses saaty_generator by default
+
+    Returns:
+        np.ndarray of shape (n, n) with:
+        - Diagonal filled with 1.0
+        - Upper triangle filled by generator when not missing
+        - Lower triangle filled with reciprocal values (1/value)
+        - Missing values as np.nan
+    """
+    matrix = np.ones((n, n), dtype=float)
+
+    for i in range(n):
+        for j in range(i + 1, n):
+            if _rng.random() < missing_ratio:
+                matrix[i, j] = np.nan
+                matrix[j, i] = np.nan
+            else:
+                value = generator(i, j)
+                matrix[i, j] = value
+                matrix[j, i] = 1.0 / value if value != 0 else np.nan
+
+    np.fill_diagonal(matrix, 1.0)
+
+    return matrix

pairwise_combinatorial/helpers.py

@@ -0,0 +1,102 @@
+import numpy as np
+
+def is_connected(A: np.ndarray) -> bool:
+    n = A.shape[0]
+    visited = set()
+
+    def dfs(i):
+        for j in range(n):
+            if i != j and not np.isnan(A[i, j]):  # є ребро i→j
+                if j not in visited:
+                    visited.add(j)
+                    dfs(j)
+            if i != j and not np.isnan(A[j, i]):  # або j→i (ігноруємо напрям)
+                if j not in visited:
+                    visited.add(j)
+                    dfs(j)
+
+    visited.add(0)
+    dfs(0)
+
+    return len(visited) == n
+
+def is_full(A: np.ndarray) -> bool:
+    """
+    Check if the comparison matrix is full (no missing values)
+    """
+    return not np.isnan(A).any()
+
+
+def calculate_consistency_ratio(A: np.ndarray, w: np.ndarray) -> float:
+    """
+    Calculate the Consistency Ratio (CR) for a pairwise comparison matrix.
+
+    The CR measures how consistent the pairwise comparisons are with the
+    derived weight vector. Lower CR values indicate better consistency.
+
+    Saaty's guideline: CR < 0.10 is acceptable
+
+    Formula:
+    1. Compute λ_max (maximum eigenvalue)
+    2. CI = (λ_max - n) / (n - 1)  (Consistency Index)
+    3. CR = CI / RI  (Consistency Ratio)
+
+    where RI is the Random Index (depends on n)
+
+    Args:
+        A: Pairwise comparison matrix (n x n), may contain NaN
+        w: Priority weight vector (n,)
+
+    Returns:
+        Consistency Ratio (CR)
+    """
+    n = A.shape[0]
+
+    if n < 2:
+        return 0.0
+
+    # Random Index values (Saaty, 1980)
+    # RI[n] is the average CI of randomly generated matrices of size n
+    RI = {
+        1: 0.00, 2: 0.00, 3: 0.58, 4: 0.90, 5: 1.12,
+        6: 1.24, 7: 1.32, 8: 1.41, 9: 1.45, 10: 1.49,
+        11: 1.51, 12: 1.48, 13: 1.56, 14: 1.57, 15: 1.59
+    }
+
+    if n not in RI:
+        # For larger matrices, use approximation
+        RI[n] = 1.98 * (n - 2) / n
+
+    # Compute λ_max using only available (non-NaN) comparisons
+    # Method: λ_max ≈ average of (Aw)_i / w_i for all i
+
+    lambda_max_estimates = []
+
+    for i in range(n):
+        # Compute (Aw)_i using only non-NaN values
+        weighted_sum = 0.0
+        count = 0
+
+        for j in range(n):
+            if not np.isnan(A[i, j]):
+                weighted_sum += A[i, j] * w[j]
+                count += 1
+
+        if count > 0 and w[i] > 0:
+            lambda_max_estimates.append(weighted_sum / w[i])
+
+    if not lambda_max_estimates:
+        return 0.0
+
+    lambda_max = np.mean(lambda_max_estimates)
+
+    # Calculate Consistency Index
+    CI = (lambda_max - n) / (n - 1)
+
+    # Calculate Consistency Ratio
+    if RI[n] == 0:
+        return 0.0
+
+    CR = CI / RI[n]
+
+    return CR

pairwise_combinatorial/llsm.py

@@ -0,0 +1,35 @@
+import numpy as np
+from numpy.linalg import lstsq
+
+def llsm_incomplete(A: np.ndarray):
+    n = A.shape[0]
+    eqs = []
+    vals = []
+
+    # Беремо лише відомі елементи (не nan)
+    for i in range(n):
+        for j in range(n):
+            if i != j and not np.isnan(A[i, j]):
+                row = np.zeros(n)
+                row[i] = 1
+                row[j] = -1
+                eqs.append(row)
+                vals.append(np.log(A[i, j]))
+
+    eqs = np.array(eqs)
+    vals = np.array(vals)
+
+    # язання методом найменших квадратів
+    x, _, _, _ = np.linalg.lstsq(eqs, vals, rcond=None)
+
+    # Обчислюємо ваги
+    w = np.exp(x)
+    w /= w.sum()  # нормалізація
+
+    # Відновлюємо повну матрицю
+    A_filled = np.zeros((n, n))
+    for i in range(n):
+        for j in range(n):
+            A_filled[i, j] = w[i] / w[j]
+
+    return w, A_filled

pairwise_combinatorial-0.1.0.dist-info/METADATA

@@ -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}
+}
+```

pairwise_combinatorial-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+pairwise_combinatorial/__init__.py,sha256=qECRrXvoIzK5xUyjshQGUhgNHVZWndzKPphrncU4vIc,1247
+pairwise_combinatorial/combinatorial.py,sha256=KdA5WxyxXLikvS5Y1bSWxQqelPMhU6SoEO2Lsoh8MC0,13731
+pairwise_combinatorial/gen.py,sha256=7jwzmE51LP9MiZHlR9Hc7zgLSWLsQv4XPdsTTKZVu7I,1605
+pairwise_combinatorial/helpers.py,sha256=o_DUTmnMZPX5ALjDjuW6O3si2aOG88bR22z3gI_7aMQ,2687
+pairwise_combinatorial/llsm.py,sha256=XsLBuFMrIPXSVuh1RmRlJG9A81TbOIM9XyGT0rvJrEk,951
+pairwise_combinatorial-0.1.0.dist-info/METADATA,sha256=-CKWFfAN-joRhtuKQQxdi3eau00Ea-ibF-zzvakFeqs,11724
+pairwise_combinatorial-0.1.0.dist-info/WHEEL,sha256=qtCwoSJWgHk21S1Kb4ihdzI2rlJ1ZKaIurTj_ngOhyQ,87
+pairwise_combinatorial-0.1.0.dist-info/licenses/LICENSE,sha256=xo0iFqmQCkA7K4y6Gpwjcx3g0JfcRa3MNCpqwO8RpT4,1120
+pairwise_combinatorial-0.1.0.dist-info/RECORD,,

pairwise_combinatorial-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.27.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pairwise_combinatorial-0.1.0.dist-info/licenses/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.