netoptim 0.3__tar.gz → 0.4__tar.gz

{netoptim-0.3 → netoptim-0.4}/.github/workflows/multi-platforms.yml

@@ -10,7 +10,7 @@ jobs:
         os: ["ubuntu-latest", "windows-latest"]
         version: ["3.9", "3.11"]
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - uses: conda-incubator/setup-miniconda@v3
         with:
           activate-environment: test

{netoptim-0.3 → netoptim-0.4}/.github/workflows/python-app.yml

@@ -14,9 +14,9 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Set up Python 3.9
-        uses: actions/setup-python@v2
+        uses: actions/setup-python@v5
         with:
           python-version: 3.9
       - name: Install dependencies
@@ -40,7 +40,7 @@ jobs:
       - name: Codecov
         # You may pin to the exact commit or the version.
         # uses: codecov/codecov-action@29386c70ef20e286228c72b668a06fd0e8399192
-        uses: codecov/codecov-action@v1.5.2
+        uses: codecov/codecov-action@v4
         with:
           # Repository upload token - get it from codecov.io. Required only for private repositories
           token: ${{ secrets.CODECOV_TOKEN }}

{netoptim-0.3 → netoptim-0.4}/.github/workflows/python-package.yml

@@ -18,7 +18,7 @@ jobs:
         python-version: ["3.9", "3.11"]
 
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@v4
         with:

{netoptim-0.3 → netoptim-0.4}/.gitignore

@@ -180,3 +180,6 @@ MANIFEST
 # Cache dirs
 .ruff_cache/
 .benchmarks/
+
+# Downloaded reference papers -- not redistributable, see refs/README.md
+refs/*.pdf

netoptim-0.4/AGENTS.md

@@ -0,0 +1,121 @@
+# AGENTS.md - Agent Guidelines for netoptim
+
+## Build/Lint/Test Commands
+
+### Testing
+```bash
+# Run all tests (coverage on by default)
+pytest
+
+# Run single test
+pytest tests/test_network_oracle.py::test_network_oracle_update
+
+# Run tests matching a pattern
+pytest -k "cycle_finder"
+
+# With explicit coverage
+pytest --cov netoptim --cov-report term-missing
+
+# Run via tox (isolated environment)
+tox
+```
+
+### Linting & Formatting
+```bash
+# Run all pre-commit hooks (recommended before committing)
+pre-commit run --all-files
+
+# Individual tools
+black .               # Format code (line length 256)
+isort .               # Sort imports
+flake8 .              # Lint (max_line_length=256, ignores E203/W503)
+mypy src/             # Type check (Python 3.12 target)
+```
+
+### Build & Docs
+```bash
+tox -e build          # Build sdist + wheel
+tox -e clean          # Remove build artifacts
+tox -e docs           # Build HTML docs
+tox -e doctests       # Run doctests
+tox -e linkcheck      # Check for broken doc links
+```
+
+## Code Style Guidelines
+
+### Project Structure
+- Source code: `src/netoptim/`
+- Tests: `tests/` (test_network_oracle.py, test_optscaling.py, test_cycle_finder.py, test_ratio.py, test_delay_padding.py, test_stress_*.py)
+- Version managed via setuptools_scm (`no-guess-dev` scheme)
+
+### Naming Conventions
+- **Classes**: PascalCase (e.g., `NetworkOracle`, `OptScalingOracle`)
+- **Inner classes**: Nested PascalCase for helpers (e.g., `OptScalingOracle.Ratio`)
+- **Functions/Methods**: snake_case (e.g., `assess_feas`, `assess_optim`, `update`)
+- **Type aliases**: Short PascalCase (e.g., `Cut = Tuple[Any, float]`, `Graph = Dict[...]`, `Arr = np.ndarray`)
+- **Private attributes**: Single underscore prefix (e.g., `_gra`, `_potential`, `_ncf`)
+
+### Type Hints
+- **Required**: All function parameters and return types
+- Type aliases documented with module-level string docstrings
+- Oracle interfaces typed against `ellalgo.ell_typing` (`OracleOptim`, `OracleFeas`)
+- Generic types used where appropriate (e.g., `NegCycleFinder[Any, Any, float]`)
+
+### Docstrings
+- **Primary style**: Sphinx/reStructuredText with `:param:`, `:type:`, `:return:`
+- **Alternative**: Google-style `Args:`/`Returns:` sections
+- **Examples**: doctest blocks with `>>>` (use `unittest.mock.Mock` for graph oracles)
+- **Diagrams**: `.. svgbob::` ASCII art for constraint descriptions
+
+### Imports
+- **Order**: stdlib → third-party → local (PEP8, enforced by isort)
+- Relative import for package-local module:
+  ```python
+  from .network_oracle import NetworkOracle
+  ```
+
+### Error Handling
+- **Minimal explicit error handling** — rely on natural exceptions
+- Oracles return `(Cut, value)` tuples; `None` value signals infeasible/continuing
+- No `assert` preconditions or `try/except` in algorithm code
+
+### Python Version
+- Minimum: Python 3.9 (setup.cfg `python_requires`)
+- CI tests on Python 3.9 and 3.11
+
+### Configuration Files
+- `setup.cfg`: package metadata, pytest options, flake8 config
+- `.flake8`: formatter-friendly (ignores E1/E2/E3/E501/W1/W2/W3/W5)
+- `.pre-commit-config.yaml`: pre-commit hooks
+- `mypy.ini`: Python 3.12 target, ignores setuptools/matplotlib/digraphx/ellalgo/mywheel
+- `pyproject.toml`: build system (setuptools_scm)
+- `tox.ini`: task automation (test, build, clean, docs, doctests, linkcheck, publish)
+- `.coveragerc`: branch coverage, excludes `__repr__`, debug, and assertion code
+
+### Pre-commit Hooks
+- trailing-whitespace
+- check-added-large-files
+- check-ast
+- check-json / check-yaml / check-xml
+- check-merge-conflict
+- debug-statements
+- end-of-file-fixer
+- requirements-txt-fixer
+- mixed-line-ending (auto-fix)
+- isort
+- black
+- flake8
+
+### Testing Patterns
+- Framework: pytest with coverage (addopts: `--cov netoptim --cov-report term-missing --verbose`)
+- Custom mock oracle classes (e.g., `MockOracle` in tests) replace external oracles
+- Graph fixtures built from `networkx` (`nx.DiGraph`)
+- Stress tests (`test_stress_*.py`) exercise iteration bounds
+
+## Key Project Context
+
+netoptim solves parametric network flow optimization problems using cutting-plane/ellipsoid methods:
+- **NetworkOracle**: feasibility oracle that detects negative cycles via Howard's algorithm (from `digraphx`) and emits a cutting plane `(gradient, intercept)` for each infeasible point
+- **OptScalingOracle**: optimal matrix scaling (Orlin & Rothblum) built on the network oracle, exposing `assess_optim` for `cutting_plane_optim`
+- **Solver backend**: `ellalgo` cutting-plane and ellipsoid routines; `digraphx` for negative-cycle search; `mywheel` for graph adapters
+- **Key dependencies**: `digraphx`, `ellalgo`, `mywheel`, `networkx`, `numpy`

netoptim-0.4/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## Version 0.4 (2026-10-09)
+
+### Features
+- **Oracle facades + `EdgeOracle` protocol**: Added `_typing.py` (`EdgeOracle` Protocol + `Cut` alias), re-exported the oracles from `__init__.py`, and added `solve_network_feas` / `solve_opt_scaling` facades. `OptScalingOracle.Ratio` gained its missing `update()` no-op. (#9137d2f)
+- **Tighter default optimizer settings**: `DEFAULT_TOLERANCE` tightened to `1e-10` (was `1e-8`; measured ~1e-5 vs ~1e-4 objective error for ~10–15 extra iterations), and `solve_opt_scaling`'s `gamma` now defaults to `float('inf')`. (#1d36ef0)
+
+### Performance
+- **Oracle hot path + Options forwarding**: Forward `Options` through the facades (default `1e-8` vs ellalgo's `1e-20`: 51→27 iterations on the stress graph); added an optional `EdgeOracle.make_weight_fn` hook with `Ratio` binding `x[0]`/`x[1]` once per assessment to avoid NumPy scalar indexing in the per-edge loop. Measured ~300 ms → ~90 ms (3.4×) on the 250-node / 1844-edge optscaling stress graph with identical gamma. (#505fab2)
+
+### Bug Fixes
+- **`solve_network_feas` facade**: It called `cutting_plane_optim` (needs `assess_optim`) and raised `AttributeError`; now calls `cutting_plane_feas` and drops the unused `x0` argument. `NetworkOracle` now nominally subclasses `OracleFeas`, making mypy clean. (#505fab2)
+- **`Ratio.update()` latent `AttributeError`**: Added the missing no-op. (#9137d2f)
+- **mypy config**: Removed the duplicate `ignore_missing_imports` entry. (#8aa12b1)
+- **RTD docs build**: Added matplotlib to `docs/requirements.txt`. (#be689e8)
+
+### Testing & Code Quality
+- **Oracle tests**: Added tests for the `make_weight_fn` hook, Options forwarding, and the feasibility facade. (#505fab2)
+
+### Code Cleanup
+- **Removed AI slop**: Stripped docstring/comment boilerplate and expanded the `EdgeOracle` protocol stubs to multi-line. (#94f68b0, #d62cc66)
+
+### Documentation
+- **Clock-skew scheduling survey paper + slides**: Added a 16-page two-column Pandoc survey (`paper/clock_skew_scheduling.md`) and a 30-minute Beamer deck (41 frames) with a vendored IEEE CSL, TikZ figures, offline build Makefiles, and reference-availability notes. (#1f0df97, #59b61e2, #ab91ef7, #1fc930c, #25981dd)
+- **Tunable parameter reference**: Added `tunable_parameter.md`. (#7afef62)
+- **AGENTS.md**: Added agent guidelines. (#6e36a7f)
+
+### Build & CI
+- **Updated GitHub Actions**: `checkout`→v4, `setup-python`→v5, `codecov-action`→v4; removed the stale `.bak` workflow files. (#6016c29, #5351aa8)
+
+## Version 0.3 (2026-07-16)
+
+### Documentation
+- **plot_directive with network flow examples**: Enabled matplotlib plot_directive for auto-generated figures. Added network flow and network oracle example plots. (#4ae94a8)
+
+### Bug Fixes
+- **mypy type annotation fixes**: Annotated `NegCycleFinder` with `float Domain` to prevent `int` default. Fixed `NetworkOracle.__init__` parameter types to `Dict[Any, float]`. (#336ef29)
+- **Float literal normalization**: Normalized integer literals to float in test graph data across cycle_finder, ratio, and stress_optscaling tests for type consistency. (#30f5d7a)
+- **Re-enabled disabled tests**: Fixed type annotations in `test_delay_padding` and re-enabled `test_maximize_slack`, `test_maximize_effective_slack`. (#8a76500)
+
+### Testing & Code Quality
+- **Delay padding implementation**: Added delay padding with enhanced cycle finder test cases. (#9df6788)
+- **Additional cycle finder tests**: Added extra test cases for cycle finder algorithms. (#9df6788)
+
+### Code Cleanup
+- **Removed PyScaffold boilerplate**: Deleted `skeleton.py`/`test_skeleton.py`, removed Python < 3.9 compat, dead entry points, stale `IFLOW.md`, duplicate `LICENSE`. (#4cd5756)
+
+### Build & CI
+- **CI repair**: Fixed broken entry_points and remaining skeleton imports. (#c2bf0d3)
+- **Dependency fixes**: Added explicit `mywheel` dep, PyPI-compatible version pins, removed redundant git+https installs. (#81b59c8, #2d232b7, #f07e1bf)

{netoptim-0.3/src/netoptim.egg-info → netoptim-0.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: netoptim
-Version: 0.3
+Version: 0.4
 Summary: Network Optimization Python Code
 Home-page: https://github.com/luk036/netoptim
 Author: Wai-Shing Luk

{netoptim-0.3 → netoptim-0.4}/docs/requirements.txt

@@ -8,3 +8,4 @@ myst-parser[linkify]
 numpy
 sphinx>=3.2.1
 sphinxcontrib-svgbob
+matplotlib

{netoptim-0.3 → netoptim-0.4}/mypy.ini

@@ -5,16 +5,6 @@ warn_unused_configs = True
 [mypy-setuptools.*]
 ignore_missing_imports = True
 
-ignore_missing_imports = True
-
-ignore_missing_imports = True
-
-ignore_missing_imports = True
-
-ignore_missing_imports = True
-
-ignore_missing_imports = True
-
 [mypy-matplotlib.*]
 ignore_missing_imports = True
 

netoptim-0.4/paper/.gitignore

@@ -0,0 +1,8 @@
+# Build artifacts (regenerable via `make`)
+clock_skew_scheduling.tex
+clock_skew_scheduling.html
+*.aux
+*.log
+*.out
+*.fls
+*.fdb_latexmk

netoptim-0.4/paper/Makefile

@@ -0,0 +1,53 @@
+# Build pipeline for the "Clock Skew Scheduling" survey.
+#
+# Flag rationale (see also the md-to-latex skill):
+#   --citeproc --csl=ieee.csl : IEEE numeric in-text citations and a numeric
+#       reference list.  ieee.csl is *vendored* in this directory and is
+#       self-contained (it has no <link rel="independent-parent">), so the
+#       build needs no network access.  Verified offline with
+#       HTTP_PROXY=http://127.0.0.1:9.
+#   -N                        : number sections/subsections.
+#   --pdf-engine=pdflatex     : all mathematics and text are ASCII, so pdflatex
+#       is sufficient; no xelatex/font fallback is required.
+#   -V geometry:margin=1in    : comfortable single-column page.
+#
+# Figures are *native TikZ* included via \input{figures/*.tikz}.  We do NOT
+# convert the source SVGs with rsvg-convert: without a font configuration it
+# silently drops every <text> element, producing empty figures.  Compiling the
+# original .tikz sources keeps the labels (text) intact and the output vector.
+#
+# We deliberately do NOT use pandoc-crossref/cleveref.  Plain LaTeX
+# \label/\ref/\eqref is used for every cross-reference; this is robust across
+# document classes and avoids the cleveref/\newlabel conflicts that render
+# references as "??" with older classes.
+
+PANDOC ?= pandoc
+CSL    ?= ieee.csl
+BIB    ?= refs.bib
+MD      = clock_skew_scheduling.md
+OUT     = clock_skew_scheduling.pdf
+
+PDFFLAGS = -s -t latex -N --pdf-engine=pdflatex \
+           --pdf-engine-opt=-interaction=nonstopmode \
+           --citeproc --csl=$(CSL) \
+           -V geometry:margin=1in
+
+.PHONY: paper pdf html tex clean
+
+paper: pdf
+
+pdf: $(OUT)
+
+$(OUT): $(MD) metadata.yaml latex.yaml $(BIB) $(CSL)
+	$(PANDOC) $(PDFFLAGS) metadata.yaml latex.yaml $(MD) -o $(OUT)
+
+html: $(MD) metadata.yaml latex.yaml $(BIB) $(CSL)
+	$(PANDOC) -s -t html5 --citeproc --csl=$(CSL) --mathjax \
+	  metadata.yaml latex.yaml $(MD) -o clock_skew_scheduling.html
+
+tex: $(MD) metadata.yaml latex.yaml $(BIB) $(CSL)
+	$(PANDOC) -s -t latex -N --citeproc --csl=$(CSL) \
+	  metadata.yaml latex.yaml $(MD) -o clock_skew_scheduling.tex
+
+clean:
+	rm -f $(OUT) clock_skew_scheduling.tex clock_skew_scheduling.html