pyotc 0.2.2__tar.gz → 0.3.0__tar.gz

{pyotc-0.2.2 → pyotc-0.3.0}/.github/workflows/build_and_publish.yml

@@ -10,11 +10,8 @@ name: build and publish
 
 on:
   release:
-    types: [published]
+    types: [published, prereleased]
   workflow_dispatch:
-  push:
-    branches:
-      - '77-fix-pypi-upload'
 
 permissions:
   contents: read

{pyotc-0.2.2 → pyotc-0.3.0}/CHANGELOG.md

@@ -7,6 +7,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0] - 2026-02-03
+* Implement public api
+* Fix and improve codecov test coverage
+* Update instructions for install
+
 ## [0.2.2] - 2025-10-10
 * Add github actions build wheels and upload them to pypi.
 

pyotc-0.3.0/PKG-INFO

@@ -0,0 +1,90 @@
+Metadata-Version: 2.4
+Name: pyotc
+Version: 0.3.0
+Summary: Perform optimal transition coupling (OTC) in python.
+Author: Jay Hineman, Yuning Pan, Bongsoo Yi
+License: MIT license
+License-File: AUTHORS.rst
+License-File: LICENSE
+Requires-Python: >=3.10
+Requires-Dist: matplotlib>=3.10.0
+Requires-Dist: networkx>=3.4.2
+Requires-Dist: numpy>=2.2.1
+Requires-Dist: pot>=0.9.5
+Description-Content-Type: text/markdown
+
+# pyotc
+[![codecov](https://codecov.io/github/pyotc/pyotc/graph/badge.svg?token=52QPNW0AP7)](https://codecov.io/github/pyotc/pyotc)
+
+A python implementations of optimal transport coupling algorithms.
+
+## Documentation
+Find sphinx documentation [here](https://pyotc.github.io/pyotc/).
+
+## Installation
+
+We expect `pyotc` to be pip-installable across all platforms. 
+
+
+### 1. Install from pypi (Recommended)
+
+```bash
+pip install pyotc
+```
+- Note: `pyotc` requires Python 3.10 or above.
+
+### 2. Install from github
+
+```bash
+pip install https://github.com/pyotc/pyotc.git
+```
+
+### 3. Install for Development
+We test in venvs provided by [uv](https://docs.astral.sh/uv/) via [nox](https://nox.thea.codes/en/stable/usage.html#changing-the-sessions-default-backend). It's helpful, but not strictly necessary to do the same.
+
+```bash
+git clone https://github.com/pyotc/pyotc.git
+cd pyotc
+pip install -e .
+```
+
+### `uv` workflow
+Install the [uv tool](https://docs.astral.sh/uv/getting-started/installation/). Then
+
+```bash
+git clone https://github.com/pyotc/pyotc.git
+cd pyotc
+uv sync
+uv pip install -e .
+```
+
+To verify your installation, run
+```bash
+uv run pytest
+```
+
+## Run Tests
+With a `uv` setup one can simply
+```bash
+uv run pytest
+```
+Otherwise, in `pip` installed context with deps met, `pytest` should behave as expected.
+
+## Contributing
+Guidelines for contribution to `pyotc` are provided in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Changelog
+A summary of changes and guide to versioning are recoreded in [CHANGELOG.md](./CHANGELOG.md).
+
+## Citing this Repository
+If you wish to cite our work, please use the following BibTeX code:
+```bibtex
+@article{yi2025alignment,
+  title={Alignment and comparison of directed networks via transition couplings of random walks},
+  author={Yi, Bongsoo and O'Connor, Kevin and McGoff, Kevin and Nobel, Andrew B},
+  journal={Journal of the Royal Statistical Society Series B: Statistical Methodology},
+  pages={qkae085},
+  year={2024},
+  doi = {10.1093/jrsssb/qkae085}
+}
+```

pyotc-0.3.0/README.md

@@ -0,0 +1,75 @@
+# pyotc
+[![codecov](https://codecov.io/github/pyotc/pyotc/graph/badge.svg?token=52QPNW0AP7)](https://codecov.io/github/pyotc/pyotc)
+
+A python implementations of optimal transport coupling algorithms.
+
+## Documentation
+Find sphinx documentation [here](https://pyotc.github.io/pyotc/).
+
+## Installation
+
+We expect `pyotc` to be pip-installable across all platforms. 
+
+
+### 1. Install from pypi (Recommended)
+
+```bash
+pip install pyotc
+```
+- Note: `pyotc` requires Python 3.10 or above.
+
+### 2. Install from github
+
+```bash
+pip install https://github.com/pyotc/pyotc.git
+```
+
+### 3. Install for Development
+We test in venvs provided by [uv](https://docs.astral.sh/uv/) via [nox](https://nox.thea.codes/en/stable/usage.html#changing-the-sessions-default-backend). It's helpful, but not strictly necessary to do the same.
+
+```bash
+git clone https://github.com/pyotc/pyotc.git
+cd pyotc
+pip install -e .
+```
+
+### `uv` workflow
+Install the [uv tool](https://docs.astral.sh/uv/getting-started/installation/). Then
+
+```bash
+git clone https://github.com/pyotc/pyotc.git
+cd pyotc
+uv sync
+uv pip install -e .
+```
+
+To verify your installation, run
+```bash
+uv run pytest
+```
+
+## Run Tests
+With a `uv` setup one can simply
+```bash
+uv run pytest
+```
+Otherwise, in `pip` installed context with deps met, `pytest` should behave as expected.
+
+## Contributing
+Guidelines for contribution to `pyotc` are provided in [CONTRIBUTING.md](./CONTRIBUTING.md).
+
+## Changelog
+A summary of changes and guide to versioning are recoreded in [CHANGELOG.md](./CHANGELOG.md).
+
+## Citing this Repository
+If you wish to cite our work, please use the following BibTeX code:
+```bibtex
+@article{yi2025alignment,
+  title={Alignment and comparison of directed networks via transition couplings of random walks},
+  author={Yi, Bongsoo and O'Connor, Kevin and McGoff, Kevin and Nobel, Andrew B},
+  journal={Journal of the Royal Statistical Society Series B: Statistical Methodology},
+  pages={qkae085},
+  year={2024},
+  doi = {10.1093/jrsssb/qkae085}
+}
+```

{pyotc-0.2.2 → pyotc-0.3.0}/noxfile.py

@@ -23,6 +23,6 @@ def format_check(session):
 
 @session
 def tests(session):
-    session.install(".")
+    session.install("-e", ".")
     session.install("pytest", "pytest-cov")
-    session.run("pytest")
+    session.run("pytest", "--cov=pyotc", "--cov-report=term", "--cov-report=xml")

{pyotc-0.2.2 → pyotc-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "pyotc"
-version = "0.2.2"
+version = "0.3.0"
 authors = [
     {name="Jay Hineman"},
     {name="Yuning Pan"},
@@ -45,3 +45,9 @@ name = "testpypi"
 url = "https://test.pypi.org/simple/"
 publish-url = "https://test.pypi.org/legacy/"
 explicit = true
+
+[tool.coverage.run]
+omit = [
+  "src/pyotc/otc_backend/optimal_transport/native_refactor.py",
+  "src/pyotc/otc_backend/graph/utils.py",
+]

pyotc-0.3.0/src/pyotc/__init__.py

@@ -0,0 +1,16 @@
+"""Top-level package for pyotc."""
+
+__author__ = """Jay Hineman"""
+__email__ = "jay.hineman@gmail.com"
+__version__ = "0.3.0"
+
+# Public API re-exports
+from .otc import entropic_otc, exact_otc
+
+__all__ = [
+    "exact_otc",
+    "entropic_otc",
+    "__author__",
+    "__email__",
+    "__version__",
+]

pyotc-0.3.0/src/pyotc/otc.py

@@ -0,0 +1,53 @@
+"""Main entry point for otc funcitonality"""
+
+from .otc_backend.policy_iteration.dense.exact import exact_otc as _exact_otc_dense
+from .otc_backend.policy_iteration.sparse.exact import exact_otc as _exact_otc_sparse
+from .otc_backend.policy_iteration.dense.entropic import entropic_otc as _entropic_otc
+
+
+def exact_otc(
+    P1,
+    P2,
+    c,
+    *,
+    stat_dist="best",
+    backend="dense",
+    max_iter=None,
+):
+    if backend == "dense":
+        return _exact_otc_dense(P1, P2, c, stat_dist=stat_dist)
+    elif backend == "sparse":
+        if max_iter is None:
+            return _exact_otc_sparse(P1, P2, c, stat_dist=stat_dist)
+        return _exact_otc_sparse(P1, P2, c, stat_dist=stat_dist, max_iter=max_iter)
+    else:
+        raise ValueError("Unknown backend: {backend}. Choose from {'dense', 'sparse'}.")
+
+
+def entropic_otc(
+    Px,
+    Py,
+    c,
+    *,
+    L=100,
+    T=100,
+    xi=0.1,
+    method="logsinkhorn",
+    sink_iter=100,
+    reg_num=None,
+    get_sd=False,
+    silent=True,
+):
+    return _entropic_otc(
+        Px,
+        Py,
+        c,
+        L=L,
+        T=T,
+        xi=xi,
+        method=method,
+        sink_iter=sink_iter,
+        reg_num=reg_num,
+        get_sd=get_sd,
+        silent=silent,
+    )

{pyotc-0.2.2 → pyotc-0.3.0}/tests/benchmark/test_entropic.py

@@ -5,7 +5,7 @@ import networkx as nx
 import time
 import pytest
 
-from pyotc.otc_backend.policy_iteration.dense.entropic import entropic_otc
+from pyotc import entropic_otc
 from pyotc.otc_backend.graph.utils import adj_to_trans, get_degree_cost
 from pyotc.examples.stochastic_block_model import stochastic_block_model
 from pyotc.examples.wheel import wheel_1, wheel_2, wheel_3
@@ -67,7 +67,7 @@ def test_wheel_exact_otc():
     # entropic otc
     start = time.time()
     exp_cost12, _, _ = entropic_otc(
-        P1, P2, c12, get_sd=True, L=25, T=50, xi=0.1, sink_iter=10
+        P1, P2, c12, get_sd=True, L=25, T=50, xi=0.1, sink_iter=10, silent=False
     )
     exp_cost13, _, _ = entropic_otc(
         P1, P3, c13, get_sd=True, L=25, T=50, xi=0.1, sink_iter=10

{pyotc-0.2.2 → pyotc-0.3.0}/tests/benchmark/test_exact.py

@@ -5,11 +5,8 @@ import networkx as nx
 import time
 import pytest
 
+from pyotc import exact_otc
 from pyotc.otc_backend.policy_iteration.dense.exact import exact_otc_lp
-from pyotc.otc_backend.policy_iteration.dense.exact import exact_otc as exact_otc_dense
-from pyotc.otc_backend.policy_iteration.sparse.exact import (
-    exact_otc as exact_otc_sparse,
-)
 from pyotc.otc_backend.graph.utils import adj_to_trans, get_degree_cost
 from pyotc.examples.stochastic_block_model import stochastic_block_model
 from pyotc.examples.wheel import wheel_1, wheel_2, wheel_3
@@ -41,27 +38,22 @@ test_data = zip(trans, costs)
 
 @pytest.mark.parametrize("transition, cost", test_data)
 def test_sbm_exact_otc(transition, cost):
-    # scipy linprog algo
-    start = time.time()
-    exp_cost1, _, _ = exact_otc_lp(transition["P1"], transition["P2"], cost)
-    end = time.time()
-    print(f"`exact_otc` (scipy) run time: {end - start}")
-
     # python optimal transport algo (numpy)
     start = time.time()
-    exp_cost2, _, _ = exact_otc_dense(transition["P1"], transition["P2"], cost)
+    exp_cost1, _, _ = exact_otc(transition["P1"], transition["P2"], cost)
     end = time.time()
     print(f"`exact_otc` (pot) run time: {end - start}")
 
     # python optimal transport algo (scipy.sparse)
     start = time.time()
-    exp_cost3, _, _ = exact_otc_sparse(transition["P1"], transition["P2"], cost)
+    exp_cost2, _, _ = exact_otc(
+        transition["P1"], transition["P2"], cost, backend="sparse", max_iter=100
+    )
     end = time.time()
     print(f"`exact_otc` (pot) run time: {end - start}")
 
     # check consistency
     assert np.allclose(exp_cost1, exp_cost2)
-    assert np.allclose(exp_cost1, exp_cost3)
 
 
 # 2. Test exact OTC on wheel graph
@@ -78,17 +70,24 @@ wheel_c = [
 
 
 def test_wheel_exact_otc():
-    # python optimal transport algo
-    exp_cost12_dense, _, _ = exact_otc_dense(wheel_P[0], wheel_P[1], wheel_c[0])
-    exp_cost12_sparse, _, _ = exact_otc_sparse(wheel_P[0], wheel_P[1], wheel_c[0])
+    exp_cost12_dense, _, _ = exact_otc(
+        wheel_P[0], wheel_P[1], wheel_c[0], stat_dist=None, backend="dense"
+    )
+    exp_cost12_sparse, _, _ = exact_otc(
+        wheel_P[0], wheel_P[1], wheel_c[0], stat_dist=None, backend="sparse"
+    )
 
-    exp_cost13_dense, _, _ = exact_otc_dense(wheel_P[0], wheel_P[2], wheel_c[1])
-    exp_cost13_sparse, _, _ = exact_otc_sparse(wheel_P[0], wheel_P[2], wheel_c[1])
+    exp_cost13_dense, _, _ = exact_otc(
+        wheel_P[0], wheel_P[2], wheel_c[1], stat_dist=None, backend="dense"
+    )
+    exp_cost13_sparse, _, _ = exact_otc(
+        wheel_P[0], wheel_P[2], wheel_c[1], stat_dist=None, backend="sparse"
+    )
 
     # check consistency
     assert np.allclose(exp_cost12_dense, 2.6551724137931036)
     assert np.allclose(exp_cost12_dense, exp_cost12_sparse)
-    assert np.allclose(exp_cost13_dense, 2.551724137931033)
+    assert np.allclose(exp_cost13_dense, 2.5517241379310316)
     assert np.allclose(exp_cost13_dense, exp_cost13_sparse)
 
 
@@ -103,14 +102,39 @@ edge_awareness_c = [c21, c23]
 
 
 def test_edge_awareness_exact_otc():
-    # python optimal transport algo
-    exp_cost21, _, _ = exact_otc_dense(
-        edge_awareness_P[1], edge_awareness_P[0], edge_awareness_c[0]
+    exp_cost21, _, _ = exact_otc(
+        edge_awareness_P[1],
+        edge_awareness_P[0],
+        edge_awareness_c[0],
+        stat_dist="eigen",
+        backend="dense",
+    )
+    exp_cost21_lp, _, _ = exact_otc_lp(
+        edge_awareness_P[1], edge_awareness_P[0], edge_awareness_c[0], stat_dist="best"
+    )
+    exp_cost23, _, _ = exact_otc(
+        edge_awareness_P[1],
+        edge_awareness_P[2],
+        edge_awareness_c[1],
+        stat_dist="iterative",
+        backend="dense",
     )
-    exp_cost23, _, _ = exact_otc_dense(
-        edge_awareness_P[1], edge_awareness_P[2], edge_awareness_c[1]
+    exp_cost23_lp, _, _ = exact_otc_lp(
+        edge_awareness_P[1], edge_awareness_P[2], edge_awareness_c[1], stat_dist=None
     )
 
     # check consistency
-    assert np.allclose(exp_cost21, 0.5714285714285714)
-    assert np.allclose(exp_cost23, 0.4464098659648351)
+    assert np.allclose(exp_cost21, 0.5714285714285724)
+    assert np.allclose(exp_cost21, exp_cost21_lp)
+    assert np.allclose(exp_cost23, 0.4464098659648501)
+    assert np.allclose(exp_cost23, exp_cost23_lp)
+
+
+def test_exact_otc_invalid_backend():
+    with pytest.raises(ValueError):
+        exact_otc(
+            edge_awareness_P[1],
+            edge_awareness_P[2],
+            edge_awareness_c[1],
+            backend="invalid_backend",
+        )

pyotc-0.2.2/INSTALL.md

@@ -1,41 +0,0 @@
-# Install
-We expect pyotc to be pip-installable across all platforms.
-
-## Install for usage
-### From pypi
-
-```pip install pyotc```
-[TODO#26](https://github.com/pyotc/pyotc/issues/26)
-
-### From github
-
-```pip install https://github.com/pyotc/pyotc.git```
-
-## Install for development
-We test in venvs provided by [uv](https://docs.astral.sh/uv/) via [nox](https://nox.thea.codes/en/stable/usage.html#changing-the-sessions-default-backend). It's helpful, but not strictly necessary to do the same.
-
-```bash
-git clone https://github.com/pyotc/pyotc.git
-cd pyotc
-pip install -e .
-```
-
-### `uv` workflow
-[Install the uv tool](https://docs.astral.sh/uv/getting-started/installation/).
-
-Then
-
-```bash
-git clone https://github.com/pyotc/pyotc.git
-cd pyotc
-uv sync
-uv pip install -e .
-```
-
-To verify your installation, run
-```bash
-uv run pytest
-```
-
-
-

pyotc-0.2.2/PKG-INFO

@@ -1,38 +0,0 @@
-Metadata-Version: 2.4
-Name: pyotc
-Version: 0.2.2
-Summary: Perform optimal transition coupling (OTC) in python.
-Author: Jay Hineman, Yuning Pan, Bongsoo Yi
-License: MIT license
-License-File: AUTHORS.rst
-License-File: LICENSE
-Requires-Python: >=3.10
-Requires-Dist: matplotlib>=3.10.0
-Requires-Dist: networkx>=3.4.2
-Requires-Dist: numpy>=2.2.1
-Requires-Dist: pot>=0.9.5
-Description-Content-Type: text/markdown
-
-# pyotc
-[![codecov](https://codecov.io/github/pyotc/pyotc/graph/badge.svg?token=52QPNW0AP7)](https://codecov.io/github/pyotc/pyotc)
-
-A python implementations of optimal transport coupling algorithms.
-
-## Documentation
-Find sphinx documentation [here](https://pyotc.github.io/pyotc/).
-
-## Install
-See [install instructions](INSTALL.md)
-
-## Run Tests
-With a `uv` setup one can simply
-```bash
-uv run pytest
-```
-Otherwise, in `pip` installed context with deps met, `pytest` should behave as expected.
-
-## Contributing
-Guidelines for contribution to `pyotc` are provided in [CONTRIBUTING.md](./CONTRIBUTING.md).
-
-## Changelog
-A summary of changes and guide to versioning are recoreded in [CHANGELOG.md](./CHANGELOG.md).

pyotc-0.2.2/README.md

@@ -1,23 +0,0 @@
-# pyotc
-[![codecov](https://codecov.io/github/pyotc/pyotc/graph/badge.svg?token=52QPNW0AP7)](https://codecov.io/github/pyotc/pyotc)
-
-A python implementations of optimal transport coupling algorithms.
-
-## Documentation
-Find sphinx documentation [here](https://pyotc.github.io/pyotc/).
-
-## Install
-See [install instructions](INSTALL.md)
-
-## Run Tests
-With a `uv` setup one can simply
-```bash
-uv run pytest
-```
-Otherwise, in `pip` installed context with deps met, `pytest` should behave as expected.
-
-## Contributing
-Guidelines for contribution to `pyotc` are provided in [CONTRIBUTING.md](./CONTRIBUTING.md).
-
-## Changelog
-A summary of changes and guide to versioning are recoreded in [CHANGELOG.md](./CHANGELOG.md).

pyotc-0.2.2/src/pyotc/__init__.py

@@ -1,5 +0,0 @@
-"""Top-level package for pyotc."""
-
-__author__ = """Jay Hineman"""
-__email__ = "jay.hineman@gmail.com"
-__version__ = "0.1.0"

pyotc-0.2.2/src/pyotc/otc.py

@@ -1,5 +0,0 @@
-"""Main entry point for otc funcitonality"""
-
-
-def exact_OTC():
-    raise NotImplementedError