muoblpanalyzers 0.0.1__tar.gz

muoblpanalyzers-0.0.1/PKG-INFO

@@ -0,0 +1,91 @@
+Metadata-Version: 2.4
+Name: muoblpanalyzers
+Version: 0.0.1
+Summary: Analysis metrics for solved multi objective linear programs
+License-Expression: MIT
+Author: Piotr Skowron
+Author-email: p.skowron@mimuw.edu.pl
+Requires-Python: >=3.13
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Programming Language :: Python :: 3.15
+Provides-Extra: native
+Requires-Dist: muoblp (>=1.0.5,<2.0)
+Requires-Dist: muoblpbindings (>=0.0.20,<0.1) ; extra == "native"
+Requires-Dist: muoblpsolvers (>=0.0.15,<0.1)
+Requires-Dist: pulp (==3.3.2)
+Project-URL: Documentation, https://jasieksz.github.io/multiobjective-lp
+Project-URL: Repository, https://github.com/algorithmic-econ/multiobjective-lp
+Description-Content-Type: text/markdown
+
+# Analyzers
+Metrics for analysing solved multi objective linear programs
+(`muoblp.MultiObjectiveLpProblem` with variable values set, e.g. by a solver
+from `muoblpsolvers`).
+
+---
+
+## Installation
+```shell
+pip install muoblpanalyzers            # python metrics
+pip install "muoblpanalyzers[native]"  # + C++ native metrics (muoblpbindings)
+```
+
+## Usage
+```python
+from muoblpanalyzers import Metric, get_metrics, ejr_plus
+
+problem.solve(solver)  # any solved MultiObjectiveLpProblem
+
+get_metrics([Metric.EXCLUSION_RATIO, Metric.EJR_PLUS_NATIVE], problem)
+# {"EXCLUSION_RATIO": {"exclusion_ratio": 0.25}, "EJR_PLUS_NATIVE": {"ejr_plus": 0}}
+
+ejr_plus(problem)  # single metric -> {"ejr_plus": 0}
+```
+
+## Metrics
+`Metric` values are stable keys (used in persisted results), never renamed.
+
+| `Metric` | Function | Result | Notes |
+|---|---|---|---|
+| `EXCLUSION_RATIO` | `exclusion_ratio` | `{"exclusion_ratio": float}` | share of objectives (voters) with value 0 |
+| `SUM_OBJECTIVES` | `sum_objectives` | `{"sum": float}` | sum of objective values |
+| `EJR_PLUS` | `ejr_plus` | `{"ejr_plus": int}` | unelected projects violating EJR+ (up to one) |
+| `CONSTRAINTS` | `invalid_constraints` | `{"pb_constraint": bool, "invalid_count": int}` | needs PB constraint |
+| `INSTANCE_SIZE` | `instance_size` | `{"size": int}` | number of variables |
+| `TOTAL_COST` | `total_cost` | `{"total_cost": float}` | needs PB constraint |
+| `EXCLUSION_RATIO_NATIVE` | native | same as `EXCLUSION_RATIO` | needs `[native]` |
+| `EJR_PLUS_NATIVE` | native | same as `EJR_PLUS` | needs `[native]` |
+
+PB constraint = single `<=` constraint covering all candidates
+(`muoblpsolvers.election_solver.validate_pb_constraint`); missing or ambiguous
+raises.
+
+## Native metrics
+C++ implementations from `muoblpbindings.metrics`, each a twin of a python
+metric (`PYTHON_COUNTERPART`) with identical results (parity-tested, exact).
+* Imports are lazy: python metrics work without bindings; a native metric
+  without bindings raises `ImportError` (no silent python fallback).
+* `get_metrics` builds one `SolvedInstance` handle per problem, shared by all
+  requested native metrics; a snapshot of variable values at build time.
+
+## Adding a metric
+* Python: function `(MultiObjectiveLpProblem) -> dict` in `metrics.py`,
+  `Metric` member in `metric.py`, entry in `PYTHON_STRATEGIES`.
+* Native: follow "Adding new metric" in the
+  [bindings README](../bindings/README.md), then register strategy in
+  `NATIVE_STRATEGIES` and its python oracle in `PYTHON_COUNTERPART`
+  (`native_metrics.py`). Parity tests pick it up from `PYTHON_COUNTERPART`.
+* `experiments` consumers: add matching `AnalyzerResult` field
+  (`experiments/src/helpers/analyzers/model.py`).
+
+## Development
+```shell
+$ poetry install --all-extras
+$ poetry run pytest
+$ poetry run pyright
+```
+C++ edits need a reinstall of the bindings into this venv:
+`poetry run pip install --force-reinstall --no-deps ../bindings`.
+

muoblpanalyzers-0.0.1/README.md

@@ -0,0 +1,69 @@
+# Analyzers
+Metrics for analysing solved multi objective linear programs
+(`muoblp.MultiObjectiveLpProblem` with variable values set, e.g. by a solver
+from `muoblpsolvers`).
+
+---
+
+## Installation
+```shell
+pip install muoblpanalyzers            # python metrics
+pip install "muoblpanalyzers[native]"  # + C++ native metrics (muoblpbindings)
+```
+
+## Usage
+```python
+from muoblpanalyzers import Metric, get_metrics, ejr_plus
+
+problem.solve(solver)  # any solved MultiObjectiveLpProblem
+
+get_metrics([Metric.EXCLUSION_RATIO, Metric.EJR_PLUS_NATIVE], problem)
+# {"EXCLUSION_RATIO": {"exclusion_ratio": 0.25}, "EJR_PLUS_NATIVE": {"ejr_plus": 0}}
+
+ejr_plus(problem)  # single metric -> {"ejr_plus": 0}
+```
+
+## Metrics
+`Metric` values are stable keys (used in persisted results), never renamed.
+
+| `Metric` | Function | Result | Notes |
+|---|---|---|---|
+| `EXCLUSION_RATIO` | `exclusion_ratio` | `{"exclusion_ratio": float}` | share of objectives (voters) with value 0 |
+| `SUM_OBJECTIVES` | `sum_objectives` | `{"sum": float}` | sum of objective values |
+| `EJR_PLUS` | `ejr_plus` | `{"ejr_plus": int}` | unelected projects violating EJR+ (up to one) |
+| `CONSTRAINTS` | `invalid_constraints` | `{"pb_constraint": bool, "invalid_count": int}` | needs PB constraint |
+| `INSTANCE_SIZE` | `instance_size` | `{"size": int}` | number of variables |
+| `TOTAL_COST` | `total_cost` | `{"total_cost": float}` | needs PB constraint |
+| `EXCLUSION_RATIO_NATIVE` | native | same as `EXCLUSION_RATIO` | needs `[native]` |
+| `EJR_PLUS_NATIVE` | native | same as `EJR_PLUS` | needs `[native]` |
+
+PB constraint = single `<=` constraint covering all candidates
+(`muoblpsolvers.election_solver.validate_pb_constraint`); missing or ambiguous
+raises.
+
+## Native metrics
+C++ implementations from `muoblpbindings.metrics`, each a twin of a python
+metric (`PYTHON_COUNTERPART`) with identical results (parity-tested, exact).
+* Imports are lazy: python metrics work without bindings; a native metric
+  without bindings raises `ImportError` (no silent python fallback).
+* `get_metrics` builds one `SolvedInstance` handle per problem, shared by all
+  requested native metrics; a snapshot of variable values at build time.
+
+## Adding a metric
+* Python: function `(MultiObjectiveLpProblem) -> dict` in `metrics.py`,
+  `Metric` member in `metric.py`, entry in `PYTHON_STRATEGIES`.
+* Native: follow "Adding new metric" in the
+  [bindings README](../bindings/README.md), then register strategy in
+  `NATIVE_STRATEGIES` and its python oracle in `PYTHON_COUNTERPART`
+  (`native_metrics.py`). Parity tests pick it up from `PYTHON_COUNTERPART`.
+* `experiments` consumers: add matching `AnalyzerResult` field
+  (`experiments/src/helpers/analyzers/model.py`).
+
+## Development
+```shell
+$ poetry install --all-extras
+$ poetry run pytest
+$ poetry run pyright
+```
+C++ edits need a reinstall of the bindings into this venv:
+`poetry run pip install --force-reinstall --no-deps ../bindings`.

muoblpanalyzers-0.0.1/pyproject.toml

@@ -0,0 +1,64 @@
+[project]
+version = "0.0.1"
+name = "muoblpanalyzers"
+description = "Analysis metrics for solved multi objective linear programs"
+
+authors = [
+    { name = "Piotr Skowron", email = "p.skowron@mimuw.edu.pl" },
+    { name = "Jan Sznajd", email = "j.sznajd@uw.edu.pl" }
+]
+license = "MIT"
+readme = "README.md"
+
+requires-python = ">=3.13"
+
+dependencies = [
+    "muoblp>=1.0.5,<2.0",
+    "muoblpsolvers>=0.0.15,<0.1",
+    "pulp==3.3.2",
+]
+
+[project.optional-dependencies]
+# native (C++) metrics: muoblpbindings.metrics, imported lazily
+native = ["muoblpbindings>=0.0.20,<0.1"]
+
+[project.urls]
+repository = "https://github.com/algorithmic-econ/multiobjective-lp"
+documentation = "https://jasieksz.github.io/multiobjective-lp"
+
+[tool.poetry]
+packages = [{include = "muoblpanalyzers", from = "src"}]
+
+# Single-style policy: static [project.dependencies] holds the
+# published version pins; this table ONLY enriches them with local path
+# sources for dev installs. Poetry 2.x uses [project] for wheel METADATA
+# and this table for install/lock -- do not move deps back here alone or
+# wheels regain broken file:// refs.
+[tool.poetry.dependencies]
+muoblp = {path = "../core", develop = true}
+muoblpsolvers = {path = "../solvers", develop = true}
+# explicit path wiring: solvers' path enrichment for muoblpbindings
+# doesn't propagate transitively on relock
+muoblpbindings = {path = "../bindings", develop = false, optional = true}
+
+[build-system]
+requires = ["poetry-core>=2.0.0,<3.0.0"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.ruff]
+line-length = 79
+preview = true
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+addopts = "-ra -q --import-mode=importlib"
+testpaths = [
+    "tests",
+]
+
+[dependency-groups]
+dev = [
+    "pytest (>=8.4,<9.0)",
+    "ruff (==0.15.1)",  # = CI (ruff.yml); preview rules drift across patches
+    "pyright (>=1.1,<2.0)"
+]

muoblpanalyzers-0.0.1/src/muoblpanalyzers/__init__.py

@@ -0,0 +1,39 @@
+import logging
+
+from muoblpanalyzers.metric import Metric
+from muoblpanalyzers.metrics import (
+    PYTHON_STRATEGIES,
+    ejr_plus,
+    exclusion_ratio,
+    get_metric_strategy,
+    get_metrics,
+    instance_size,
+    invalid_constraints,
+    sum_objectives,
+    total_cost,
+)
+from muoblpanalyzers.native_metrics import (
+    NATIVE_STRATEGIES,
+    PYTHON_COUNTERPART,
+    build_solved_instance,
+)
+
+__all__ = [
+    "NATIVE_STRATEGIES",
+    "PYTHON_COUNTERPART",
+    "PYTHON_STRATEGIES",
+    "Metric",
+    "build_solved_instance",
+    "ejr_plus",
+    "exclusion_ratio",
+    "get_metric_strategy",
+    "get_metrics",
+    "instance_size",
+    "invalid_constraints",
+    "sum_objectives",
+    "total_cost",
+]
+
+logger = logging.getLogger(__name__)
+
+logger.addHandler(logging.NullHandler())

muoblpanalyzers-0.0.1/src/muoblpanalyzers/metric.py

@@ -0,0 +1,15 @@
+from enum import StrEnum
+
+
+class Metric(StrEnum):
+    # values are on-disk keys (metrics.json, goldens): never rename
+    EXCLUSION_RATIO = "EXCLUSION_RATIO"
+    SUM_OBJECTIVES = "SUM_OBJECTIVES"
+    EJR_PLUS = "EJR_PLUS"
+    CONSTRAINTS = "CONSTRAINTS"
+    INSTANCE_SIZE = "INSTANCE_SIZE"
+    TOTAL_COST = "TOTAL_COST"
+    # native (C++ bindings) twin of EXCLUSION_RATIO
+    EXCLUSION_RATIO_NATIVE = "EXCLUSION_RATIO_NATIVE"
+    # native (C++ bindings) twin of EJR_PLUS
+    EJR_PLUS_NATIVE = "EJR_PLUS_NATIVE"

muoblpanalyzers-0.0.1/src/muoblpanalyzers/metrics.py

@@ -0,0 +1,124 @@
+from collections.abc import Callable
+from typing import cast
+
+from muoblp.model.multi_objective_lp import MultiObjectiveLpProblem
+from muoblpsolvers.election_solver import validate_pb_constraint
+
+from muoblpanalyzers import native_metrics
+from muoblpanalyzers.metric import Metric
+
+
+def get_metrics(
+    metrics: list[Metric], problem: MultiObjectiveLpProblem
+) -> dict[str, dict]:
+    # native handle built once per problem, only if a native metric is asked
+    instance = (
+        native_metrics.build_solved_instance(problem)
+        if any(m in native_metrics.NATIVE_STRATEGIES for m in metrics)
+        else None
+    )
+    results: dict[str, dict] = {}
+    for metric in metrics:
+        if instance is not None and metric in native_metrics.NATIVE_STRATEGIES:
+            results[metric] = native_metrics.NATIVE_STRATEGIES[metric](
+                instance
+            )
+        else:
+            results[metric] = get_metric_strategy(metric)(problem)
+    return results
+
+
+def get_metric_strategy(
+    metric: Metric,
+) -> Callable[[MultiObjectiveLpProblem], dict]:
+    # native metrics have no python strategy (see NATIVE_STRATEGIES)
+    try:
+        return PYTHON_STRATEGIES[metric]
+    except KeyError:
+        raise NotImplementedError("Metric not implemented") from None
+
+
+def exclusion_ratio(problem: MultiObjectiveLpProblem) -> dict:
+    zero_count = len([1 for obj in problem.objectives if obj.value() == 0])
+    return {
+        "exclusion_ratio": zero_count / len(problem.objectives),
+    }
+
+
+def sum_objectives(problem: MultiObjectiveLpProblem) -> dict:
+    # expects a solved problem: every variable has a value, so value() is
+    # never None here
+    return {
+        "sum": sum(cast(float, obj.value()) for obj in problem.objectives),
+    }
+
+
+def total_cost(problem: MultiObjectiveLpProblem) -> dict:
+    pb_constraint = validate_pb_constraint(problem)
+    costs = {candidate.name: cost for candidate, cost in pb_constraint.items()}
+    selected = [v for v in problem.variables() if v.value() == 1.0]
+    return {
+        "total_cost": sum(costs[c.name] for c in selected),
+    }
+
+
+def invalid_constraints(problem: MultiObjectiveLpProblem) -> dict:
+    total_budget_constraint = validate_pb_constraint(problem)
+    return {
+        "pb_constraint": total_budget_constraint.valid(),
+        "invalid_count": sum(
+            1 if not c.valid() else 0 for c in problem.constraints.values()
+        ),
+    }
+
+
+def instance_size(problem: MultiObjectiveLpProblem) -> dict:
+    return {"size": len(problem.variables())}
+
+
+def ejr_plus(problem: MultiObjectiveLpProblem) -> dict:
+    # TODO: Check if utility was COST based
+    # TODO: Introduce metric options, i.e., pass up_to_one as config parameter
+    up_to_one = True
+
+    costs: dict[str, int] = {
+        candidate.name: cost
+        for constraint in problem.constraints.values()
+        for candidate, cost in constraint.items()
+    }
+
+    total_budget = abs(validate_pb_constraint(problem).constant)
+
+    voter_satisfaction = sorted(
+        [(voter, cast(float, voter.value())) for voter in problem.objectives],
+        key=lambda v_sat: v_sat[1],
+    )
+    voter_count = len(problem.objectives)
+    failures = []
+
+    for project in problem.variables():
+        if project.value() == 1:  # skip elected
+            continue
+        coalition_size = 0
+        for voter, satisfaction in voter_satisfaction:
+            # if voter approved of project
+            if project in voter:
+                coalition_size += 1
+                ejr_satisfied = satisfaction >= (
+                    coalition_size / voter_count
+                ) * total_budget - (costs[project.name] if up_to_one else 0)
+                if not ejr_satisfied:
+                    failures.append(project.name)
+                    break
+
+    return {"ejr_plus": len(failures)}
+
+
+PYTHON_STRATEGIES: dict[Metric, Callable[[MultiObjectiveLpProblem], dict]] = {
+    Metric.EXCLUSION_RATIO: exclusion_ratio,
+    Metric.SUM_OBJECTIVES: sum_objectives,
+    Metric.EJR_PLUS: ejr_plus,
+    Metric.CONSTRAINTS: invalid_constraints,
+    Metric.INSTANCE_SIZE: instance_size,
+    Metric.TOTAL_COST: total_cost,
+}

muoblpanalyzers-0.0.1/src/muoblpanalyzers/native_metrics.py

@@ -0,0 +1,50 @@
+"""Native metrics: C++ implementations from `muoblpbindings.metrics`.
+
+Each has its own Metric name and a python counterpart (oracle) for parity
+tests. Imports are lazy: python-only analysis works without the metrics
+module, and a native request fails loudly with ImportError.
+"""
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING
+
+from muoblp.model.multi_objective_lp import MultiObjectiveLpProblem
+
+from muoblpanalyzers.metric import Metric
+
+if TYPE_CHECKING:
+    from muoblpbindings.metrics import SolvedInstance
+
+
+def build_solved_instance(
+    problem: MultiObjectiveLpProblem,
+) -> "SolvedInstance":
+    from muoblpbindings.metrics import SolvedInstance
+
+    return SolvedInstance(problem)
+
+
+def exclusion_ratio_native(instance: "SolvedInstance") -> dict:
+    from muoblpbindings.metrics import exclusion_ratio
+
+    # same inner key as python metric -> values compare directly
+    return {"exclusion_ratio": exclusion_ratio(instance)}
+
+
+def ejr_plus_native(instance: "SolvedInstance") -> dict:
+    from muoblpbindings.metrics import ejr_plus
+
+    # up_to_one=True, same as the python metric
+    return {"ejr_plus": ejr_plus(instance, up_to_one=True)}
+
+
+NATIVE_STRATEGIES: dict[Metric, Callable[["SolvedInstance"], dict]] = {
+    Metric.EXCLUSION_RATIO_NATIVE: exclusion_ratio_native,
+    Metric.EJR_PLUS_NATIVE: ejr_plus_native,
+}
+
+# parity tests iterate this map: every native metric must be registered here
+PYTHON_COUNTERPART: dict[Metric, Metric] = {
+    Metric.EXCLUSION_RATIO_NATIVE: Metric.EXCLUSION_RATIO,
+    Metric.EJR_PLUS_NATIVE: Metric.EJR_PLUS,
+}