nn-rank 0.0.1__tar.gz

nn_rank-0.0.1/LICENSE

@@ -0,0 +1,204 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+ 
+   Copyright (c) 2026- ABrain-One
+   All rights reserved.
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

nn_rank-0.0.1/PKG-INFO

@@ -0,0 +1,213 @@
+Metadata-Version: 2.4
+Name: nn-rank
+Version: 0.0.1
+Summary: Ranking of AI Systems by the Accuracy-Resource Trade-off
+Author-email: ABrain One and contributors <AI@ABrain.one>
+License-Expression: Apache-2.0
+Project-URL: Homepage, https://ABrain.one
+Project-URL: Repository, https://github.com/ABrain-One/nn-rank
+Project-URL: Bug Tracker, https://github.com/ABrain-One/nn-rank/issues
+Keywords: neural network ranking,model selection,AI system,accuracy latency trade-off,pareto front,quality resource trade-off,inference cost analysis,model efficiency benchmark,deep learning model comparison,python model ranking
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: pandas
+Dynamic: license-file
+
+# AI Ranking
+
+Ranks neural networks by the **accuracy–resource trade-off** and returns one
+score per model. There is no weight to choose: the exchange rate between
+accuracy and cost is derived from the candidates' own frontier.
+
+## Create and Activate a Virtual Environment (recommended)
+
+For Linux/Mac:
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+```
+
+For Windows:
+```bash
+python3 -m venv .venv
+.venv\Scripts\activate
+python -m pip install --upgrade pip
+```
+
+```bash
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+## Use as an API
+
+```python
+import pandas as pd
+from ab.nn.select import select
+
+df = pd.DataFrame({
+    "name":     ["B0",   "B1",  "B2",  "B3",  "B4",  "B5",  "B6",  "B7"],
+    "accuracy": [0.771, 0.791, 0.801, 0.816, 0.829, 0.836, 0.840, 0.843],
+    "flops_B":  [0.39,  0.70,  1.0,   1.8,   4.2,   9.9,   19,    37],
+    "params_M": [5.3,   7.8,   9.2,   12,    19,    30,    43,    66],
+})
+
+r = select(df, res_col=["flops_B", "params_M"], rank=True)
+
+r["winner"]["name"]       # 'B0'      <- the selected model
+r["winner"]["score"]      # 0.7140    <- its score, higher is better
+r["verdict"]["level"]     # 'USABLE' | 'UNVERIFIED' | 'UNUSABLE'
+r["ranking"]              # DataFrame: name, score, rank, ...
+```
+
+### Input
+
+One row per model, in a `pandas.DataFrame`:
+
+| column | required | meaning |
+|---|---|---|
+| `name` | yes | model identifier |
+| `accuracy` | yes | quality in **(0, 1)**, strictly between 0 and 1 |
+| one or more resource columns | yes | anything you spend: latency, FLOPs, parameters, memory, energy. Each **> 0** |
+
+`select(df, res_col=...)` names the resource column(s) — a string for one, a
+list for several. All models must be measured on the **same test set and the
+same device**, and each resource in **one fixed unit**.
+
+Quality that is not already in (0, 1) must be converted first. For PSNR in dB,
+`accuracy = 1 - 10 ** (-PSNR / 10)`. For top-1, mAP, mIoU, SSIM or F1, use the
+value as it is.
+
+### Output
+
+`select()` returns a dict. The three things most users need:
+
+| key | what it is |
+|---|---|
+| `winner["name"]` | **the selected model** |
+| `winner["score"]` | **its score** — higher is better |
+| `ranking` | a `DataFrame`, winner first: `name`, `score`, `rank`, `accuracy`, each resource, `sigma`, `eps_eff`, `margin_to_next`, `rank_low`, `rank_high`, `note` |
+
+Also returned: `verdict`, `status`, `prices` (one price per resource axis),
+`rate`, `price_free` (dominations true at every price), `front`, `fit`,
+`envelope`, `axis_drop`, `next`, `notes`, `problems`. `select()` prints
+nothing and raises nothing; bad input comes back as `status="bad_input"` with
+the offending rows listed in `problems`.
+
+### The score
+
+```
+score   = 1 / (1 + eps_eff)
+eps_eff = eps * product over axes of (resource ** lambda)      eps = 1 - accuracy
+```
+
+`eps_eff` is **the error the model effectively costs once its resources are
+charged** at the derived price `lambda`; `score` is that mapped into (0, 1) so
+that **higher is better**.
+
+Its one useful property: it is computed from a single model's own accuracy and
+resources, and from nothing else. **Adding or removing other models cannot
+change it** — unlike `rank`, or any score normalised over the candidate set.
+So scores are comparable across runs and across published tables.
+
+Two things it is *not* invariant to:
+
+- **the resource unit** — milliseconds vs seconds shifts every score by the
+  same constant, so the ordering is untouched but the numbers are not
+  comparable unless the unit is fixed;
+- **`lambda`** — only compare scores derived at the same price.
+
+### Read the verdict before the ranking
+
+`verdict["level"]` says whether the ranking means anything. A clean run prints
+nothing; a problem prints in red, first.
+
+| level | meaning |
+|---|---|
+| `USABLE` | the error floor is confirmed by a nested F-test, so an exchange rate exists and the ranking is a genuine trade-off ranking |
+| `UNVERIFIED` | too few points on the frontier to test the floor, or its knee lies outside the measured range — the ranking is a guess |
+| `UNUSABLE` | the floor is rejected: no exchange rate exists in this data, and the ranking collapses to resource order |
+
+`UNVERIFIED` and `UNUSABLE` still return a full ranking — labelled, not
+withheld. What holds regardless of the verdict is `price_free`: a model beaten
+on accuracy **and** on every resource can never win at any price.
+
+### How many models are needed
+
+Counts refer to candidates that **survive the cull**, not those supplied.
+
+| surviving | behaviour |
+|---|---|
+| **8 or more** | the floor test identifies a rate reliably — `USABLE` expected |
+| 6–7 | the papers' threshold, but noise-sensitive: identification 81% at 1% accuracy noise, 9% at 3% |
+| 3–5 | the floor cannot be tested; a ranking is returned, labelled `UNVERIFIED` |
+
+Fewer still ranks usefully: the exponent's precision is flat from three to ten
+candidates when a floor is present, and `price_free` dominations hold at any
+price. On MAI 2021, three surviving candidates of ten recovered the official
+top two and identified six of the nine entries as dominated.
+
+Competition leaderboards rarely reach eight by construction: their rules fix
+quality at a threshold and compete on cost, so the surviving frontier is short
+and carries little curvature.
+
+## Usage examples
+
+Ranked by the accuracy–time trade-off, no weight to choose. Any bare argument
+containing a comma is a candidate: `name,accuracy,p1[,p2,...]`.
+
+1. MAI 2026 INT8, SSIM vs inference time ms (NPU) — [arXiv:2611.00963](https://arxiv.org/pdf/2611.00963)
+```bash
+python -m ab.nn.select --rank koreatechV2,0.8499,4.35 Godzilla,0.8831,215160 AntSR,0.8731,4.52 LoongSR,0.8586,5729 IN2GM,0.8701,46.5 z6,0.8699,5.49 AIO_MAI,0.8634,41.1 AntYSP,0.8729,4.33
+```
+
+2. MAI 2026 INT8, PSNR converted to (0,1) vs 3 resources — NPU ms, CPU ms, model size (KB) — [arXiv:2611.00963](https://arxiv.org/pdf/2611.00963)
+```bash
+python -m ab.nn.select --rank koreatechV2,0.998758348,4.35,464,77.1 Godzilla,0.999085887,215160,215160,16253 AntSR,0.998995384,4.52,404,65.3 LoongSR,0.998943182,5729,5729,708 IN2GM,0.998964858,46.5,526,64.3 z6,0.998983751,5.49,330,67.4 AIO_MAI,0.998950458,41.1,610,96.1 AntYSP,0.998990747,4.33,338,54.9
+```
+
+3. EfficientNet B0–B7, ImageNet top-1 vs FLOPs and params (2 resources simultaneously) — [arXiv:1905.11946](https://arxiv.org/pdf/1905.11946), Table 2
+```bash
+python -m ab.nn.select --rank B7,0.843000000,37,66 B0,0.771000000,0.39,5.3 B4,0.829000000,4.2,19 B6,0.840000000,19,43 B2,0.801000000,1,9.2 B1,0.791000000,0.7,7.8 B3,0.816000000,1.8,12 B5,0.836000000,9.9,30
+```
+
+4. YOLO11, mAP vs 4 resources — T4 TensorRT10 ms, CPU ONNX ms, params (M), FLOPs (B) — [Ultralytics YOLO11 docs](https://docs.ultralytics.com/models/yolo11/)
+```bash
+python -m ab.nn.select --rank YOLO11l,0.534000000,6.2,238.6,25.3,87.2 YOLO11m,0.515000000,4.7,183.2,20.1,68.1 YOLO11x,0.547000000,11.3,462.8,56.9,195.3 YOLO11n,0.395000000,1.5,56.1,2.6,6.5 YOLO11s,0.470000000,2.5,90.0,9.4,21.6
+```
+
+5. MAI 2021 camera scene detection, Top-1 vs A11 Bionic runtime — [CVPRW 2021](https://openaccess.thecvf.com/content/CVPR2021W/MAI/papers/Ignatov_Fast_and_Accurate_Quantized_Camera_Scene_Detection_on_Smartphones_Mobile_CVPRW_2021_paper.pdf)
+```bash
+python -m ab.nn.select --rank Airia-Det,0.9300,17.51 Sidiki,0.7800,1.74 ByteScene,0.9500,4.44 MobileNet-V2,0.9417,16.38 PyImageSearch,0.8967,45.88 ALONG,0.9467,64.45 neptuneai,0.8367,4.17 EVAI,0.9300,3.35 DataArt,0.9150,54.13 Team-Horizon,0.9233,7.7
+```
+
+A CSV works too, with headers guessed or named:
+```bash
+python -m ab.nn.select models.csv --rank --acc-col top1 --res-col latency_ms --res-col params_M
+```
+
+### Other options
+
+| flag | effect |
+|---|---|
+| `--rank` | order every model winner to loser (otherwise only the winner) |
+| `--out-csv FILE` | write the ranking to CSV (`-` for stdout) |
+| `--alpha 0.05` | coverage level for the rate interval |
+| `--boot N` | max bootstrap refits; skipped automatically once the frontier has 50+ points |
+| `--no-color`, `--quiet` | plain text / suppress the report |
+
+Exit codes: `0` clean, `1` `UNVERIFIED` or `UNUSABLE`, `2` bad input.
+
+Scale: thousands of candidates are fine — they collapse to a frontier of a few
+hundred, and the fit runs on that. 20,000 models rank in about 1 second.

nn_rank-0.0.1/README.md

@@ -0,0 +1,188 @@
+# AI Ranking
+
+Ranks neural networks by the **accuracy–resource trade-off** and returns one
+score per model. There is no weight to choose: the exchange rate between
+accuracy and cost is derived from the candidates' own frontier.
+
+## Create and Activate a Virtual Environment (recommended)
+
+For Linux/Mac:
+```bash
+python3 -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+```
+
+For Windows:
+```bash
+python3 -m venv .venv
+.venv\Scripts\activate
+python -m pip install --upgrade pip
+```
+
+```bash
+python -m pip install --upgrade pip
+pip install -r requirements.txt
+```
+
+## Use as an API
+
+```python
+import pandas as pd
+from ab.nn.select import select
+
+df = pd.DataFrame({
+    "name":     ["B0",   "B1",  "B2",  "B3",  "B4",  "B5",  "B6",  "B7"],
+    "accuracy": [0.771, 0.791, 0.801, 0.816, 0.829, 0.836, 0.840, 0.843],
+    "flops_B":  [0.39,  0.70,  1.0,   1.8,   4.2,   9.9,   19,    37],
+    "params_M": [5.3,   7.8,   9.2,   12,    19,    30,    43,    66],
+})
+
+r = select(df, res_col=["flops_B", "params_M"], rank=True)
+
+r["winner"]["name"]       # 'B0'      <- the selected model
+r["winner"]["score"]      # 0.7140    <- its score, higher is better
+r["verdict"]["level"]     # 'USABLE' | 'UNVERIFIED' | 'UNUSABLE'
+r["ranking"]              # DataFrame: name, score, rank, ...
+```
+
+### Input
+
+One row per model, in a `pandas.DataFrame`:
+
+| column | required | meaning |
+|---|---|---|
+| `name` | yes | model identifier |
+| `accuracy` | yes | quality in **(0, 1)**, strictly between 0 and 1 |
+| one or more resource columns | yes | anything you spend: latency, FLOPs, parameters, memory, energy. Each **> 0** |
+
+`select(df, res_col=...)` names the resource column(s) — a string for one, a
+list for several. All models must be measured on the **same test set and the
+same device**, and each resource in **one fixed unit**.
+
+Quality that is not already in (0, 1) must be converted first. For PSNR in dB,
+`accuracy = 1 - 10 ** (-PSNR / 10)`. For top-1, mAP, mIoU, SSIM or F1, use the
+value as it is.
+
+### Output
+
+`select()` returns a dict. The three things most users need:
+
+| key | what it is |
+|---|---|
+| `winner["name"]` | **the selected model** |
+| `winner["score"]` | **its score** — higher is better |
+| `ranking` | a `DataFrame`, winner first: `name`, `score`, `rank`, `accuracy`, each resource, `sigma`, `eps_eff`, `margin_to_next`, `rank_low`, `rank_high`, `note` |
+
+Also returned: `verdict`, `status`, `prices` (one price per resource axis),
+`rate`, `price_free` (dominations true at every price), `front`, `fit`,
+`envelope`, `axis_drop`, `next`, `notes`, `problems`. `select()` prints
+nothing and raises nothing; bad input comes back as `status="bad_input"` with
+the offending rows listed in `problems`.
+
+### The score
+
+```
+score   = 1 / (1 + eps_eff)
+eps_eff = eps * product over axes of (resource ** lambda)      eps = 1 - accuracy
+```
+
+`eps_eff` is **the error the model effectively costs once its resources are
+charged** at the derived price `lambda`; `score` is that mapped into (0, 1) so
+that **higher is better**.
+
+Its one useful property: it is computed from a single model's own accuracy and
+resources, and from nothing else. **Adding or removing other models cannot
+change it** — unlike `rank`, or any score normalised over the candidate set.
+So scores are comparable across runs and across published tables.
+
+Two things it is *not* invariant to:
+
+- **the resource unit** — milliseconds vs seconds shifts every score by the
+  same constant, so the ordering is untouched but the numbers are not
+  comparable unless the unit is fixed;
+- **`lambda`** — only compare scores derived at the same price.
+
+### Read the verdict before the ranking
+
+`verdict["level"]` says whether the ranking means anything. A clean run prints
+nothing; a problem prints in red, first.
+
+| level | meaning |
+|---|---|
+| `USABLE` | the error floor is confirmed by a nested F-test, so an exchange rate exists and the ranking is a genuine trade-off ranking |
+| `UNVERIFIED` | too few points on the frontier to test the floor, or its knee lies outside the measured range — the ranking is a guess |
+| `UNUSABLE` | the floor is rejected: no exchange rate exists in this data, and the ranking collapses to resource order |
+
+`UNVERIFIED` and `UNUSABLE` still return a full ranking — labelled, not
+withheld. What holds regardless of the verdict is `price_free`: a model beaten
+on accuracy **and** on every resource can never win at any price.
+
+### How many models are needed
+
+Counts refer to candidates that **survive the cull**, not those supplied.
+
+| surviving | behaviour |
+|---|---|
+| **8 or more** | the floor test identifies a rate reliably — `USABLE` expected |
+| 6–7 | the papers' threshold, but noise-sensitive: identification 81% at 1% accuracy noise, 9% at 3% |
+| 3–5 | the floor cannot be tested; a ranking is returned, labelled `UNVERIFIED` |
+
+Fewer still ranks usefully: the exponent's precision is flat from three to ten
+candidates when a floor is present, and `price_free` dominations hold at any
+price. On MAI 2021, three surviving candidates of ten recovered the official
+top two and identified six of the nine entries as dominated.
+
+Competition leaderboards rarely reach eight by construction: their rules fix
+quality at a threshold and compete on cost, so the surviving frontier is short
+and carries little curvature.
+
+## Usage examples
+
+Ranked by the accuracy–time trade-off, no weight to choose. Any bare argument
+containing a comma is a candidate: `name,accuracy,p1[,p2,...]`.
+
+1. MAI 2026 INT8, SSIM vs inference time ms (NPU) — [arXiv:2611.00963](https://arxiv.org/pdf/2611.00963)
+```bash
+python -m ab.nn.select --rank koreatechV2,0.8499,4.35 Godzilla,0.8831,215160 AntSR,0.8731,4.52 LoongSR,0.8586,5729 IN2GM,0.8701,46.5 z6,0.8699,5.49 AIO_MAI,0.8634,41.1 AntYSP,0.8729,4.33
+```
+
+2. MAI 2026 INT8, PSNR converted to (0,1) vs 3 resources — NPU ms, CPU ms, model size (KB) — [arXiv:2611.00963](https://arxiv.org/pdf/2611.00963)
+```bash
+python -m ab.nn.select --rank koreatechV2,0.998758348,4.35,464,77.1 Godzilla,0.999085887,215160,215160,16253 AntSR,0.998995384,4.52,404,65.3 LoongSR,0.998943182,5729,5729,708 IN2GM,0.998964858,46.5,526,64.3 z6,0.998983751,5.49,330,67.4 AIO_MAI,0.998950458,41.1,610,96.1 AntYSP,0.998990747,4.33,338,54.9
+```
+
+3. EfficientNet B0–B7, ImageNet top-1 vs FLOPs and params (2 resources simultaneously) — [arXiv:1905.11946](https://arxiv.org/pdf/1905.11946), Table 2
+```bash
+python -m ab.nn.select --rank B7,0.843000000,37,66 B0,0.771000000,0.39,5.3 B4,0.829000000,4.2,19 B6,0.840000000,19,43 B2,0.801000000,1,9.2 B1,0.791000000,0.7,7.8 B3,0.816000000,1.8,12 B5,0.836000000,9.9,30
+```
+
+4. YOLO11, mAP vs 4 resources — T4 TensorRT10 ms, CPU ONNX ms, params (M), FLOPs (B) — [Ultralytics YOLO11 docs](https://docs.ultralytics.com/models/yolo11/)
+```bash
+python -m ab.nn.select --rank YOLO11l,0.534000000,6.2,238.6,25.3,87.2 YOLO11m,0.515000000,4.7,183.2,20.1,68.1 YOLO11x,0.547000000,11.3,462.8,56.9,195.3 YOLO11n,0.395000000,1.5,56.1,2.6,6.5 YOLO11s,0.470000000,2.5,90.0,9.4,21.6
+```
+
+5. MAI 2021 camera scene detection, Top-1 vs A11 Bionic runtime — [CVPRW 2021](https://openaccess.thecvf.com/content/CVPR2021W/MAI/papers/Ignatov_Fast_and_Accurate_Quantized_Camera_Scene_Detection_on_Smartphones_Mobile_CVPRW_2021_paper.pdf)
+```bash
+python -m ab.nn.select --rank Airia-Det,0.9300,17.51 Sidiki,0.7800,1.74 ByteScene,0.9500,4.44 MobileNet-V2,0.9417,16.38 PyImageSearch,0.8967,45.88 ALONG,0.9467,64.45 neptuneai,0.8367,4.17 EVAI,0.9300,3.35 DataArt,0.9150,54.13 Team-Horizon,0.9233,7.7
+```
+
+A CSV works too, with headers guessed or named:
+```bash
+python -m ab.nn.select models.csv --rank --acc-col top1 --res-col latency_ms --res-col params_M
+```
+
+### Other options
+
+| flag | effect |
+|---|---|
+| `--rank` | order every model winner to loser (otherwise only the winner) |
+| `--out-csv FILE` | write the ranking to CSV (`-` for stdout) |
+| `--alpha 0.05` | coverage level for the rate interval |
+| `--boot N` | max bootstrap refits; skipped automatically once the frontier has 50+ points |
+| `--no-color`, `--quiet` | plain text / suppress the report |
+
+Exit codes: `0` clean, `1` `UNVERIFIED` or `UNUSABLE`, `2` bad input.
+
+Scale: thousands of candidates are fine — they collapse to a frontier of a few
+hundred, and the fit runs on that. 20,000 models rank in about 1 second.