flopscope 0.2.0__tar.gz → 0.4.0__tar.gz

{flopscope-0.2.0 → flopscope-0.4.0}/.github/workflows/ci.yml

@@ -137,6 +137,9 @@ jobs:
       - name: Check generated files are in sync
         run: uv run python scripts/sync_client.py --check
 
+      - name: Check package versions are in lockstep
+        run: uv run python scripts/check_version_sync.py
+
       - name: Run parity tests
         run: uv run pytest tests/test_client_server_parity.py tests/test_serialization_parity.py -v
 

{flopscope-0.2.0 → flopscope-0.4.0}/.github/workflows/pypi-publish.yml

@@ -1,8 +1,9 @@
 name: PyPI publish
 
 # Triggered when a `v*` tag is pushed (typically via `cz bump` followed by
-# `git push --follow-tags`). See AGENTS.md → "Release process" for the
-# end-to-end flow and the one-time PyPI Trusted Publisher setup.
+# `git push --follow-tags`). Publishes all published packages at the tagged
+# version under a single environment approval. See the Release docs at
+# website/content/docs/development/release.mdx.
 
 on:
   push:
@@ -13,17 +14,27 @@ on:
 permissions: {}
 
 # Never run two publish jobs for the same tag in parallel. Don't cancel an
-# in-flight publish if another tag arrives — let it finish atomically.
+# in-flight publish if another tag arrives -- let it finish atomically.
 concurrency:
   group: pypi-publish-${{ github.ref }}
   cancel-in-progress: false
 
 jobs:
   build:
-    name: Build sdist + wheel
+    name: Build ${{ matrix.package.name }}
     runs-on: ubuntu-latest
     permissions:
       contents: read
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - name: flopscope
+            path: .
+          - name: flopscope-server
+            path: flopscope-server
+          - name: flopscope-client
+            path: flopscope-client
     steps:
       - uses: actions/checkout@v4
 
@@ -31,24 +42,33 @@ jobs:
         uses: astral-sh/setup-uv@v4
 
       - name: Build distributions
+        working-directory: ${{ matrix.package.path }}
         run: uv build
 
       - name: Upload dist artifact
         uses: actions/upload-artifact@v4
         with:
-          name: dist
-          path: dist/
+          name: dist-${{ matrix.package.name }}
+          path: ${{ matrix.package.path }}/dist/
           if-no-files-found: error
 
   publish-pypi:
-    name: Publish to PyPI
+    name: Publish ${{ matrix.package.name }} to PyPI
     needs: build
     runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        package:
+          - name: flopscope
+          - name: flopscope-server
+          - name: flopscope-client
     # The `pypi` environment in repo settings has Required Reviewers
-    # configured, so this job pauses for a human approval before running.
+    # configured. A single approval click in this environment covers all
+    # three matrix entries that share it.
     environment:
       name: pypi
-      url: https://pypi.org/project/flopscope/
+      url: https://pypi.org/project/${{ matrix.package.name }}/
     permissions:
       # Required for Trusted Publishing (OIDC). No long-lived token stored.
       id-token: write
@@ -56,7 +76,7 @@ jobs:
       - name: Download dist artifact
         uses: actions/download-artifact@v4
         with:
-          name: dist
+          name: dist-${{ matrix.package.name }}
           path: dist/
 
       - name: Publish to PyPI
@@ -82,7 +102,7 @@ jobs:
             capture { print }
           ' CHANGELOG.md > release-notes.md
 
-          # Fallback if no matching section (defensive — shouldn't happen if cz bump was used).
+          # Fallback if no matching section (defensive -- shouldn't happen if cz bump was used).
           if [ ! -s release-notes.md ]; then
             printf 'Release %s\n\nSee CHANGELOG.md for details.\n' "${GITHUB_REF_NAME}" > release-notes.md
           fi

flopscope-0.4.0/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+## v0.4.0 (2026-05-26)
+
+Follow-up to v0.3.0 that completes the multi-package PyPI release. All
+three packages — `flopscope`, `flopscope-server`, `flopscope-client` —
+are now published in lockstep, each with a polished README rendering
+on its PyPI project page.
+
+### Added
+
+- `flopscope-client` first PyPI release. The Trusted Publisher block
+  on PyPI's side that deferred this package from v0.3.0 was resolved.
+  The package is now in both `build` and `publish-pypi` matrices in
+  `.github/workflows/pypi-publish.yml`, treated identically to
+  `flopscope-server`.
+- Dedicated `README.md` for `flopscope-server` and `flopscope-client`
+  (the root `flopscope` README was already present in-tree but was
+  not wired into PyPI metadata).
+- `license = "MIT"` field added to the server and client pyprojects
+  (only the root previously declared it).
+
+### Fixed
+
+- `[project].readme = "README.md"` added to all three pyproject.toml
+  files. v0.3.0 had published flopscope and flopscope-server with
+  empty descriptions because no readme was configured; v0.4.0
+  backfills them.
+
+### Tooling
+
+- The PyPI publish workflow's environment-approval gate now covers all
+  three matrix entries with a single click.
+
+## v0.3.0 (2026-05-26)
+
+Synchronized multi-package release. The `flopscope-server` package is
+published to PyPI for the first time, versioned in lockstep with
+`flopscope`. The `flopscope-client` package is built and tested in this
+release but its PyPI publish is deferred to a follow-up release pending
+resolution of a PyPI Trusted Publisher bug (the publisher-create form
+returns 500 for the `flopscope-client` project name despite the
+identical request succeeding for `flopscope-server`).
+
+### Added
+
+- `flopscope[server]` extra: `pip install "flopscope[server]"` installs
+  both flopscope and flopscope-server, exact-pinned to the same version.
+- `flopscope-server` first PyPI release. Server-side runtime for the
+  client/server architecture; pulls in flopscope as a dependency.
+- Runtime version handshake between client and server: the first
+  request from a flopscope-client to a flopscope-server compares
+  versions and raises `ConnectionError` with both versions on mismatch.
+  Code lives in both packages so the contract is in place for the
+  follow-up flopscope-client PyPI release.
+
+### Changed
+
+- `flopscope.__version__` now reflects the synchronized release line
+  (still suffixed `+np<numpy_version>`).
+- `flopscope-server`'s `flopscope` dependency is now an exact pin
+  (`flopscope==0.3.0`) so server and library always travel together.
+
+### Tooling
+
+- Commitizen `version_files` is configured to update all version
+  strings across the three packages in one `cz bump` invocation,
+  including the cross-package pin.
+- New `scripts/check_version_sync.py` and `make check-sync-versions`
+  catch drift in CI before merge.
+- `.github/workflows/pypi-publish.yml` is now a matrix workflow:
+  one `v*` tag triggers three parallel builds, three parallel
+  publishes (gated by a single `pypi` environment approval), and one
+  GitHub Release.
+
+## v0.2.0 (2026-05-26)
+
+First PyPI release.
+
+Flopscope is a NumPy-compatible math library that counts every FLOP
+analytically, so compute budgets stop being guesswork.
+
+### What's included
+
+- 508 NumPy-compatible operations with analytical FLOP cost formulas
+- Symmetry-aware einsum cost model (direct-event α/M)
+- Orbit-mapping cost model for reductions (`sum`, `mean`, `median`, …)
+- Configurable FMA cost convention (1 op vs 2 op)
+- Budget tracking via `flopscope.BudgetContext` with namespaces and
+  per-operation breakdowns
+- Symmetric tensor support via `flopscope.as_symmetric`
+- Bilinear-wrapper symmetry propagation (`matmul`, `dot`, `outer`,
+  `inner`, `vdot`, `tensordot`)
+- Public inspection helpers: `einsum_accumulation_cost`,
+  `reduction_accumulation_cost`, `tier2_reduction_cost`
+
+### Release tooling
+
+- Commitizen for version bumps + CHANGELOG management
+- Conventional-commits enforcement via a `gitlint` `commit-msg` hook
+- PyPI publishing via Trusted Publishing (OIDC, no API tokens stored)
+- Auto-created GitHub Release on every tag push
+
+See the [README](README.md) for the API overview and the
+[docs site](https://aicrowd.github.io/flopscope/) for guides and the
+full API reference.
+
+## Unreleased

{flopscope-0.2.0 → flopscope-0.4.0}/Makefile

@@ -16,7 +16,7 @@ UV    := uv run
 # Composite targets
 # ---------------------------------------------------------------------------
 .PHONY: ci
-ci: lint lint-commits typecheck test test-numpy-compat check-sync docs-build  ## Run the full CI pipeline locally
+ci: lint lint-commits typecheck test test-numpy-compat check-sync check-sync-versions docs-build  ## Run the full CI pipeline locally
 
 # ---------------------------------------------------------------------------
 # Lint  (mirrors: CI → lint job)
@@ -87,6 +87,10 @@ check-sync:  ## Verify client is in sync with core library
 	$(UV) python scripts/sync_client.py --check
 	$(UV) pytest tests/test_client_server_parity.py tests/test_serialization_parity.py -v
 
+.PHONY: check-sync-versions
+check-sync-versions:  ## Verify all package versions are in lockstep
+	$(UV) python scripts/check_version_sync.py
+
 .PHONY: sync-client
 sync-client:  ## Regenerate client files from core library
 	$(UV) python scripts/sync_client.py

flopscope-0.4.0/PKG-INFO

@@ -0,0 +1,351 @@
+Metadata-Version: 2.4
+Name: flopscope
+Version: 0.4.0
+Summary: NumPy-compatible math primitives with FLOP counting for the Mechanistic Estimation Challenge
+License-Expression: MIT
+Requires-Python: >=3.10
+Requires-Dist: numpy<2.5.0,>=2.0.0
+Requires-Dist: opt-einsum<4.0.0,>=3.3.0
+Requires-Dist: rich>=14.3.3
+Provides-Extra: dev
+Requires-Dist: commitizen>=4.0; extra == 'dev'
+Requires-Dist: gitlint>=0.19; extra == 'dev'
+Requires-Dist: psutil>=5.9; extra == 'dev'
+Requires-Dist: pyright<1.2.0,>=1.1.408; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: rich>=13.0; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Requires-Dist: scipy>=1.10; extra == 'dev'
+Provides-Extra: docs
+Requires-Dist: numpydoc>=1.10; extra == 'docs'
+Provides-Extra: server
+Requires-Dist: flopscope-server==0.3.0; extra == 'server'
+Provides-Extra: sympy
+Requires-Dist: sympy>=1.11; extra == 'sympy'
+Description-Content-Type: text/markdown
+
+<div align="center">
+<img src="website/public/logo.png" alt="flopscope" height="80">
+<h1>flopscope</h1>
+<p><strong>NumPy-compatible math primitives with analytical FLOP counting</strong></p>
+</div>
+
+<div align="center">
+
+[![PyPI version](https://img.shields.io/pypi/v/flopscope.svg)](https://pypi.org/project/flopscope/)
+[![CI](https://github.com/AIcrowd/flopscope/actions/workflows/ci.yml/badge.svg)](https://github.com/AIcrowd/flopscope/actions/workflows/ci.yml)
+[![Docs](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://aicrowd.github.io/flopscope/)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+*Built for the [ARC Whitebox Estimation Challenge](https://aicrowd.com) by [AIcrowd](https://aicrowd.com)*
+
+---
+
+**flopscope** is a drop-in replacement for a subset of NumPy that counts floating-point operations as you compute. Algorithms submitted to the ARC Whitebox Estimation Challenge are scored by their analytical FLOP cost, not wall-clock time, so researchers can focus on **algorithmic innovation** rather than hardware tuning. Every arithmetic call deducts from a fixed budget; exceed it and execution stops immediately.
+
+## Why flopscope?
+
+<table>
+<tr><th>NumPy</th><th>flopscope</th></tr>
+<tr>
+<td>
+
+```python
+import numpy as np
+
+
+depth, width = 5, 256
+
+# Weight init
+scale = np.sqrt(2 / width)
+weights = [
+    np.random.randn(width, width) * scale
+    for _ in range(depth)
+]
+
+# Forward pass
+x = np.random.randn(width)
+h = x
+for i, W in enumerate(weights):
+    h = np.einsum('ij,j->i', W, h)
+    if i < depth - 1:
+        h = np.maximum(h, 0)
+# Total FLOPs? No idea.
+```
+
+</td>
+<td>
+
+```python
+import flopscope as flops
+import flopscope.numpy as fnp
+
+depth, width = 5, 256
+
+# Weight init
+scale = fnp.sqrt(2 / width)
+weights = [
+    fnp.random.randn(width, width) * scale
+    for _ in range(depth)
+]
+
+# Forward pass
+x = fnp.random.randn(width)
+h = x
+for i, W in enumerate(weights):
+    h = fnp.einsum('ij,j->i', W, h)
+    if i < depth - 1:
+        h = fnp.maximum(h, 0)
+flops.budget_summary()  # 6,231,041 FLOPs
+```
+
+</td>
+</tr>
+</table>
+
+## Key Features
+
+- **NumPy-compatible API** -- `import flopscope.numpy as fnp` for counted NumPy ops, with `import flopscope as flops` for budgets and symmetry helpers
+- **Analytical FLOP counting** -- deterministic, hardware-independent cost tracking
+- **Budget enforcement** -- operations are checked before execution; exceeding the budget raises a clear error
+- **Symmetry-aware einsum** -- automatic FLOP savings for repeated operands and declared symmetry groups
+- **Transparent diagnostics** -- inspect per-operation costs, cumulative budget usage, and detailed summaries at any time
+- **Inspect costs analytically** -- `flops.einsum_accumulation_cost(...)` and `flops.reduction_accumulation_cost(...)` return the exact FLOP count for an einsum or reduction without running the op
+- **Truncated SVD** -- top-k singular value decomposition with `O(m * n * k)` cost
+
+## What's Supported
+
+| Module | Operations | Cost Model | Status |
+|--------|-----------|------------|--------|
+| NumPy surface (`fnp.*`) | 333 | Varies by category (unary, binary, reduction, free) | Supported |
+| `fnp.linalg` | 31 | Per-operation formulas | Supported |
+| `fnp.fft` | 18 | `5n * ceil(log2(n))` for transforms | Supported |
+| `fnp.random` | 51 | `numel(output)` per sample; shuffle: `n*ceil(log2(n))` | Supported |
+| `flops.stats` | 24 | Per-distribution CDF/PDF/PPF formulas | Supported |
+| `fnp.polynomial` | 10 | Per-operation formulas | Supported |
+| **Total** | **473 supported** | | **35 blocked** |
+
+Blocked operations (I/O, config, and system calls) raise a helpful `AttributeError` with a link to the docs.
+
+## Quick Start
+
+### Installation
+
+Latest stable release from [PyPI](https://pypi.org/project/flopscope/)
+(see [release notes](https://github.com/AIcrowd/flopscope/releases)):
+
+```bash
+uv add flopscope
+# or
+pip install flopscope
+```
+
+For the server-side toolkit (heavy install plus the flopscope-server
+process for remote-execution architectures):
+
+```bash
+pip install "flopscope[server]"
+# equivalently:
+pip install flopscope-server
+```
+
+For the lightweight client (proxies all calls to a remote
+flopscope-server over ZMQ; no numpy dependency):
+
+```bash
+pip install flopscope-client
+```
+
+The client occupies the same `import flopscope` namespace as the main
+package — install it *instead of* `flopscope`, not alongside. All three
+packages are released in lockstep at the same version. See
+[CHANGELOG.md](CHANGELOG.md) for the release notes.
+
+Latest development version from git:
+
+```bash
+uv add git+https://github.com/AIcrowd/flopscope.git
+# or
+pip install git+https://github.com/AIcrowd/flopscope.git
+```
+
+### Basic Usage
+
+```python
+import flopscope as flops
+import flopscope.numpy as fnp
+
+depth, width = 5, 256
+
+with flops.BudgetContext(flop_budget=10**8, wall_time_limit_s=5.0) as budget:
+    # Weight init
+    scale = fnp.sqrt(2 / width)
+    weights = [fnp.random.randn(width, width) * scale
+               for _ in range(depth)]
+
+    # Forward pass
+    x = fnp.random.randn(width)
+    h = x
+    for i, W in enumerate(weights):
+        h = fnp.einsum('ij,j->i', W, h)
+        if i < depth - 1:
+            h = fnp.maximum(h, 0)
+
+    print(budget.summary())   # current context summary
+
+flops.budget_summary()           # accumulated session/global summary
+```
+
+```
+flopscope FLOP Budget Summary
+=============================
+  Total budget:             100,000,000
+  Used:                       6,231,041  (6.2%)
+  Remaining:                 93,768,959  (93.8%)
+
+  By operation:
+    random.randn            5,246,976  ( 84.2%)  [6 calls]
+    einsum                    655,360  ( 10.5%)  [5 calls]
+    multiply                  327,680  (  5.3%)  [5 calls]
+    maximum                     1,024  (  0.0%)  [4 calls]
+    sqrt                            1  (  0.0%)  [1 call]
+
+  Total Wall Time:     ...s
+  Flopscope Backend:   ...s  (...%)
+  Flopscope Overhead:  ...s  (...%)
+  Residual Wall Time:  ...s  (...%)
+```
+
+### Plan Your Budget Before Executing
+
+```python
+# Query FLOP costs without running anything (no BudgetContext needed)
+cost = flops.accounting.einsum_cost('ij,jk->ik', shapes=[(256, 256), (256, 256)])
+print(f"Matmul cost: {cost:,}")  # 33,554,432
+
+cost = flops.accounting.svd_cost(m=256, n=256, k=10)
+print(f"SVD cost: {cost:,}")     # 2,621,440
+```
+
+For symmetry-aware inspection that takes actual array inputs (and reflects
+declared symmetry), use the accumulation cost APIs:
+
+```python
+import numpy as np
+A = np.zeros((256, 256))
+B = np.zeros((256, 256))
+# Returns an AccumulationCost decomposition without running the op
+cost = flops.einsum_accumulation_cost('ij,jk->ik', A, B)
+print(cost.total)                # 33,554,432
+
+cost = flops.reduction_accumulation_cost(A, op_factor=1)
+print(cost.total)                # 65,535
+```
+
+### Symmetry Savings
+
+When you pass the same array object multiple times, flopscope automatically
+detects the symmetry and reduces the FLOP count:
+
+```python
+with flops.BudgetContext(flop_budget=10**8) as budget:
+    X = fnp.ones((100, 100))
+
+    # Gram matrix: both operands are the same X.
+    # flopscope auto-detects this and induces S2{j,k} on the output,
+    # giving ~1/2 the dense cost (since R[j,k] = R[k,j]).
+    R = fnp.einsum("ij,ik->jk", X, X)
+    print(f"Cost with equal-operand detection: {budget.flops_used:,}")
+```
+
+This works for any einsum where the same Python object appears at multiple
+operand positions. See the
+[exploit-symmetry guide](website/content/docs/guides/symmetry.mdx) for more examples
+including triple products and block symmetries.
+
+## How It Works
+
+1. **FLOPs are tracked automatically.** A global default budget activates on first use, or you can wrap code in an explicit `BudgetContext` for a custom limit. Free ops (tensor creation, reshaping) cost 0 FLOPs.
+2. **FLOP costs are analytical.** Costs are computed from tensor shapes, not measured from execution. A matmul of `(m, k) @ (k, n)` always costs `m * k * n` FLOPs regardless of hardware.
+3. **Budget is checked before execution.** If an operation would exceed the remaining budget, `BudgetExhaustedError` is raised and the operation does not run.
+4. **All tensors are plain `numpy.ndarray`.** Standard flopscope arrays are regular NumPy arrays with no hidden state. `SymmetricTensor` is a lightweight `ndarray` subclass that carries symmetry metadata for einsum savings — it works everywhere a normal array does.
+
+## Sharp Edges
+
+**Budget is always active.** A global default budget (1e15 FLOPs, configurable via `FLOPSCOPE_DEFAULT_BUDGET` env var) activates automatically. Use an explicit `BudgetContext` to set a custom limit.
+
+**35 operations are blocked.** I/O, config, and system-level functions (`save`, `load`, `set_printoptions`, etc.) raise `AttributeError` by design. These have no meaningful FLOP cost and are not part of the competition API.
+
+**sort, argsort, trace, and random sampling all have analytical FLOP costs** based on their algorithmic complexity.
+
+**Nested explicit BudgetContexts are not allowed.** Opening an explicit `BudgetContext` while another explicit `BudgetContext` is already active raises `RuntimeError`. However, opening an explicit context while only the global default is active is fine — the explicit context temporarily replaces the default.
+
+**Cost is analytical, not wall-clock.** Two operations with the same shapes always report the same FLOP cost, regardless of data values, cache effects, or hardware. This is intentional -- it makes scores reproducible across machines.
+
+**SymmetricTensor propagation rules.** Symmetry metadata (used by einsum for FLOP savings) propagates through reshaping, slicing, and unary pointwise operations (e.g., `exp`, `log`). Binary pointwise operations (e.g., `add`, `multiply`) intersect the symmetry groups of both operands. Reductions may drop symmetry on the reduced axis. If the result doesn't carry the symmetry you expect, declare symmetry groups explicitly with `flops.as_symmetric()`.
+
+## Documentation
+
+**Getting Started**
+
+- [Installation & Setup](website/content/docs/getting-started/installation.mdx)
+- [Your First Budget](website/content/docs/getting-started/quickstart.mdx)
+
+**How-To Guides**
+
+- [Use Einsum](website/content/docs/guides/einsum.mdx)
+- [Exploit Symmetry](website/content/docs/guides/symmetry.mdx)
+- [Use Linear Algebra](website/content/docs/guides/linalg.mdx)
+- [Plan Your Budget](website/content/docs/guides/budget-planning.mdx)
+- [Debug Budget Overruns](website/content/docs/guides/budget-planning.mdx)
+- [Migrate from NumPy](website/content/docs/guides/migrate-from-numpy.mdx)
+
+**Concepts**
+
+- [FLOP Counting Model](website/content/docs/understanding/flop-counting-model.mdx)
+- [Operation Categories](website/content/docs/understanding/operation-categories.mdx)
+
+**Development**
+
+- [Contributor Guide](website/content/docs/development/contributing.mdx)
+
+**API Reference**
+
+- [Full API Reference](website/content/docs/api/index.mdx)
+
+**For AI Agents:**
+
+- [Cheat Sheet](website/content/docs/api/for-agents.mdx) -- compact reference for fast lookup
+
+## Development
+
+```bash
+git clone https://github.com/AIcrowd/flopscope.git
+cd flopscope
+make install
+make test                      # core test suite
+make docs-serve                # local docs at http://127.0.0.1:8000
+```
+
+For the monorepo layout, client/server workflows, and generated-doc rules, see
+[Contributor Guide](website/content/docs/development/contributing.mdx).
+
+## Citation
+
+```bibtex
+@misc{flopscope2026,
+  title  = {flopscope: NumPy-compatible math primitives with FLOP counting},
+  author = {AIcrowd},
+  year   = {2026},
+  url    = {https://github.com/AIcrowd/flopscope},
+  note   = {Built for the ARC Whitebox Estimation Challenge}
+}
+```
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)

{flopscope-0.2.0 → flopscope-0.4.0}/README.md

@@ -117,6 +117,27 @@ uv add flopscope
 pip install flopscope
 ```
 
+For the server-side toolkit (heavy install plus the flopscope-server
+process for remote-execution architectures):
+
+```bash
+pip install "flopscope[server]"
+# equivalently:
+pip install flopscope-server
+```
+
+For the lightweight client (proxies all calls to a remote
+flopscope-server over ZMQ; no numpy dependency):
+
+```bash
+pip install flopscope-client
+```
+
+The client occupies the same `import flopscope` namespace as the main
+package — install it *instead of* `flopscope`, not alongside. All three
+packages are released in lockstep at the same version. See
+[CHANGELOG.md](CHANGELOG.md) for the release notes.
+
 Latest development version from git:
 
 ```bash