auction-assign 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,80 @@
1
+ name: CI
2
+
3
+ on:
4
+ push:
5
+ branches:
6
+ - main
7
+ pull_request:
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ rust:
14
+ name: Rust checks
15
+ runs-on: ubuntu-latest
16
+ steps:
17
+ - name: Checkout repository
18
+ uses: actions/checkout@v4
19
+
20
+ - name: Set up Python
21
+ uses: actions/setup-python@v5
22
+ with:
23
+ python-version-file: ".python-version"
24
+
25
+ - name: Set up Rust toolchain
26
+ uses: dtolnay/rust-toolchain@stable
27
+ with:
28
+ components: rustfmt, clippy
29
+
30
+ - name: Cache Cargo artifacts
31
+ uses: Swatinem/rust-cache@v2
32
+
33
+ - name: Check formatting
34
+ run: cargo fmt --check
35
+
36
+ - name: Run Clippy
37
+ run: cargo clippy --all-targets -- -D warnings
38
+
39
+ - name: Run Rust tests
40
+ run: cargo test
41
+
42
+ python:
43
+ name: Python checks (${{ matrix.os }})
44
+ runs-on: ${{ matrix.os }}
45
+ strategy:
46
+ fail-fast: false
47
+ matrix:
48
+ os: [ubuntu-latest, windows-latest, macos-latest]
49
+ steps:
50
+ - name: Checkout repository
51
+ uses: actions/checkout@v4
52
+
53
+ - name: Set up Rust toolchain
54
+ uses: dtolnay/rust-toolchain@stable
55
+
56
+ - name: Cache Cargo artifacts
57
+ uses: Swatinem/rust-cache@v2
58
+
59
+ - name: Set up uv
60
+ uses: astral-sh/setup-uv@v5
61
+ with:
62
+ enable-cache: true
63
+
64
+ - name: Install Python
65
+ run: uv python install
66
+
67
+ - name: Sync environment and build extension
68
+ run: uv sync
69
+
70
+ - name: Run ruff lint
71
+ run: uv run ruff check .
72
+
73
+ - name: Check ruff formatting
74
+ run: uv run ruff format --check python tests benchmarks
75
+
76
+ - name: Run mypy
77
+ run: uv run mypy python tests benchmarks
78
+
79
+ - name: Run pytest
80
+ run: uv run pytest -v
@@ -0,0 +1,149 @@
1
+ name: Release
2
+
3
+ on:
4
+ push:
5
+ tags:
6
+ - "v*"
7
+ workflow_dispatch:
8
+
9
+ permissions:
10
+ contents: read
11
+
12
+ jobs:
13
+ build-wheels:
14
+ name: Build wheel (${{ matrix.platform.name }})
15
+ runs-on: ${{ matrix.platform.os }}
16
+ strategy:
17
+ fail-fast: false
18
+ matrix:
19
+ platform:
20
+ - name: linux-x86_64
21
+ os: ubuntu-latest
22
+ target: x86_64
23
+ manylinux: "2_28"
24
+ - name: linux-aarch64
25
+ os: ubuntu-latest
26
+ target: aarch64
27
+ manylinux: "2_28"
28
+ - name: macos-x86_64
29
+ os: macos-15-intel
30
+ target: x86_64
31
+ manylinux: ""
32
+ - name: macos-aarch64
33
+ os: macos-latest
34
+ target: aarch64
35
+ manylinux: ""
36
+ - name: windows-x64
37
+ os: windows-latest
38
+ target: x64
39
+ manylinux: ""
40
+ steps:
41
+ - name: Checkout repository
42
+ uses: actions/checkout@v4
43
+
44
+ - name: Set up Python
45
+ uses: actions/setup-python@v5
46
+ with:
47
+ python-version: "3.10"
48
+
49
+ - name: Build abi3 wheel
50
+ uses: PyO3/maturin-action@v1
51
+ with:
52
+ command: build
53
+ target: ${{ matrix.platform.target }}
54
+ args: --release --out dist
55
+ manylinux: ${{ matrix.platform.manylinux }}
56
+ sccache: ${{ !startsWith(github.ref, 'refs/tags/') }}
57
+
58
+ - name: Upload wheel artifact
59
+ uses: actions/upload-artifact@v4
60
+ with:
61
+ name: wheels-${{ matrix.platform.name }}
62
+ path: dist/*.whl
63
+
64
+ build-sdist:
65
+ name: Build sdist
66
+ runs-on: ubuntu-latest
67
+ steps:
68
+ - name: Checkout repository
69
+ uses: actions/checkout@v4
70
+
71
+ - name: Build source distribution
72
+ uses: PyO3/maturin-action@v1
73
+ with:
74
+ command: sdist
75
+ args: --out dist
76
+
77
+ - name: Upload sdist artifact
78
+ uses: actions/upload-artifact@v4
79
+ with:
80
+ name: sdist
81
+ path: dist/*.tar.gz
82
+
83
+ test-wheels:
84
+ name: Smoke test wheel (${{ matrix.platform.name }})
85
+ needs: [build-wheels]
86
+ runs-on: ${{ matrix.platform.os }}
87
+ strategy:
88
+ fail-fast: false
89
+ matrix:
90
+ platform:
91
+ - name: linux-x86_64
92
+ os: ubuntu-latest
93
+ artifact: wheels-linux-x86_64
94
+ - name: macos-x86_64
95
+ os: macos-15-intel
96
+ artifact: wheels-macos-x86_64
97
+ - name: macos-aarch64
98
+ os: macos-latest
99
+ artifact: wheels-macos-aarch64
100
+ - name: windows-x64
101
+ os: windows-latest
102
+ artifact: wheels-windows-x64
103
+ steps:
104
+ - name: Checkout repository
105
+ uses: actions/checkout@v4
106
+
107
+ - name: Download wheel artifact
108
+ uses: actions/download-artifact@v4
109
+ with:
110
+ name: ${{ matrix.platform.artifact }}
111
+ path: dist
112
+
113
+ - name: Set up uv
114
+ uses: astral-sh/setup-uv@v5
115
+ with:
116
+ enable-cache: true
117
+
118
+ - name: Install Python
119
+ run: uv python install
120
+
121
+ - name: Smoke test installed wheel
122
+ shell: bash
123
+ run: |
124
+ set -euo pipefail
125
+ WHEEL=$(ls dist/*.whl | head -n 1)
126
+ uv run --isolated --no-project --with "$WHEEL" --with pytest pytest -v tests/test_correctness.py
127
+
128
+ publish:
129
+ name: Publish to PyPI
130
+ needs: [build-wheels, build-sdist, test-wheels]
131
+ if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
132
+ runs-on: ubuntu-latest
133
+ environment:
134
+ name: release
135
+ url: https://pypi.org/project/auction-assign/
136
+ permissions:
137
+ id-token: write
138
+ steps:
139
+ - name: Download built distributions
140
+ uses: actions/download-artifact@v4
141
+ with:
142
+ path: dist
143
+ merge-multiple: true
144
+
145
+ - name: Inspect distribution artifacts
146
+ run: ls -la dist
147
+
148
+ - name: Publish to PyPI
149
+ uses: pypa/gh-action-pypi-publish@release/v1
@@ -0,0 +1,11 @@
1
+ target/
2
+ .venv/
3
+ dist/
4
+ *.egg-info/
5
+ __pycache__/
6
+ .pytest_cache/
7
+ .mypy_cache/
8
+ .ruff_cache/
9
+ .superpowers/
10
+ *.pyd
11
+ *.so
@@ -0,0 +1 @@
1
+ 3.12
@@ -0,0 +1,228 @@
1
+ # This file is automatically @generated by Cargo.
2
+ # It is not intended for manual editing.
3
+ version = 4
4
+
5
+ [[package]]
6
+ name = "auction-assign"
7
+ version = "0.1.0"
8
+ dependencies = [
9
+ "numpy",
10
+ "pyo3",
11
+ ]
12
+
13
+ [[package]]
14
+ name = "autocfg"
15
+ version = "1.5.1"
16
+ source = "registry+https://github.com/rust-lang/crates.io-index"
17
+ checksum = "f2032f911046de80f0a198e0901378627c33f59ea0ac00e363d481118bd70a53"
18
+
19
+ [[package]]
20
+ name = "heck"
21
+ version = "0.5.0"
22
+ source = "registry+https://github.com/rust-lang/crates.io-index"
23
+ checksum = "2304e00983f87ffb38b55b444b5e3b60a884b5d30c0fca7d82fe33449bbe55ea"
24
+
25
+ [[package]]
26
+ name = "libc"
27
+ version = "0.2.191"
28
+ source = "registry+https://github.com/rust-lang/crates.io-index"
29
+ checksum = "65cd87c9a6d60536580b316ad985726104730a5151c99845f2490428ef91240a"
30
+
31
+ [[package]]
32
+ name = "matrixmultiply"
33
+ version = "0.3.11"
34
+ source = "registry+https://github.com/rust-lang/crates.io-index"
35
+ checksum = "3f607c237553f086e7043417a51df26b2eb899d3caff94e6a67592ff992fedc7"
36
+ dependencies = [
37
+ "autocfg",
38
+ "rawpointer",
39
+ ]
40
+
41
+ [[package]]
42
+ name = "ndarray"
43
+ version = "0.17.2"
44
+ source = "registry+https://github.com/rust-lang/crates.io-index"
45
+ checksum = "520080814a7a6b4a6e9070823bb24b4531daac8c4627e08ba5de8c5ef2f2752d"
46
+ dependencies = [
47
+ "matrixmultiply",
48
+ "num-complex",
49
+ "num-integer",
50
+ "num-traits",
51
+ "portable-atomic",
52
+ "portable-atomic-util",
53
+ "rawpointer",
54
+ ]
55
+
56
+ [[package]]
57
+ name = "num-complex"
58
+ version = "0.4.6"
59
+ source = "registry+https://github.com/rust-lang/crates.io-index"
60
+ checksum = "73f88a1307638156682bada9d7604135552957b7818057dcef22705b4d509495"
61
+ dependencies = [
62
+ "num-traits",
63
+ ]
64
+
65
+ [[package]]
66
+ name = "num-integer"
67
+ version = "0.1.47"
68
+ source = "registry+https://github.com/rust-lang/crates.io-index"
69
+ checksum = "7ce2d95d4b3734dc35aa2f45e1aa22cd416814592a4f9d9205e11affd5b8e10b"
70
+ dependencies = [
71
+ "num-traits",
72
+ ]
73
+
74
+ [[package]]
75
+ name = "num-traits"
76
+ version = "0.2.19"
77
+ source = "registry+https://github.com/rust-lang/crates.io-index"
78
+ checksum = "071dfc062690e90b734c0b2273ce72ad0ffa95f0c74596bc250dcfd960262841"
79
+ dependencies = [
80
+ "autocfg",
81
+ ]
82
+
83
+ [[package]]
84
+ name = "numpy"
85
+ version = "0.30.0"
86
+ source = "registry+https://github.com/rust-lang/crates.io-index"
87
+ checksum = "aa0b9111761885449e894981fa8051dcf69e0bd114aecbd4bcdd830b6be4ed92"
88
+ dependencies = [
89
+ "libc",
90
+ "ndarray",
91
+ "num-complex",
92
+ "num-integer",
93
+ "num-traits",
94
+ "pyo3",
95
+ "pyo3-build-config",
96
+ "rustc-hash",
97
+ ]
98
+
99
+ [[package]]
100
+ name = "once_cell"
101
+ version = "1.21.4"
102
+ source = "registry+https://github.com/rust-lang/crates.io-index"
103
+ checksum = "9f7c3e4beb33f85d45ae3e3a1792185706c8e16d043238c593331cc7cd313b50"
104
+
105
+ [[package]]
106
+ name = "portable-atomic"
107
+ version = "1.15.0"
108
+ source = "registry+https://github.com/rust-lang/crates.io-index"
109
+ checksum = "05c8b63e8d9609db387f0324918f81d68fe27748f084ef092fb35954d0539a85"
110
+
111
+ [[package]]
112
+ name = "portable-atomic-util"
113
+ version = "0.2.8"
114
+ source = "registry+https://github.com/rust-lang/crates.io-index"
115
+ checksum = "10ab3eb7f3becc3a1cbc4f2c6f20267996cfc1a6467a873763411b136a122715"
116
+ dependencies = [
117
+ "portable-atomic",
118
+ ]
119
+
120
+ [[package]]
121
+ name = "proc-macro2"
122
+ version = "1.0.107"
123
+ source = "registry+https://github.com/rust-lang/crates.io-index"
124
+ checksum = "985e7ec9bb745e6ce6535b544d84d6cd6f7ad8bd711c398938ae983b91a766d9"
125
+ dependencies = [
126
+ "unicode-ident",
127
+ ]
128
+
129
+ [[package]]
130
+ name = "pyo3"
131
+ version = "0.30.1"
132
+ source = "registry+https://github.com/rust-lang/crates.io-index"
133
+ checksum = "229ca13b8a15bb0d1487b81ab975bfcd97513416499a8312011b6036e42e0de4"
134
+ dependencies = [
135
+ "libc",
136
+ "once_cell",
137
+ "portable-atomic",
138
+ "pyo3-build-config",
139
+ "pyo3-ffi",
140
+ "pyo3-macros",
141
+ ]
142
+
143
+ [[package]]
144
+ name = "pyo3-build-config"
145
+ version = "0.30.1"
146
+ source = "registry+https://github.com/rust-lang/crates.io-index"
147
+ checksum = "70130e2b6dd1ee589a8788026a429561ca5c40fa7a2fa7914c2282eddae24700"
148
+ dependencies = [
149
+ "target-lexicon",
150
+ ]
151
+
152
+ [[package]]
153
+ name = "pyo3-ffi"
154
+ version = "0.30.1"
155
+ source = "registry+https://github.com/rust-lang/crates.io-index"
156
+ checksum = "5e7ff73c555c286d212d4ce7e5fbda845a973c4f61bd5f160f5f2c3c2a04d1c4"
157
+ dependencies = [
158
+ "libc",
159
+ "pyo3-build-config",
160
+ ]
161
+
162
+ [[package]]
163
+ name = "pyo3-macros"
164
+ version = "0.30.1"
165
+ source = "registry+https://github.com/rust-lang/crates.io-index"
166
+ checksum = "c46d2e5862c7bb8207e3b639f713dda3c499933444784154c11d013c5a691b60"
167
+ dependencies = [
168
+ "proc-macro2",
169
+ "pyo3-macros-backend",
170
+ "quote",
171
+ "syn",
172
+ ]
173
+
174
+ [[package]]
175
+ name = "pyo3-macros-backend"
176
+ version = "0.30.1"
177
+ source = "registry+https://github.com/rust-lang/crates.io-index"
178
+ checksum = "38b89f066f2ae72a2aef52d1537ca2fcd104440ebfadee06e97aa90738a25b9b"
179
+ dependencies = [
180
+ "heck",
181
+ "proc-macro2",
182
+ "quote",
183
+ "syn",
184
+ ]
185
+
186
+ [[package]]
187
+ name = "quote"
188
+ version = "1.0.47"
189
+ source = "registry+https://github.com/rust-lang/crates.io-index"
190
+ checksum = "1fbf4db142a473a8d80c26bbf18454ed458bf8d26c8219c331daecfdbd079001"
191
+ dependencies = [
192
+ "proc-macro2",
193
+ ]
194
+
195
+ [[package]]
196
+ name = "rawpointer"
197
+ version = "0.2.1"
198
+ source = "registry+https://github.com/rust-lang/crates.io-index"
199
+ checksum = "60a357793950651c4ed0f3f52338f53b2f809f32d83a07f72909fa13e4c6c1e3"
200
+
201
+ [[package]]
202
+ name = "rustc-hash"
203
+ version = "2.1.3"
204
+ source = "registry+https://github.com/rust-lang/crates.io-index"
205
+ checksum = "6b1e7f9a428571be2dc5bc0505c13fb6bf936822b894ec87abf8a08a4e51742d"
206
+
207
+ [[package]]
208
+ name = "syn"
209
+ version = "3.0.10"
210
+ source = "registry+https://github.com/rust-lang/crates.io-index"
211
+ checksum = "4ae9ccbea3a7b0b09443036490c8f34a8b1b760fd345e5c0dae0aac718faea79"
212
+ dependencies = [
213
+ "proc-macro2",
214
+ "quote",
215
+ "unicode-ident",
216
+ ]
217
+
218
+ [[package]]
219
+ name = "target-lexicon"
220
+ version = "0.13.6"
221
+ source = "registry+https://github.com/rust-lang/crates.io-index"
222
+ checksum = "8c447be3a2abfa84b2d91680c56600bd6b2873866de27b36ec911be705e291da"
223
+
224
+ [[package]]
225
+ name = "unicode-ident"
226
+ version = "1.0.27"
227
+ source = "registry+https://github.com/rust-lang/crates.io-index"
228
+ checksum = "a2c754d6c33795a1c324727428e5a7dedb5b06195f9890bdbcba760d3e246563"
@@ -0,0 +1,16 @@
1
+ [package]
2
+ name = "auction-assign"
3
+ version = "0.1.0"
4
+ edition = "2024"
5
+ rust-version = "1.85"
6
+ license = "MIT"
7
+ repository = "https://github.com/dcollison/auction-assign"
8
+ readme = "README.md"
9
+
10
+ [lib]
11
+ name = "_core"
12
+ crate-type = ["cdylib"]
13
+
14
+ [dependencies]
15
+ numpy = "0.30"
16
+ pyo3 = { version = "0.30", features = ["abi3-py310"] }
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 Dale Collison
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,195 @@
1
+ Metadata-Version: 2.4
2
+ Name: auction-assign
3
+ Version: 0.1.0
4
+ Classifier: Operating System :: OS Independent
5
+ Classifier: Programming Language :: Python :: 3
6
+ Classifier: Programming Language :: Python :: 3.10
7
+ Classifier: Programming Language :: Python :: 3.11
8
+ Classifier: Programming Language :: Python :: 3.12
9
+ Classifier: Programming Language :: Python :: 3.13
10
+ Classifier: Programming Language :: Python :: 3.14
11
+ Classifier: Programming Language :: Rust
12
+ Classifier: Topic :: Scientific/Engineering :: Mathematics
13
+ Requires-Dist: numpy>=1.24
14
+ License-File: LICENSE
15
+ Summary: Fast Bertsekas auction algorithm for linear sum assignment in Rust with Python bindings
16
+ License-Expression: MIT
17
+ Requires-Python: >=3.10
18
+ Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
19
+ Project-URL: Homepage, https://github.com/dcollison/auction-assign
20
+ Project-URL: Issues, https://github.com/dcollison/auction-assign/issues
21
+ Project-URL: Repository, https://github.com/dcollison/auction-assign
22
+
23
+ # auction-assign
24
+
25
+ Fast Bertsekas epsilon-scaling forward-reverse auction algorithm for dense linear sum assignment in Rust with Python bindings.
26
+
27
+ ## Features
28
+
29
+ - **Drop-in replacement for `scipy.optimize.linear_sum_assignment`**: `auction_assign(cost_matrix)` returns `(row_ind, col_ind)` as sorted `np.intp` NumPy arrays for square and rectangular (`m x n`) matrices.
30
+ - **Native `cost_limit` partial assignment**: Supports unassigned-slack gating (`cost < cost_limit` when minimizing, `cost > cost_limit` when maximizing) so non-beneficial pairs stay unmatched without quadratic padding.
31
+ - **Hard edge gating (`inf` / `-inf`)**: Exclude impossible associations with `+inf` (minimization) or `-inf` (maximization), raising `InfeasibleError` if no complete matching exists when `cost_limit=None`.
32
+ - **Rich solver telemetry**: `solve()` returns an immutable `AuctionResult` with exact total `cost` and `AuctionInfo` (`iterations`, `scaling_rounds`, `final_eps`, `row_prices`, `col_prices`).
33
+ - **Releases the GIL**: Core Rust computation runs without holding the Python GIL, scaling across threads with `ThreadPoolExecutor`.
34
+ - **Typed Python API**: Includes `py.typed` and passes `mypy --strict`.
35
+
36
+ ## Installation
37
+
38
+ Requires Python 3.10+ and NumPy 1.24+.
39
+
40
+ ```bash
41
+ uv add auction-assign
42
+ ```
43
+
44
+ Or with `pip`:
45
+
46
+ ```bash
47
+ pip install auction-assign
48
+ ```
49
+
50
+ ## Quickstart
51
+
52
+ ### Drop-in `linear_sum_assignment` usage
53
+
54
+ ```python
55
+ import numpy as np
56
+ from auction_assign import auction_assign
57
+
58
+ cost_matrix = np.array(
59
+ [
60
+ [4.0, 1.0, 3.0],
61
+ [2.0, 0.0, 5.0],
62
+ [3.0, 2.0, 2.0],
63
+ ]
64
+ )
65
+ row_ind, col_ind = auction_assign(cost_matrix)
66
+ total_cost = float(cost_matrix[row_ind, col_ind].sum())
67
+ print(row_ind, col_ind, total_cost)
68
+ # [0 1 2] [1 0 2] 5.0
69
+ ```
70
+
71
+ ### Track-to-track fusion with gating, `cost_limit`, and diagnostics
72
+
73
+ In multi-target tracking and sensor fusion, impossible associations are masked with `np.inf` and associations worse than a gate threshold `cost_limit` should remain unassigned rather than forcing bad matches:
74
+
75
+ ```python
76
+ import numpy as np
77
+ from auction_assign import ConvergenceError, InfeasibleError, solve
78
+
79
+ # Pairwise track-to-measurement association costs (3 tracks x 4 measurements).
80
+ # np.inf forbids impossible pairs; track 2 has no pair below cost_limit=10.0.
81
+ costs = np.array(
82
+ [
83
+ [1.2, 8.5, np.inf, 9.0],
84
+ [np.inf, 2.4, 3.1, np.inf],
85
+ [12.0, 15.0, np.inf, 18.0],
86
+ ]
87
+ )
88
+
89
+ try:
90
+ result = solve(costs, cost_limit=10.0)
91
+ except InfeasibleError as exc:
92
+ raise RuntimeError("No complete gated assignment exists") from exc
93
+ except ConvergenceError as exc:
94
+ raise RuntimeError(
95
+ f"Solver stopped at iteration {exc.iterations} (eps={exc.final_eps:.3e})"
96
+ ) from exc
97
+
98
+ print("Matched tracks:", result.row_ind) # [0 1]
99
+ print("Matched meas: ", result.col_ind) # [0 1]
100
+ print(f"Total cost: {result.cost:.2f}") # 3.60
101
+ print("Iterations: ", result.info.iterations)
102
+ print("Scaling rounds:", result.info.scaling_rounds)
103
+ print("Final epsilon: ", result.info.final_eps)
104
+ ```
105
+
106
+ For maximization problems (e.g., log-likelihood or affinity scores), pass `maximize=True`, use `-np.inf` to forbid pairs, and set `cost_limit` as a strict lower bound (`score > cost_limit`):
107
+
108
+ ```python
109
+ import numpy as np
110
+ from auction_assign import solve
111
+
112
+ scores = np.array(
113
+ [
114
+ [10.0, -np.inf, 1.0],
115
+ [-np.inf, 4.0, -2.0],
116
+ ]
117
+ )
118
+ res = solve(scores, maximize=True, cost_limit=0.0)
119
+ print(res.row_ind, res.col_ind, res.cost)
120
+ # [0 1] [0 1] 14.0
121
+ ```
122
+
123
+ ## API Reference
124
+
125
+ - **`auction_assign(cost_matrix, *, maximize=False, cost_limit=None, eps_min=None, eps_factor=5.0, max_iterations=None) -> tuple[NDArray[np.intp], NDArray[np.intp]]`**
126
+ Solves the 2D linear sum assignment problem and returns `(row_ind, col_ind)` with `row_ind` in strictly ascending order.
127
+ - **`solve(cost_matrix, *, maximize=False, cost_limit=None, eps_min=None, eps_factor=5.0, max_iterations=None) -> AuctionResult`**
128
+ Same parameters as `auction_assign`, returning an `AuctionResult`.
129
+ - **`AuctionResult`** (frozen dataclass): `row_ind`, `col_ind`, `cost: float`, `info: AuctionInfo`.
130
+ - **`AuctionInfo`** (frozen dataclass): `iterations: int`, `scaling_rounds: int`, `final_eps: float`, `row_prices: NDArray[np.float64]`, `col_prices: NDArray[np.float64]`.
131
+ - **`InfeasibleError(ValueError)`**: Raised when `cost_limit is None` and a matrix gated with `inf` (or `-inf` when `maximize=True`) has no complete assignment of size `min(n_rows, n_cols)`.
132
+ - **`ConvergenceError(RuntimeError)`**: Raised when `max_iterations` is exceeded or IEEE-754 `f64` price updates stall; provides `.iterations` and `.final_eps`.
133
+
134
+ Note: Pairs with `cost == cost_limit` are excluded (strict `< cost_limit` when minimizing, strict `> cost_limit` when maximizing). `NaN`, `-inf` during minimization, and `+inf` during maximization raise `ValueError`.
135
+
136
+ ## Benchmarks
137
+
138
+ Compare `auction_assign` against `scipy.optimize.linear_sum_assignment` on dense random matrices (`N = 20, 50, 100, 250, 500`, plus `50x200`) and feasible sparse-gated track-fusion matrices (90% `inf` entries, with a `1e15` sentinel for SciPy):
139
+
140
+ ```bash
141
+ # Full benchmark table with median/min timings and optimality gap checks
142
+ uv run python benchmarks/bench_assign.py
143
+
144
+ # Fast verification run (fewer warmup/repeat iterations)
145
+ uv run python benchmarks/bench_assign.py --quick
146
+ ```
147
+
148
+ Both modes verify solution optimality against SciPy for every benchmark case (`PASS`/`FAIL`).
149
+
150
+ ## Local Development
151
+
152
+ ```bash
153
+ # Create/sync virtualenv and build the Rust extension
154
+ uv sync
155
+
156
+ # Run Python test suite
157
+ uv run pytest -v
158
+
159
+ # Run Rust checks and unit tests
160
+ cargo fmt --check
161
+ cargo clippy --all-targets -- -D warnings
162
+ cargo test
163
+
164
+ # Run Python lint, format check, and strict type checking
165
+ uv run ruff check .
166
+ uv run ruff format --check python tests benchmarks
167
+ uv run mypy python tests benchmarks
168
+
169
+ # Build wheel and sdist into dist/
170
+ uv build
171
+ ```
172
+
173
+ ## Releasing (PyPI Trusted Publishing)
174
+
175
+ Releases are automated by [`.github/workflows/release.yml`](.github/workflows/release.yml) using PyPI OIDC Trusted Publishing (`id-token: write` with `pypa/gh-action-pypi-publish@release/v1`), so no long-lived PyPI API tokens are stored in repository secrets.
176
+
177
+ One-time repository and PyPI setup:
178
+
179
+ 1. In your GitHub repository, go to **Settings → Environments** and create an environment named `release` (optionally configure required reviewers or branch/tag protection rules).
180
+ 2. On [PyPI](https://pypi.org/), go to **Your Account → Publishing** (or your project's **Publishing** settings) and add a **GitHub** Trusted Publisher with:
181
+ - **Owner**: `dcollison`
182
+ - **Repository name**: `auction-assign`
183
+ - **Workflow name**: `release.yml`
184
+ - **Environment name**: `release`
185
+ 3. Tag a release matching `v*` and push it to GitHub:
186
+ ```bash
187
+ git tag v0.1.0
188
+ git push origin v0.1.0
189
+ ```
190
+ You can also test wheel builds and smoke tests without publishing by triggering the **Release** workflow manually via `workflow_dispatch`.
191
+
192
+ ## License
193
+
194
+ MIT — see [LICENSE](LICENSE).
195
+