opdiv 0.1.0__tar.gz

opdiv-0.1.0/LICENSE

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

opdiv-0.1.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: opdiv
+Version: 0.1.0
+Summary: Molecular portfolio selection and diversity evaluation
+Author: Miroslav Lzicar
+License-Expression: MIT
+Project-URL: Repository, https://github.com/mireklzicar/opdiv
+Project-URL: Issues, https://github.com/mireklzicar/opdiv/issues
+Keywords: cheminformatics,diversity,portfolio,molecule-selection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: ortools<10,>=9.15
+Provides-Extra: chem
+Requires-Dist: rdkit>=2023.9; extra == "chem"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# OPDiv
+
+[![PyPI](https://img.shields.io/pypi/v/opdiv.svg)](https://pypi.org/project/opdiv/)
+
+Molecular portfolio selection and diversity evaluation.
+
+Choose exactly **k** candidates with the highest mean score while enforcing a
+pairwise similarity ceiling. Use the resulting mean to evaluate a screening or
+generative method's candidate archive.
+
+Implements **Optimal Portfolio Diversity (OPDiv)**, its score-ordered greedy
+approximation **GPDiv**, from
+*Measuring Diversity of Top-K Molecules as an Optimal Portfolio Selection Problem*
+by Miroslav Lžičař (preprint draft, September 2026).
+
+## Install
+
+Python 3.10 or newer:
+
+```bash
+pip install opdiv
+```
+
+For development, from this repository:
+
+```bash
+pip install -e '.[chem,dev]'
+```
+
+The core requires NumPy and OR-Tools. The optional `chem` extra adds RDKit for
+building Morgan/Tanimoto similarities from SMILES.
+
+## Select a portfolio
+
+```python
+from opdiv import select, opdiv, gpdiv
+
+# The paper's counterexample: A conflicts with B and C; B and C are compatible.
+scores = [16.0, 12.0, 11.0, 6.0]  # A, B, C, D; larger is better
+conflicts = [
+    [0, 1, 1, 0],
+    [1, 0, 0, 0],
+    [1, 0, 0, 0],
+    [0, 0, 0, 0],
+]
+
+result = select(scores, k=2, conflicts=conflicts)
+print(result.indices)  # (1, 2): B and C
+print(result.value)    # 11.5
+print(result.status)   # optimal
+
+# Metric-only calls also perform selection internally.
+print(opdiv(scores, k=2, conflicts=conflicts))  # 11.5
+print(gpdiv(scores, k=2, conflicts=conflicts))  # 11.0: A and D
+
+greedy = select(scores, k=2, conflicts=conflicts, method="greedy")
+```
+
+`indices` are zero-based input positions, sorted by descending score, then input
+position. Index a Python list with `[items[i] for i in result.indices]`, or a
+DataFrame with `df.iloc[list(result.indices)]`. Scores are **utilities**: for
+lower-is-better docking energies, pass their negatives.
+
+## From molecules or custom similarities
+
+Install RDKit support with `pip install 'opdiv[chem]'`.
+
+```python
+from opdiv import select, tanimoto_similarity
+
+smiles = ["CCO", "CCCO", "c1ccccc1", "CC(=O)O"]
+scores = [0.9, 0.8, 0.7, 0.6]
+similarities = tanimoto_similarity(smiles)  # Morgan radius 2, 2048 bits, no chirality
+
+result = select(scores, k=2, similarities=similarities, max_similarity=0.4)
+selected_smiles = [smiles[i] for i in result.indices]
+```
+
+Any finite symmetric similarity matrix works, including shape or electrostatic
+comparisons. A pair conflicts exactly when **similarity > max_similarity**;
+equality is allowed, and no numerical epsilon is added. The similarity diagonal
+is ignored. Asymmetric matrices must be explicitly symmetrized before use.
+
+Alternatively, supply a symmetric boolean/0–1 `conflicts` matrix with a false
+diagonal. For distances, construct conflicts with `distances < min_distance`
+and set the diagonal to false. Use `<=` if equality should conflict. With neither
+matrix, `select(scores, k)` returns ordinary top-k.
+
+Filter ineligible candidates and resolve molecular identity **before selection**.
+The SMILES helper rejects invalid/empty molecules and duplicate canonical
+isomeric SMILES; it does not normalize salts or tautomers. Matrix-based calls
+assume each row is a distinct eligible candidate.
+
+## Feasibility and bounds
+
+```python
+result = select(scores, k=2, similarities=similarities,
+                max_similarity=0.4, time_limit=10.0)
+print(result.status, result.value, result.upper_bound, result.gap)
+```
+
+| Status | Meaning |
+|---|---|
+| `optimal` | Optimum certified within the numerical tolerance below; inspect `gap`. |
+| `feasible` | Full portfolio found; its mean is a lower bound on OPDiv. |
+| `incomplete` | Greedy stopped short; another full portfolio may exist. |
+| `infeasible` | The requested capacity is proven infeasible. |
+| `unknown` | Search stopped without finding a full portfolio or proving infeasibility. |
+
+`value` is the mean of a full selection, or `None` when underfilled. A partial
+greedy result retains its indices, but has no GPDiv value at the requested k.
+`upper_bound` bounds the optimum; `gap` is the absolute difference from `value`.
+Neither repeating candidates nor relaxing the diversity threshold fills a result.
+
+`opdiv(...)` raises `MetricUndefinedError` unless optimality is established;
+`gpdiv(...)` raises it when its metric is undefined. The exception
+has a `.result` containing the selection and available bounds. Use `select(...)`
+when you want to inspect a time-limited result rather than require a scalar metric.
+
+Optimal selection uses [OR-Tools CP-SAT](https://developers.google.com/optimization/cp/cp_solver),
+with binary variables, exactly k selections, and one exclusion constraint per
+conflict edge. A complete greedy portfolio supplies a solver hint and an objective
+lower bound. One search worker and a fixed seed make runs reproducible within a
+solver version.
+
+Scores are centered and rescaled before conversion to integer coefficients at
+precision 1e-9 in normalized units. The largest k coefficient-rounding errors
+are included in the returned upper bound. `optimal` means CP-SAT proved the
+integer optimum and the original-score mean gap is at most 1e-8 times the
+centered score scale (the largest absolute centered score, or 1 for constant
+scores), subject to floating-point arithmetic. A small nonzero `gap` can remain
+due to rounding; extremely close portfolios can be indistinguishable at this
+precision. Returned `value` always uses the original scores.
+
+There is no default time limit; `time_limit` limits the solver only. On a stopped
+search, a complete greedy portfolio is retained if it beats the solver's candidate.
+Greedy ties follow input order. Equally optimal selections can differ between
+solver versions. Pairwise matrices require O(m²) memory; difficult conflict graphs
+can be expensive to optimize.
+
+This package uses the paper's CP-SAT backend and OPDiv/GPDiv definitions. It keeps
+a direct full-graph model; the experiment runner's clique compression, score-prefix
+relaxations, and benchmark pipeline are not included. Its normalized integer
+scaling also differs from the experiment runner's fixed score multiplier.
+For reproduction, use identical eligible candidates, row ordering, scores, and
+conflict graphs: experiment-specific threshold tolerances must be encoded in
+`conflicts` explicitly. The molecular helper matches the paper's non-chiral
+fingerprint settings; compute fingerprints from the original archived graphs
+when reproducing the archive experiments.
+
+## Development
+
+```bash
+python -m pytest
+ruff check .
+python -m build
+python -m twine check dist/*
+```
+
+Tests compare optimal results and rounding-aware bounds with exhaustive enumeration,
+exercise the paper's greedy failure, and cover threshold boundaries, negative
+utilities, time-limit outcomes, input validation, and optional molecular support.
+
+The source repository is [mireklzicar/opdiv](https://github.com/mireklzicar/opdiv);
+[Deep-MedChem/opdiv](https://github.com/Deep-MedChem/opdiv) is its organization fork.
+
+## Attribution
+
+The portfolio metrics and their molecular evaluation application are introduced
+in the paper above. The underlying graph optimization and score-ordered greedy
+algorithms are established methods; this package does not claim their invention.
+See the paper for the scientific formulation and prior work. MIT licensed.

opdiv-0.1.0/README.md

@@ -0,0 +1,172 @@
+# OPDiv
+
+[![PyPI](https://img.shields.io/pypi/v/opdiv.svg)](https://pypi.org/project/opdiv/)
+
+Molecular portfolio selection and diversity evaluation.
+
+Choose exactly **k** candidates with the highest mean score while enforcing a
+pairwise similarity ceiling. Use the resulting mean to evaluate a screening or
+generative method's candidate archive.
+
+Implements **Optimal Portfolio Diversity (OPDiv)**, its score-ordered greedy
+approximation **GPDiv**, from
+*Measuring Diversity of Top-K Molecules as an Optimal Portfolio Selection Problem*
+by Miroslav Lžičař (preprint draft, September 2026).
+
+## Install
+
+Python 3.10 or newer:
+
+```bash
+pip install opdiv
+```
+
+For development, from this repository:
+
+```bash
+pip install -e '.[chem,dev]'
+```
+
+The core requires NumPy and OR-Tools. The optional `chem` extra adds RDKit for
+building Morgan/Tanimoto similarities from SMILES.
+
+## Select a portfolio
+
+```python
+from opdiv import select, opdiv, gpdiv
+
+# The paper's counterexample: A conflicts with B and C; B and C are compatible.
+scores = [16.0, 12.0, 11.0, 6.0]  # A, B, C, D; larger is better
+conflicts = [
+    [0, 1, 1, 0],
+    [1, 0, 0, 0],
+    [1, 0, 0, 0],
+    [0, 0, 0, 0],
+]
+
+result = select(scores, k=2, conflicts=conflicts)
+print(result.indices)  # (1, 2): B and C
+print(result.value)    # 11.5
+print(result.status)   # optimal
+
+# Metric-only calls also perform selection internally.
+print(opdiv(scores, k=2, conflicts=conflicts))  # 11.5
+print(gpdiv(scores, k=2, conflicts=conflicts))  # 11.0: A and D
+
+greedy = select(scores, k=2, conflicts=conflicts, method="greedy")
+```
+
+`indices` are zero-based input positions, sorted by descending score, then input
+position. Index a Python list with `[items[i] for i in result.indices]`, or a
+DataFrame with `df.iloc[list(result.indices)]`. Scores are **utilities**: for
+lower-is-better docking energies, pass their negatives.
+
+## From molecules or custom similarities
+
+Install RDKit support with `pip install 'opdiv[chem]'`.
+
+```python
+from opdiv import select, tanimoto_similarity
+
+smiles = ["CCO", "CCCO", "c1ccccc1", "CC(=O)O"]
+scores = [0.9, 0.8, 0.7, 0.6]
+similarities = tanimoto_similarity(smiles)  # Morgan radius 2, 2048 bits, no chirality
+
+result = select(scores, k=2, similarities=similarities, max_similarity=0.4)
+selected_smiles = [smiles[i] for i in result.indices]
+```
+
+Any finite symmetric similarity matrix works, including shape or electrostatic
+comparisons. A pair conflicts exactly when **similarity > max_similarity**;
+equality is allowed, and no numerical epsilon is added. The similarity diagonal
+is ignored. Asymmetric matrices must be explicitly symmetrized before use.
+
+Alternatively, supply a symmetric boolean/0–1 `conflicts` matrix with a false
+diagonal. For distances, construct conflicts with `distances < min_distance`
+and set the diagonal to false. Use `<=` if equality should conflict. With neither
+matrix, `select(scores, k)` returns ordinary top-k.
+
+Filter ineligible candidates and resolve molecular identity **before selection**.
+The SMILES helper rejects invalid/empty molecules and duplicate canonical
+isomeric SMILES; it does not normalize salts or tautomers. Matrix-based calls
+assume each row is a distinct eligible candidate.
+
+## Feasibility and bounds
+
+```python
+result = select(scores, k=2, similarities=similarities,
+                max_similarity=0.4, time_limit=10.0)
+print(result.status, result.value, result.upper_bound, result.gap)
+```
+
+| Status | Meaning |
+|---|---|
+| `optimal` | Optimum certified within the numerical tolerance below; inspect `gap`. |
+| `feasible` | Full portfolio found; its mean is a lower bound on OPDiv. |
+| `incomplete` | Greedy stopped short; another full portfolio may exist. |
+| `infeasible` | The requested capacity is proven infeasible. |
+| `unknown` | Search stopped without finding a full portfolio or proving infeasibility. |
+
+`value` is the mean of a full selection, or `None` when underfilled. A partial
+greedy result retains its indices, but has no GPDiv value at the requested k.
+`upper_bound` bounds the optimum; `gap` is the absolute difference from `value`.
+Neither repeating candidates nor relaxing the diversity threshold fills a result.
+
+`opdiv(...)` raises `MetricUndefinedError` unless optimality is established;
+`gpdiv(...)` raises it when its metric is undefined. The exception
+has a `.result` containing the selection and available bounds. Use `select(...)`
+when you want to inspect a time-limited result rather than require a scalar metric.
+
+Optimal selection uses [OR-Tools CP-SAT](https://developers.google.com/optimization/cp/cp_solver),
+with binary variables, exactly k selections, and one exclusion constraint per
+conflict edge. A complete greedy portfolio supplies a solver hint and an objective
+lower bound. One search worker and a fixed seed make runs reproducible within a
+solver version.
+
+Scores are centered and rescaled before conversion to integer coefficients at
+precision 1e-9 in normalized units. The largest k coefficient-rounding errors
+are included in the returned upper bound. `optimal` means CP-SAT proved the
+integer optimum and the original-score mean gap is at most 1e-8 times the
+centered score scale (the largest absolute centered score, or 1 for constant
+scores), subject to floating-point arithmetic. A small nonzero `gap` can remain
+due to rounding; extremely close portfolios can be indistinguishable at this
+precision. Returned `value` always uses the original scores.
+
+There is no default time limit; `time_limit` limits the solver only. On a stopped
+search, a complete greedy portfolio is retained if it beats the solver's candidate.
+Greedy ties follow input order. Equally optimal selections can differ between
+solver versions. Pairwise matrices require O(m²) memory; difficult conflict graphs
+can be expensive to optimize.
+
+This package uses the paper's CP-SAT backend and OPDiv/GPDiv definitions. It keeps
+a direct full-graph model; the experiment runner's clique compression, score-prefix
+relaxations, and benchmark pipeline are not included. Its normalized integer
+scaling also differs from the experiment runner's fixed score multiplier.
+For reproduction, use identical eligible candidates, row ordering, scores, and
+conflict graphs: experiment-specific threshold tolerances must be encoded in
+`conflicts` explicitly. The molecular helper matches the paper's non-chiral
+fingerprint settings; compute fingerprints from the original archived graphs
+when reproducing the archive experiments.
+
+## Development
+
+```bash
+python -m pytest
+ruff check .
+python -m build
+python -m twine check dist/*
+```
+
+Tests compare optimal results and rounding-aware bounds with exhaustive enumeration,
+exercise the paper's greedy failure, and cover threshold boundaries, negative
+utilities, time-limit outcomes, input validation, and optional molecular support.
+
+The source repository is [mireklzicar/opdiv](https://github.com/mireklzicar/opdiv);
+[Deep-MedChem/opdiv](https://github.com/Deep-MedChem/opdiv) is its organization fork.
+
+## Attribution
+
+The portfolio metrics and their molecular evaluation application are introduced
+in the paper above. The underlying graph optimization and score-ordered greedy
+algorithms are established methods; this package does not claim their invention.
+See the paper for the scientific formulation and prior work. MIT licensed.

opdiv-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=77"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "opdiv"
+version = "0.1.0"
+description = "Molecular portfolio selection and diversity evaluation"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{name = "Miroslav Lzicar"}]
+keywords = ["cheminformatics", "diversity", "portfolio", "molecule-selection"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Science/Research",
+    "Programming Language :: Python :: 3",
+    "Topic :: Scientific/Engineering :: Chemistry",
+    "Typing :: Typed",
+]
+dependencies = ["numpy>=1.23", "ortools>=9.15,<10"]
+
+[project.optional-dependencies]
+chem = ["rdkit>=2023.9"]
+dev = ["pytest>=7", "build>=1.2", "twine>=5", "ruff>=0.6"]
+
+[project.urls]
+Repository = "https://github.com/mireklzicar/opdiv"
+Issues = "https://github.com/mireklzicar/opdiv/issues"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+opdiv = ["py.typed"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]

opdiv-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

opdiv-0.1.0/src/opdiv/__init__.py

@@ -0,0 +1,21 @@
+"""Molecular portfolio selection and diversity evaluation."""
+
+from ._core import (
+    MetricUndefinedError,
+    Portfolio,
+    gpdiv,
+    opdiv,
+    select,
+)
+from ._similarity import conflicts_from_similarity, tanimoto_similarity
+
+__version__ = "0.1.0"
+__all__ = [
+    "MetricUndefinedError",
+    "Portfolio",
+    "conflicts_from_similarity",
+    "gpdiv",
+    "opdiv",
+    "select",
+    "tanimoto_similarity",
+]

opdiv-0.1.0/src/opdiv/_core.py

@@ -0,0 +1,273 @@
+"""Fixed-cardinality portfolio objectives, independent of molecular representation."""
+
+from dataclasses import dataclass
+from typing import Literal
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from ortools.sat.python import cp_model
+
+from ._similarity import conflicts_from_similarity
+
+_OBJECTIVE_SCALE = 1_000_000_000
+_OPTIMALITY_TOLERANCE = 1e-8
+
+Status = Literal["optimal", "feasible", "infeasible", "incomplete", "unknown"]
+
+
+@dataclass(frozen=True)
+class Portfolio:
+    """Selection and its mean-utility bounds at the requested capacity.
+
+    ``indices`` refer to input rows, ordered by descending score, then input
+    index. ``value`` is None unless exactly k compatible candidates were found.
+    ``upper_bound`` bounds OPDiv, including integer-coefficient rounding error.
+    Optimality is numerical: the certified mean gap is at most 1e-8 times the
+    centered score scale, subject to floating-point arithmetic.
+    """
+
+    indices: tuple[int, ...]
+    k: int
+    value: float | None
+    upper_bound: float | None
+    status: Status
+
+    @property
+    def is_complete(self) -> bool:
+        return len(self.indices) == self.k
+
+    @property
+    def gap(self) -> float | None:
+        """Absolute gap in mean-utility units, or None without a full portfolio."""
+        if self.value is None or self.upper_bound is None:
+            return None
+        return max(0.0, self.upper_bound - self.value)
+
+
+class MetricUndefinedError(ValueError):
+    """No full portfolio or no proven optimum; inspect ``result`` for details."""
+
+    def __init__(self, metric: str, result: Portfolio):
+        self.result = result
+        super().__init__(
+            f"{metric} is unavailable (status={result.status}, "
+            f"selected={len(result.indices)}/{result.k}); use select() to inspect bounds"
+        )
+
+
+def _inputs(scores: ArrayLike, k: int) -> NDArray[np.float64]:
+    q = np.asarray(scores, dtype=float)
+    if q.ndim != 1 or not np.isfinite(q).all():
+        raise ValueError("scores must be a one-dimensional array of finite utilities")
+    if isinstance(k, bool) or not isinstance(k, (int, np.integer)) or k < 1:
+        raise ValueError("k must be a positive integer")
+    return q
+
+
+def _graph(
+    m: int,
+    conflicts: ArrayLike | None,
+    similarities: ArrayLike | None,
+    max_similarity: float | None,
+) -> NDArray[np.bool_]:
+    if similarities is not None:
+        if conflicts is not None or max_similarity is None:
+            raise ValueError("Supply similarities with max_similarity, or conflicts, not both")
+        a = conflicts_from_similarity(similarities, max_similarity)
+    else:
+        if max_similarity is not None:
+            raise ValueError("max_similarity requires similarities")
+        if conflicts is None:
+            return np.zeros((m, m), dtype=bool)
+        raw = np.asarray(conflicts)
+        if not np.isin(raw, [0, 1]).all():
+            raise ValueError("conflicts must contain only booleans or 0/1")
+        a = raw.astype(bool)
+    if a.shape != (m, m) or not np.array_equal(a, a.T):
+        raise ValueError("The pairwise matrix must be symmetric and match the number of scores")
+    if np.diag(a).any():
+        raise ValueError("conflicts must have a false diagonal")
+    return a
+
+
+def _result(q, picks, k, upper, status) -> Portfolio:
+    indices = tuple(sorted((int(i) for i in picks), key=lambda i: (-q[i], i)))
+    # Divide first to avoid overflowing the sum of finite scores.
+    value = float(np.sum(q[list(indices)] / k)) if len(indices) == k else None
+    return Portfolio(indices, int(k), value, upper, status)
+
+
+def _greedy(q, a, k) -> list[int]:
+    blocked = np.zeros(len(q), dtype=bool)
+    picks = []
+    for i in np.argsort(-q, kind="stable"):
+        if not blocked[i]:
+            picks.append(int(i))
+            blocked |= a[i]
+            blocked[i] = True
+            if len(picks) == k:
+                break
+    return picks
+
+
+def select(
+    scores: ArrayLike,
+    k: int,
+    *,
+    similarities: ArrayLike | None = None,
+    max_similarity: float | None = None,
+    conflicts: ArrayLike | None = None,
+    method: Literal["optimal", "greedy"] = "optimal",
+    time_limit: float | None = None,
+) -> Portfolio:
+    """Select exactly k candidates maximizing mean score under pairwise exclusion.
+
+    Larger scores are better: negate docking energies before calling. Supply
+    either a similarity matrix and ceiling (equality allowed), a boolean conflict
+    matrix, or neither for ordinary top-k. Candidates must already be eligible
+    and distinct; matrix inputs cannot establish molecular identity.
+
+    ``optimal`` uses OR-Tools CP-SAT optimization without a time limit
+    by default. ``time_limit`` limits solver seconds, excluding graph preparation.
+    Integer rounding is included in the returned upper bound. Optimality is
+    certified within 1e-8 times the centered score scale. A stopped search
+    returns a feasible lower bound if available. ``greedy`` scans by score with
+    input-order tie breaking;
+    underfilling does not establish infeasibility. Equally optimal portfolios may
+    differ across solver versions; returned indices are always score-sorted.
+    """
+    q = _inputs(scores, k)
+    a = _graph(len(q), conflicts, similarities, max_similarity)
+    if method not in ("optimal", "greedy"):
+        raise ValueError("method must be 'optimal' or 'greedy'")
+    if time_limit is not None:
+        if not np.isscalar(time_limit) or not np.isfinite(time_limit) or time_limit <= 0:
+            raise ValueError("time_limit must be positive and finite")
+        if method != "optimal":
+            raise ValueError("time_limit applies only to optimal selection")
+    if k > len(q):
+        return _result(q, [], k, None, "infeasible")
+    top = np.argsort(-q, kind="stable")[:k]
+    upper = float(np.sum(q[top] / k))
+    if not a[np.ix_(top, top)].any():
+        return _result(q, top, k, upper, "optimal")
+    picks = _greedy(q, a, k)
+    if method == "greedy":
+        return _result(q, picks, k, upper, "feasible" if len(picks) == k else "incomplete")
+
+    # Center/rescale before integer conversion so offsets and units do not
+    # erase score differences. At fixed k this preserves the exact objective.
+    center = float(np.max(q) / 2 + np.min(q) / 2)
+    centered = q - center
+    scale = float(np.max(np.abs(centered))) or 1.0
+    normalized = centered / scale
+    weights = np.rint(normalized * _OBJECTIVE_SCALE).astype(np.int64)
+    # For ANY size-k set, the largest k coefficient errors bound mean error.
+    errors = np.abs(normalized - weights / _OBJECTIVE_SCALE)
+    rounding_error = float(np.sum(np.sort(errors)[-k:] / k))
+
+    model = cp_model.CpModel()
+    x = [model.new_bool_var(f"x{i}") for i in range(len(q))]
+    model.add(sum(x) == k)
+    ii, jj = np.where(np.triu(a, 1))
+    for i, j in zip(ii, jj, strict=True):
+        model.add_at_most_one(x[i], x[j])
+    objective = sum(int(w) * var for w, var in zip(weights, x, strict=True))
+    model.maximize(objective)
+    if len(picks) == k:
+        chosen = set(picks)
+        model.add(objective >= sum(int(weights[i]) for i in picks))
+        for i, var in enumerate(x):
+            model.add_hint(var, int(i in chosen))
+    else:
+        picks = []
+
+    solver = cp_model.CpSolver()
+    solver.parameters.num_search_workers = 1
+    solver.parameters.random_seed = 20260914
+    solver.parameters.relative_gap_limit = 0
+    solver.parameters.absolute_gap_limit = 0
+    if time_limit is not None:
+        solver.parameters.max_time_in_seconds = float(time_limit)
+    code = solver.solve(model)
+    if code == cp_model.INFEASIBLE:
+        if picks:
+            raise RuntimeError("Solver reported infeasibility despite a feasible greedy portfolio")
+        return _result(q, [], k, None, "infeasible")
+    if code not in (cp_model.OPTIMAL, cp_model.FEASIBLE, cp_model.UNKNOWN):
+        raise RuntimeError(f"Portfolio solver failed: {solver.solution_info()}")
+
+    status = "feasible" if picks else "unknown"
+    if code in (cp_model.OPTIMAL, cp_model.FEASIBLE):
+        candidate = [i for i, var in enumerate(x) if solver.value(var)]
+        if len(candidate) != k or a[np.ix_(candidate, candidate)].any():
+            raise RuntimeError("Solver returned an invalid portfolio")
+        if not picks or np.sum(normalized[candidate]) > np.sum(normalized[picks]):
+            picks = candidate
+        # UNKNOWN can expose an uninitialized solver bound; retain top-k then.
+        normalized_upper = (
+            solver.best_objective_bound / (_OBJECTIVE_SCALE * k) + rounding_error
+        )
+        # Small outward allowance for arithmetic in scaling and bound conversion.
+        normalized_upper += 16 * np.finfo(float).eps
+        with np.errstate(over="ignore"):
+            upper = min(upper, float(normalized_upper * scale + center))
+        value = float(np.sum(q[picks] / k))
+        upper = max(upper, value)
+        normalized_gap = normalized_upper - float(np.sum(normalized[picks] / k))
+        status = (
+            "optimal"
+            if code == cp_model.OPTIMAL and normalized_gap <= _OPTIMALITY_TOLERANCE
+            else "feasible"
+        )
+    return _result(q, picks, k, upper, status)
+
+
+def opdiv(
+    scores: ArrayLike,
+    k: int,
+    *,
+    similarities: ArrayLike | None = None,
+    max_similarity: float | None = None,
+    conflicts: ArrayLike | None = None,
+    time_limit: float | None = None,
+) -> float:
+    """Optimal Portfolio Diversity: the best feasible size-k mean utility.
+
+    Raise MetricUndefinedError for infeasibility or an unproven optimum.
+    Optimality uses the numerical tolerance documented by select().
+    The exception's result retains any feasible portfolio and its bounds.
+    """
+    result = select(
+        scores,
+        k,
+        similarities=similarities,
+        max_similarity=max_similarity,
+        conflicts=conflicts,
+        time_limit=time_limit,
+    )
+    if result.status != "optimal" or result.value is None:
+        raise MetricUndefinedError("OPDiv", result)
+    return result.value
+
+
+def gpdiv(
+    scores: ArrayLike,
+    k: int,
+    *,
+    similarities: ArrayLike | None = None,
+    max_similarity: float | None = None,
+    conflicts: ArrayLike | None = None,
+) -> float:
+    """Greedy Portfolio Diversity; raise MetricUndefinedError if underfilled."""
+    result = select(
+        scores,
+        k,
+        similarities=similarities,
+        max_similarity=max_similarity,
+        conflicts=conflicts,
+        method="greedy",
+    )
+    if result.value is None:
+        raise MetricUndefinedError("GPDiv", result)
+    return result.value

opdiv-0.1.0/src/opdiv/_similarity.py

@@ -0,0 +1,65 @@
+"""Pairwise conflict graphs and optional molecular fingerprints."""
+
+from collections.abc import Sequence
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+
+def conflicts_from_similarity(similarities: ArrayLike, max_similarity: float) -> NDArray[np.bool_]:
+    """Build a graph with an edge exactly when s(i, j) > max_similarity.
+
+    Equality is compatible. Require a finite, exactly symmetric square matrix;
+    the diagonal is ignored. Similarities need not be in [0, 1]. No implicit
+    symmetrization or threshold tolerance is applied.
+    """
+    s = np.asarray(similarities, dtype=float)
+    if s.ndim != 2 or s.shape[0] != s.shape[1]:
+        raise ValueError("similarities must be a square matrix")
+    if not np.isfinite(s).all() or not np.array_equal(s, s.T):
+        raise ValueError("similarities must be finite and symmetric")
+    if not np.isscalar(max_similarity) or not np.isfinite(max_similarity):
+        raise ValueError("max_similarity must be finite")
+    graph = s > max_similarity
+    np.fill_diagonal(graph, False)
+    return graph
+
+
+def tanimoto_similarity(
+    smiles: Sequence[str], *, radius: int = 2, n_bits: int = 2048
+) -> NDArray[np.float64]:
+    """Morgan bit-fingerprint Tanimoto matrix; requires ``opdiv[chem]``.
+
+    Uses no chirality, matching the paper, and preserves input order. Invalid, empty, or duplicate
+    canonical isomeric SMILES raise ValueError. No salt/tautomer normalization
+    is performed; establish your molecular identity policy before calling.
+    """
+    try:
+        from rdkit import Chem, DataStructs
+        from rdkit.Chem import rdFingerprintGenerator
+    except ImportError as exc:
+        raise ImportError("Install molecular support with: pip install 'opdiv[chem]'") from exc
+
+    if isinstance(smiles, str):
+        raise ValueError("smiles must be a sequence of SMILES strings")
+    for name, value, minimum in [("radius", radius, 0), ("n_bits", n_bits, 1)]:
+        if isinstance(value, bool) or not isinstance(value, (int, np.integer)) or value < minimum:
+            raise ValueError(f"{name} must be an integer >= {minimum}")
+    generator = rdFingerprintGenerator.GetMorganGenerator(
+        radius=int(radius), fpSize=int(n_bits), includeChirality=False
+    )
+    fingerprints, seen = [], set()
+    for i, text in enumerate(smiles):
+        mol = Chem.MolFromSmiles(text) if isinstance(text, str) and text.strip() else None
+        if mol is None or mol.GetNumAtoms() == 0:
+            raise ValueError(f"Invalid or empty SMILES at index {i}: {text!r}")
+        identity = Chem.MolToSmiles(mol, isomericSmiles=True)
+        if identity in seen:
+            raise ValueError(f"Duplicate molecule at index {i}: {text!r}")
+        seen.add(identity)
+        fingerprints.append(generator.GetFingerprint(mol))
+    matrix = np.eye(len(fingerprints), dtype=float)
+    for i in range(1, len(fingerprints)):
+        matrix[i, :i] = DataStructs.BulkTanimotoSimilarity(fingerprints[i], fingerprints[:i])
+        matrix[:i, i] = matrix[i, :i]
+    return matrix

opdiv-0.1.0/src/opdiv.egg-info/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.4
+Name: opdiv
+Version: 0.1.0
+Summary: Molecular portfolio selection and diversity evaluation
+Author: Miroslav Lzicar
+License-Expression: MIT
+Project-URL: Repository, https://github.com/mireklzicar/opdiv
+Project-URL: Issues, https://github.com/mireklzicar/opdiv/issues
+Keywords: cheminformatics,diversity,portfolio,molecule-selection
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Chemistry
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.23
+Requires-Dist: ortools<10,>=9.15
+Provides-Extra: chem
+Requires-Dist: rdkit>=2023.9; extra == "chem"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+# OPDiv
+
+[![PyPI](https://img.shields.io/pypi/v/opdiv.svg)](https://pypi.org/project/opdiv/)
+
+Molecular portfolio selection and diversity evaluation.
+
+Choose exactly **k** candidates with the highest mean score while enforcing a
+pairwise similarity ceiling. Use the resulting mean to evaluate a screening or
+generative method's candidate archive.
+
+Implements **Optimal Portfolio Diversity (OPDiv)**, its score-ordered greedy
+approximation **GPDiv**, from
+*Measuring Diversity of Top-K Molecules as an Optimal Portfolio Selection Problem*
+by Miroslav Lžičař (preprint draft, September 2026).
+
+## Install
+
+Python 3.10 or newer:
+
+```bash
+pip install opdiv
+```
+
+For development, from this repository:
+
+```bash
+pip install -e '.[chem,dev]'
+```
+
+The core requires NumPy and OR-Tools. The optional `chem` extra adds RDKit for
+building Morgan/Tanimoto similarities from SMILES.
+
+## Select a portfolio
+
+```python
+from opdiv import select, opdiv, gpdiv
+
+# The paper's counterexample: A conflicts with B and C; B and C are compatible.
+scores = [16.0, 12.0, 11.0, 6.0]  # A, B, C, D; larger is better
+conflicts = [
+    [0, 1, 1, 0],
+    [1, 0, 0, 0],
+    [1, 0, 0, 0],
+    [0, 0, 0, 0],
+]
+
+result = select(scores, k=2, conflicts=conflicts)
+print(result.indices)  # (1, 2): B and C
+print(result.value)    # 11.5
+print(result.status)   # optimal
+
+# Metric-only calls also perform selection internally.
+print(opdiv(scores, k=2, conflicts=conflicts))  # 11.5
+print(gpdiv(scores, k=2, conflicts=conflicts))  # 11.0: A and D
+
+greedy = select(scores, k=2, conflicts=conflicts, method="greedy")
+```
+
+`indices` are zero-based input positions, sorted by descending score, then input
+position. Index a Python list with `[items[i] for i in result.indices]`, or a
+DataFrame with `df.iloc[list(result.indices)]`. Scores are **utilities**: for
+lower-is-better docking energies, pass their negatives.
+
+## From molecules or custom similarities
+
+Install RDKit support with `pip install 'opdiv[chem]'`.
+
+```python
+from opdiv import select, tanimoto_similarity
+
+smiles = ["CCO", "CCCO", "c1ccccc1", "CC(=O)O"]
+scores = [0.9, 0.8, 0.7, 0.6]
+similarities = tanimoto_similarity(smiles)  # Morgan radius 2, 2048 bits, no chirality
+
+result = select(scores, k=2, similarities=similarities, max_similarity=0.4)
+selected_smiles = [smiles[i] for i in result.indices]
+```
+
+Any finite symmetric similarity matrix works, including shape or electrostatic
+comparisons. A pair conflicts exactly when **similarity > max_similarity**;
+equality is allowed, and no numerical epsilon is added. The similarity diagonal
+is ignored. Asymmetric matrices must be explicitly symmetrized before use.
+
+Alternatively, supply a symmetric boolean/0–1 `conflicts` matrix with a false
+diagonal. For distances, construct conflicts with `distances < min_distance`
+and set the diagonal to false. Use `<=` if equality should conflict. With neither
+matrix, `select(scores, k)` returns ordinary top-k.
+
+Filter ineligible candidates and resolve molecular identity **before selection**.
+The SMILES helper rejects invalid/empty molecules and duplicate canonical
+isomeric SMILES; it does not normalize salts or tautomers. Matrix-based calls
+assume each row is a distinct eligible candidate.
+
+## Feasibility and bounds
+
+```python
+result = select(scores, k=2, similarities=similarities,
+                max_similarity=0.4, time_limit=10.0)
+print(result.status, result.value, result.upper_bound, result.gap)
+```
+
+| Status | Meaning |
+|---|---|
+| `optimal` | Optimum certified within the numerical tolerance below; inspect `gap`. |
+| `feasible` | Full portfolio found; its mean is a lower bound on OPDiv. |
+| `incomplete` | Greedy stopped short; another full portfolio may exist. |
+| `infeasible` | The requested capacity is proven infeasible. |
+| `unknown` | Search stopped without finding a full portfolio or proving infeasibility. |
+
+`value` is the mean of a full selection, or `None` when underfilled. A partial
+greedy result retains its indices, but has no GPDiv value at the requested k.
+`upper_bound` bounds the optimum; `gap` is the absolute difference from `value`.
+Neither repeating candidates nor relaxing the diversity threshold fills a result.
+
+`opdiv(...)` raises `MetricUndefinedError` unless optimality is established;
+`gpdiv(...)` raises it when its metric is undefined. The exception
+has a `.result` containing the selection and available bounds. Use `select(...)`
+when you want to inspect a time-limited result rather than require a scalar metric.
+
+Optimal selection uses [OR-Tools CP-SAT](https://developers.google.com/optimization/cp/cp_solver),
+with binary variables, exactly k selections, and one exclusion constraint per
+conflict edge. A complete greedy portfolio supplies a solver hint and an objective
+lower bound. One search worker and a fixed seed make runs reproducible within a
+solver version.
+
+Scores are centered and rescaled before conversion to integer coefficients at
+precision 1e-9 in normalized units. The largest k coefficient-rounding errors
+are included in the returned upper bound. `optimal` means CP-SAT proved the
+integer optimum and the original-score mean gap is at most 1e-8 times the
+centered score scale (the largest absolute centered score, or 1 for constant
+scores), subject to floating-point arithmetic. A small nonzero `gap` can remain
+due to rounding; extremely close portfolios can be indistinguishable at this
+precision. Returned `value` always uses the original scores.
+
+There is no default time limit; `time_limit` limits the solver only. On a stopped
+search, a complete greedy portfolio is retained if it beats the solver's candidate.
+Greedy ties follow input order. Equally optimal selections can differ between
+solver versions. Pairwise matrices require O(m²) memory; difficult conflict graphs
+can be expensive to optimize.
+
+This package uses the paper's CP-SAT backend and OPDiv/GPDiv definitions. It keeps
+a direct full-graph model; the experiment runner's clique compression, score-prefix
+relaxations, and benchmark pipeline are not included. Its normalized integer
+scaling also differs from the experiment runner's fixed score multiplier.
+For reproduction, use identical eligible candidates, row ordering, scores, and
+conflict graphs: experiment-specific threshold tolerances must be encoded in
+`conflicts` explicitly. The molecular helper matches the paper's non-chiral
+fingerprint settings; compute fingerprints from the original archived graphs
+when reproducing the archive experiments.
+
+## Development
+
+```bash
+python -m pytest
+ruff check .
+python -m build
+python -m twine check dist/*
+```
+
+Tests compare optimal results and rounding-aware bounds with exhaustive enumeration,
+exercise the paper's greedy failure, and cover threshold boundaries, negative
+utilities, time-limit outcomes, input validation, and optional molecular support.
+
+The source repository is [mireklzicar/opdiv](https://github.com/mireklzicar/opdiv);
+[Deep-MedChem/opdiv](https://github.com/Deep-MedChem/opdiv) is its organization fork.
+
+## Attribution
+
+The portfolio metrics and their molecular evaluation application are introduced
+in the paper above. The underlying graph optimization and score-ordered greedy
+algorithms are established methods; this package does not claim their invention.
+See the paper for the scientific formulation and prior work. MIT licensed.

opdiv-0.1.0/src/opdiv.egg-info/SOURCES.txt

@@ -0,0 +1,14 @@
+LICENSE
+README.md
+pyproject.toml
+src/opdiv/__init__.py
+src/opdiv/_core.py
+src/opdiv/_similarity.py
+src/opdiv/py.typed
+src/opdiv.egg-info/PKG-INFO
+src/opdiv.egg-info/SOURCES.txt
+src/opdiv.egg-info/dependency_links.txt
+src/opdiv.egg-info/requires.txt
+src/opdiv.egg-info/top_level.txt
+tests/test_core.py
+tests/test_similarity.py

opdiv-0.1.0/src/opdiv.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

opdiv-0.1.0/src/opdiv.egg-info/requires.txt

@@ -0,0 +1,11 @@
+numpy>=1.23
+ortools<10,>=9.15
+
+[chem]
+rdkit>=2023.9
+
+[dev]
+pytest>=7
+build>=1.2
+twine>=5
+ruff>=0.6

opdiv-0.1.0/src/opdiv.egg-info/top_level.txt

@@ -0,0 +1 @@
+opdiv

opdiv-0.1.0/tests/test_core.py

@@ -0,0 +1,195 @@
+from itertools import combinations
+from types import SimpleNamespace
+
+import numpy as np
+import pytest
+from ortools.sat.python import cp_model
+
+from opdiv import MetricUndefinedError, gpdiv, opdiv, select
+
+
+def graph():
+    return np.array([[0, 1, 1, 0], [1, 0, 0, 0], [1, 0, 0, 0], [0, 0, 0, 0]], bool)
+
+
+def test_paper_counterexample():
+    scores = [16, 12, 11, 6]
+    result = select(scores, 2, conflicts=graph())
+    assert result.indices == (1, 2)
+    assert result.status == "optimal"
+    assert result.is_complete
+    assert result.gap == pytest.approx(0)
+    assert opdiv(scores, 2, conflicts=graph()) == 11.5
+    assert gpdiv(scores, 2, conflicts=graph()) == 11
+
+
+def test_greedy_underfill_is_not_infeasibility():
+    a = graph()[:3, :3]
+    greedy = select([16, 12, 11], 2, conflicts=a, method="greedy")
+    assert greedy.status == "incomplete"
+    assert greedy.indices == (0,)
+    assert greedy.value is None and greedy.gap is None
+    assert not greedy.is_complete
+    with pytest.raises(MetricUndefinedError) as exc:
+        gpdiv([16, 12, 11], 2, conflicts=a)
+    assert exc.value.result == greedy
+    assert opdiv([16, 12, 11], 2, conflicts=a) == 11.5
+
+
+@pytest.mark.parametrize("seed", range(12))
+def test_optimum_and_bounds_against_exhaustive_enumeration(seed):
+    rng = np.random.default_rng(seed)
+    q = rng.normal(size=9)
+    a = np.triu(rng.random((9, 9)) < 0.45, 1)
+    a |= a.T
+    for k in (1, 3, 6, 9):
+        values = [
+            float(q[list(s)].mean()) for s in combinations(range(9), k) if not a[np.ix_(s, s)].any()
+        ]
+        result = select(q, k, conflicts=a)
+        if not values:
+            assert result.status == "infeasible"
+            assert result.value is None and result.upper_bound is None
+        else:
+            optimum = max(values)
+            assert result.status == "optimal"
+            assert result.value == pytest.approx(optimum)
+            assert result.upper_bound >= optimum - 1e-8
+            assert result.value <= optimum + 1e-8
+            assert len(set(result.indices)) == k
+            assert not a[np.ix_(result.indices, result.indices)].any()
+
+
+@pytest.mark.parametrize("scores,k", [([], 1), ([1], 2)])
+def test_not_enough_candidates(scores, k):
+    assert select(scores, k).status == "infeasible"
+    with pytest.raises(MetricUndefinedError):
+        opdiv(scores, k)
+
+
+def test_negative_scores_and_stable_ties():
+    assert select([-4, -2, -2, -8], 3).indices == (1, 2, 0)
+    assert opdiv([-4, -2, -2, -8], 3) == pytest.approx(-8 / 3)
+
+
+@pytest.mark.parametrize("scale,offset", [(1e-12, 0), (1e-3, 1e9), (1e6, -1e12)])
+def test_positive_affine_score_transform_preserves_selection(scale, offset):
+    q = np.array([16, 12, 11, 6]) * scale + offset
+    result = select(q, 2, conflicts=graph())
+    assert result.indices == (1, 2)
+    assert result.value == pytest.approx(float(q[[1, 2]].mean()))
+
+
+def mock_solver(monkeypatch, code, selected=(), bound=0):
+    class Solver:
+        parameters = SimpleNamespace()
+        best_objective_bound = bound
+
+        def solve(self, model):
+            return code
+
+        def value(self, var):
+            return var.index in selected
+
+        def solution_info(self):
+            return "mock model error"
+
+    monkeypatch.setattr("opdiv._core.cp_model.CpSolver", Solver)
+
+
+def test_timeout_retains_greedy_and_refuses_scalar_metric(monkeypatch):
+    mock_solver(monkeypatch, cp_model.UNKNOWN)
+    result = select([16, 12, 11, 6], 2, conflicts=graph(), time_limit=0.001)
+    assert result.status == "feasible"
+    assert result.indices == (0, 3)
+    assert result.value == 11 and result.upper_bound == 14
+    with pytest.raises(MetricUndefinedError) as exc:
+        opdiv([16, 12, 11, 6], 2, conflicts=graph(), time_limit=0.001)
+    assert exc.value.result == result
+    unknown = select([16, 12, 11], 2, conflicts=graph()[:3, :3], time_limit=0.001)
+    assert unknown.status == "unknown"
+    assert unknown.value is None and unknown.upper_bound == 14
+
+
+def test_timeout_with_solver_incumbent_and_bound(monkeypatch):
+    mock_solver(monkeypatch, cp_model.FEASIBLE, selected=(1, 2), bound=400_000_000)
+    result = select([16, 12, 11, 6], 2, conflicts=graph(), time_limit=0.001)
+    assert result.status == "feasible"
+    assert result.value == 11.5
+    assert result.upper_bound == pytest.approx(12)
+    assert result.gap == pytest.approx(0.5)
+
+
+def test_rejects_invalid_solver_portfolio(monkeypatch):
+    mock_solver(monkeypatch, cp_model.OPTIMAL, selected=(0, 1))
+    with pytest.raises(RuntimeError, match="invalid portfolio"):
+        select([16, 12, 11, 6], 2, conflicts=graph())
+
+
+@pytest.mark.parametrize(
+    "scores,k,kwargs",
+    [
+        ([1, np.nan], 1, {}),
+        ([[1, 2]], 1, {}),
+        ([1, 2], 0, {}),
+        ([1, 2], True, {}),
+        ([1, 2], 1.5, {}),
+        ([1, 2], 1, {"conflicts": [[0, 1], [0, 0]]}),
+        ([1, 2], 1, {"conflicts": [[1, 0], [0, 0]]}),
+        ([1, 2], 1, {"conflicts": [[0, 0.5], [0.5, 0]]}),
+        ([1, 2], 1, {"similarities": np.eye(3), "max_similarity": 0.5}),
+        ([1, 2], 1, {"similarities": np.eye(2)}),
+        ([1, 2], 1, {"max_similarity": 0.5}),
+        ([1, 2], 1, {"method": "typo"}),
+        ([1, 2], 1, {"time_limit": -1}),
+        ([1, 2], 1, {"time_limit": np.nan}),
+        ([1, 2], 1, {"time_limit": 1, "method": "greedy"}),
+        (
+            [1, 2],
+            1,
+            {"similarities": np.eye(2), "max_similarity": 0.5, "conflicts": np.zeros((2, 2))},
+        ),
+    ],
+)
+def test_invalid_inputs(scores, k, kwargs):
+    with pytest.raises(ValueError):
+        select(scores, k, **kwargs)
+
+
+@pytest.mark.parametrize("seed", range(12))
+def test_rounding_bounds_cover_original_float_optimum(seed):
+    rng = np.random.default_rng(seed)
+    q = rng.uniform(-1, 1, 8)
+    a = np.triu(rng.random((8, 8)) < 0.3, 1)
+    a |= a.T
+    k = 3
+    feasible = [q[list(s)].mean() for s in combinations(range(8), k) if not a[np.ix_(s, s)].any()]
+    result = select(q, k, conflicts=a)
+    if feasible:
+        optimum = max(feasible)
+        assert result.value <= optimum + 1e-14
+        assert result.upper_bound >= optimum - 1e-14
+        assert result.gap <= 1e-8 * np.ptp(q)
+
+
+def test_integer_optimum_does_not_hide_rounding_gap(monkeypatch):
+    # Both portfolios tie after integer rounding; B,C have better real utility.
+    q = [1, 0.75, 0.75000000001, 0.5]
+    mock_solver(monkeypatch, cp_model.OPTIMAL, selected=(0, 3), bound=0)
+    result = select(q, 2, conflicts=graph())
+    assert result.value == 0.75
+    assert result.upper_bound >= np.mean(q[1:3])
+    assert result.gap > 0
+
+
+def test_model_errors_are_not_reported_as_infeasibility(monkeypatch):
+    mock_solver(monkeypatch, cp_model.MODEL_INVALID)
+    with pytest.raises(RuntimeError, match="mock model error"):
+        select([16, 12, 11, 6], 2, conflicts=graph())
+
+
+def test_public_api_contains_only_pairwise_metrics():
+    import opdiv as package
+
+    assert not hasattr(package, "cpdiv")
+    assert not hasattr(package, "select_clusters")

opdiv-0.1.0/tests/test_similarity.py

@@ -0,0 +1,59 @@
+import numpy as np
+import pytest
+
+from opdiv import conflicts_from_similarity, opdiv, select, tanimoto_similarity
+
+
+def test_threshold_equality_and_adjacent_float():
+    s = np.array([[1, 0.7], [0.7, 1]])
+    original = s.copy()
+    assert not conflicts_from_similarity(s, 0.7).any()
+    assert opdiv([2, 1], 2, similarities=s, max_similarity=0.7) == 1.5
+    threshold = np.nextafter(0.7, -np.inf)
+    assert select([2, 1], 2, similarities=s, max_similarity=threshold).status == "infeasible"
+    np.testing.assert_array_equal(s, original)
+
+
+@pytest.mark.parametrize(
+    "matrix,threshold",
+    [
+        ([[1, 0.2], [0.3, 1]], 0.5),
+        ([[1, np.nan], [np.nan, 1]], 0.5),
+        ([[1, 0]], 0.5),
+        (np.eye(2), np.inf),
+    ],
+)
+def test_invalid_similarity(matrix, threshold):
+    with pytest.raises(ValueError):
+        conflicts_from_similarity(matrix, threshold)
+
+
+def test_morgan_tanimoto_matches_rdkit():
+    pytest.importorskip("rdkit")
+    from rdkit import Chem, DataStructs
+    from rdkit.Chem import rdFingerprintGenerator
+
+    smiles = ["CCO", "CCCO", "c1ccccc1", "CC(=O)O"]
+    matrix = tanimoto_similarity(smiles)
+    generator = rdFingerprintGenerator.GetMorganGenerator(
+        radius=2, fpSize=2048, includeChirality=False
+    )
+    fps = [generator.GetFingerprint(Chem.MolFromSmiles(s)) for s in smiles]
+    for i in range(len(smiles)):
+        for j in range(len(smiles)):
+            assert matrix[i, j] == DataStructs.TanimotoSimilarity(fps[i], fps[j])
+    assert select([0.9, 0.8, 0.7, 0.6], 2, similarities=matrix, max_similarity=0.4).is_complete
+    assert tanimoto_similarity([]).shape == (0, 0)
+
+
+@pytest.mark.parametrize("smiles", [["CCO", "OCC"], [""], ["invalid"], "CCO"])
+def test_invalid_molecules(smiles):
+    pytest.importorskip("rdkit")
+    with pytest.raises(ValueError):
+        tanimoto_similarity(smiles)
+
+
+def test_morgan_ignores_chirality_as_in_paper():
+    pytest.importorskip("rdkit")
+    s = tanimoto_similarity(["C[C@H](O)F", "C[C@@H](O)F"])
+    assert s[0, 1] == 1.0