netoptim 0.3__tar.gz → 0.5__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.
Files changed (149) hide show
  1. {netoptim-0.3 → netoptim-0.5}/.coveragerc +5 -0
  2. netoptim-0.5/.flake8 +4 -0
  3. {netoptim-0.3 → netoptim-0.5}/.github/workflows/jekyll-gh-pages.yml +2 -4
  4. netoptim-0.5/.github/workflows/python-app.yml +52 -0
  5. netoptim-0.5/.github/workflows/python-package.yml +45 -0
  6. {netoptim-0.3 → netoptim-0.5}/.gitignore +3 -1
  7. {netoptim-0.3 → netoptim-0.5}/.pre-commit-config.yaml +12 -4
  8. {netoptim-0.3 → netoptim-0.5}/.readthedocs.yml +2 -0
  9. netoptim-0.5/AGENTS.md +121 -0
  10. netoptim-0.5/CHANGELOG.md +73 -0
  11. {netoptim-0.3 → netoptim-0.5}/CONTRIBUTING.md +1 -1
  12. {netoptim-0.3/src/netoptim.egg-info → netoptim-0.5}/PKG-INFO +23 -4
  13. {netoptim-0.3 → netoptim-0.5}/README.md +1 -1
  14. {netoptim-0.3 → netoptim-0.5}/docs/Makefile +1 -1
  15. {netoptim-0.3 → netoptim-0.5}/docs/api/netoptim.rst +8 -0
  16. netoptim-0.5/docs/authors.md +2 -0
  17. netoptim-0.5/docs/changelog.md +2 -0
  18. {netoptim-0.3 → netoptim-0.5}/docs/conf.py +0 -1
  19. {netoptim-0.3 → netoptim-0.5}/docs/examples/plot_network_flow.py +1 -0
  20. {netoptim-0.3 → netoptim-0.5}/docs/examples/plot_network_oracle.py +1 -0
  21. netoptim-0.5/docs/readme.md +2 -0
  22. {netoptim-0.3 → netoptim-0.5}/docs/requirements.txt +3 -0
  23. {netoptim-0.3 → netoptim-0.5}/environment.yml +2 -1
  24. netoptim-0.5/mypy.ini +12 -0
  25. netoptim-0.5/paper/.gitignore +8 -0
  26. netoptim-0.5/paper/Makefile +53 -0
  27. netoptim-0.5/paper/clock_skew_scheduling.md +1791 -0
  28. netoptim-0.5/paper/clock_skew_scheduling.pdf +0 -0
  29. netoptim-0.5/paper/figures/contraction_tree.tikz +34 -0
  30. netoptim-0.5/paper/figures/fig01.pdf +0 -0
  31. netoptim-0.5/paper/figures/fig02.pdf +0 -0
  32. netoptim-0.5/paper/figures/fig04.pdf +0 -0
  33. netoptim-0.5/paper/figures/fig07.png +0 -0
  34. netoptim-0.5/paper/figures/fig18.png +0 -0
  35. netoptim-0.5/paper/figures/fig20.png +0 -0
  36. netoptim-0.5/paper/figures/fig21.png +0 -0
  37. netoptim-0.5/paper/figures/fig23.png +0 -0
  38. netoptim-0.5/paper/figures/hierachy.tikz +14 -0
  39. netoptim-0.5/paper/figures/howard.pdf +0 -0
  40. netoptim-0.5/paper/figures/hybrid.pdf +0 -0
  41. netoptim-0.5/paper/figures/improved.pdf +0 -0
  42. netoptim-0.5/paper/figures/independent.tikz +22 -0
  43. netoptim-0.5/paper/figures/lawler.pdf +0 -0
  44. netoptim-0.5/paper/figures/network.tikz +19 -0
  45. netoptim-0.5/paper/figures/no_delay.tikz +18 -0
  46. netoptim-0.5/paper/figures/non-gaussian.png +0 -0
  47. netoptim-0.5/paper/figures/same_delay.tikz +22 -0
  48. netoptim-0.5/paper/figures/setup_greater.tikz +23 -0
  49. netoptim-0.5/paper/figures/tcgraph.tikz +33 -0
  50. netoptim-0.5/paper/figures/tcgraph2.tikz +31 -0
  51. netoptim-0.5/paper/figures/tcgraph3.tikz +31 -0
  52. netoptim-0.5/paper/figures/tcgraph4.tikz +31 -0
  53. netoptim-0.5/paper/figures/tcgraph5.tikz +26 -0
  54. netoptim-0.5/paper/figures/tcgraph6.tikz +18 -0
  55. netoptim-0.5/paper/figures/tcgraph7.tikz +18 -0
  56. netoptim-0.5/paper/figures/tcgraph8.tikz +33 -0
  57. netoptim-0.5/paper/figures/tcgraph9.tikz +33 -0
  58. netoptim-0.5/paper/ieee.csl +519 -0
  59. netoptim-0.5/paper/latex.yaml +14 -0
  60. netoptim-0.5/paper/metadata.yaml +34 -0
  61. netoptim-0.5/paper/peer_review.md +438 -0
  62. netoptim-0.5/paper/refs.bib +507 -0
  63. netoptim-0.5/paper/slides/.gitignore +9 -0
  64. netoptim-0.5/paper/slides/Makefile +31 -0
  65. netoptim-0.5/paper/slides/beamer.yaml +10 -0
  66. netoptim-0.5/paper/slides/preamble.tex +46 -0
  67. netoptim-0.5/paper/slides/slides.md +444 -0
  68. netoptim-0.5/paper/slides/slides.pdf +0 -0
  69. netoptim-0.5/refs/README.md +99 -0
  70. netoptim-0.5/refs/_manifest.json +13 -0
  71. netoptim-0.5/refs/_status.csv +2 -0
  72. netoptim-0.5/refs/apply_found.py +28 -0
  73. netoptim-0.5/refs/fetch_refs.py +388 -0
  74. netoptim-0.5/refs/luk2026_lecture_algo4dfm.md +257 -0
  75. netoptim-0.5/refs/luk2026_lecture_net_optim.md +294 -0
  76. {netoptim-0.3 → netoptim-0.5}/requirements/default.txt +3 -1
  77. {netoptim-0.3 → netoptim-0.5}/setup.cfg +21 -12
  78. netoptim-0.5/src/netoptim/__init__.py +101 -0
  79. netoptim-0.5/src/netoptim/_typing.py +66 -0
  80. netoptim-0.5/src/netoptim/css_oracle.py +76 -0
  81. {netoptim-0.3 → netoptim-0.5}/src/netoptim/network_oracle.py +50 -34
  82. {netoptim-0.3 → netoptim-0.5}/src/netoptim/optscaling_oracle.py +66 -29
  83. {netoptim-0.3 → netoptim-0.5/src/netoptim.egg-info}/PKG-INFO +23 -4
  84. {netoptim-0.3 → netoptim-0.5}/src/netoptim.egg-info/SOURCES.txt +55 -9
  85. netoptim-0.5/src/netoptim.egg-info/requires.txt +25 -0
  86. netoptim-0.5/src/netoptim.egg-info/scm_file_list.json +121 -0
  87. netoptim-0.5/src/netoptim.egg-info/scm_version.json +8 -0
  88. netoptim-0.5/tests/test_network_oracle.py +178 -0
  89. {netoptim-0.3 → netoptim-0.5}/tests/test_optscaling.py +63 -0
  90. netoptim-0.5/tests/test_ratio.py +62 -0
  91. netoptim-0.5/tunable_parameter.md +100 -0
  92. netoptim-0.3/.flake8 +0 -3
  93. netoptim-0.3/.github/workflows/ci.bak +0 -128
  94. netoptim-0.3/.github/workflows/multi-platforms.bak +0 -37
  95. netoptim-0.3/.github/workflows/multi-platforms.yml +0 -41
  96. netoptim-0.3/.github/workflows/python-app.yml +0 -48
  97. netoptim-0.3/.github/workflows/python-package.yml +0 -44
  98. netoptim-0.3/AUTHORS.rst +0 -5
  99. netoptim-0.3/CHANGELOG.md +0 -22
  100. netoptim-0.3/CHANGELOG.rst +0 -10
  101. netoptim-0.3/README.rst +0 -19
  102. netoptim-0.3/docs/authors.md +0 -3
  103. netoptim-0.3/docs/changelog.md +0 -7
  104. netoptim-0.3/docs/readme.md +0 -36
  105. netoptim-0.3/mypy.ini +0 -28
  106. netoptim-0.3/src/netoptim/__init__.py +0 -16
  107. netoptim-0.3/src/netoptim.egg-info/requires.txt +0 -12
  108. netoptim-0.3/src/netoptim.egg-info/scm_file_list.json +0 -75
  109. netoptim-0.3/src/netoptim.egg-info/scm_version.json +0 -8
  110. netoptim-0.3/tests/test_cycle_finder.py +0 -141
  111. netoptim-0.3/tests/test_cycle_finder2.py +0 -178
  112. netoptim-0.3/tests/test_delay_padding.py +0 -142
  113. netoptim-0.3/tests/test_network_oracle.py +0 -68
  114. netoptim-0.3/tests/test_ratio.py +0 -83
  115. {netoptim-0.3 → netoptim-0.5}/.github/workflows/python-publish.yml +0 -0
  116. {netoptim-0.3 → netoptim-0.5}/.gitpod.yml +0 -0
  117. {netoptim-0.3 → netoptim-0.5}/.isort.cfg +0 -0
  118. {netoptim-0.3 → netoptim-0.5}/.markdownlint.json +0 -0
  119. {netoptim-0.3 → netoptim-0.5}/.shellcheckrc +0 -0
  120. {netoptim-0.3 → netoptim-0.5}/.vscode/settings.json +0 -0
  121. {netoptim-0.3 → netoptim-0.5}/AUTHORS.md +0 -0
  122. {netoptim-0.3 → netoptim-0.5}/GEMINI.md +0 -0
  123. {netoptim-0.3 → netoptim-0.5}/LICENSE.txt +0 -0
  124. {netoptim-0.3 → netoptim-0.5}/_config.yml +0 -0
  125. {netoptim-0.3 → netoptim-0.5}/docs/_static/.gitignore +0 -0
  126. {netoptim-0.3 → netoptim-0.5}/docs/api/modules.rst +0 -0
  127. {netoptim-0.3 → netoptim-0.5}/docs/contributing.md +0 -0
  128. {netoptim-0.3 → netoptim-0.5}/docs/figures_demo.md +0 -0
  129. {netoptim-0.3 → netoptim-0.5}/docs/index.md +0 -0
  130. {netoptim-0.3 → netoptim-0.5}/docs/license.md +0 -0
  131. {netoptim-0.3 → netoptim-0.5}/experiments/plot_node_colormap.ipynb +0 -0
  132. {netoptim-0.3 → netoptim-0.5}/experiments/plot_node_colormap.py +0 -0
  133. {netoptim-0.3 → netoptim-0.5}/note.md +0 -0
  134. {netoptim-0.3 → netoptim-0.5}/pyproject.toml +0 -0
  135. {netoptim-0.3 → netoptim-0.5}/requirements/README.md +0 -0
  136. {netoptim-0.3 → netoptim-0.5}/requirements/doc.txt +0 -0
  137. {netoptim-0.3 → netoptim-0.5}/requirements/test.txt +0 -0
  138. {netoptim-0.3 → netoptim-0.5}/requirements.txt +0 -0
  139. {netoptim-0.3 → netoptim-0.5}/setup.py +0 -0
  140. {netoptim-0.3 → netoptim-0.5}/src/netoptim/py.typed +0 -0
  141. {netoptim-0.3 → netoptim-0.5}/src/netoptim.egg-info/dependency_links.txt +0 -0
  142. {netoptim-0.3 → netoptim-0.5}/src/netoptim.egg-info/not-zip-safe +0 -0
  143. {netoptim-0.3 → netoptim-0.5}/src/netoptim.egg-info/top_level.txt +0 -0
  144. {netoptim-0.3 → netoptim-0.5}/tests/__init__.py +0 -0
  145. {netoptim-0.3 → netoptim-0.5}/tests/conftest.py +0 -0
  146. {netoptim-0.3 → netoptim-0.5}/tests/test_network_oracle2.py +0 -0
  147. {netoptim-0.3 → netoptim-0.5}/tests/test_stress_network_oracle.py +0 -0
  148. {netoptim-0.3 → netoptim-0.5}/tests/test_stress_optscaling.py +0 -0
  149. {netoptim-0.3 → netoptim-0.5}/tox.ini +0 -0
@@ -26,3 +26,8 @@ exclude_lines =
26
26
  # Don't complain if non-runnable code isn't run:
27
27
  if 0:
28
28
  if __name__ == .__main__.:
29
+ show_missing = True
30
+ skip_covered = False
31
+
32
+ [xml]
33
+ output = coverage.xml
netoptim-0.5/.flake8 ADDED
@@ -0,0 +1,4 @@
1
+ [flake8]
2
+ max-line-length = 256
3
+ extend-ignore = E1, E2, E3, E203, E501, W1, W2, W3, W503, W5
4
+ exclude = .tox, build, dist, .eggs, docs/conf.py, src/netoptim.egg-info
@@ -1,11 +1,9 @@
1
+ # Sphinx docs are hosted on Read the Docs; this Jekyll Pages deploy is
2
+ # manual-only to avoid a competing docs deployment.
1
3
  # Sample workflow for building and deploying a Jekyll site to GitHub Pages
2
4
  name: Deploy Jekyll with GitHub Pages dependencies preinstalled
3
5
 
4
6
  on:
5
- # Runs on pushes targeting the default branch
6
- push:
7
- branches: ["master"]
8
-
9
7
  # Allows you to run this workflow manually from the Actions tab
10
8
  workflow_dispatch:
11
9
 
@@ -0,0 +1,52 @@
1
+ # This workflow installs Python dependencies, runs tests across all supported
2
+ # Python versions, and uploads coverage to Codecov.
3
+ # For more information see:
4
+ # https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
5
+
6
+ name: Python application
7
+
8
+ on:
9
+ push:
10
+ branches: [master, dev]
11
+ pull_request:
12
+ branches: [master, dev]
13
+
14
+ permissions:
15
+ contents: read
16
+
17
+ jobs:
18
+ build:
19
+ runs-on: ${{ matrix.os }}
20
+ strategy:
21
+ fail-fast: false
22
+ matrix:
23
+ os: [ubuntu-latest]
24
+ python-version: ["3.10", "3.11", "3.12", "3.13"]
25
+ include:
26
+ # ubuntu-latest is Ubuntu 26.04, which has no Python 3.9 build in
27
+ # actions/python-versions; test 3.9 on the previous LTS instead.
28
+ - os: ubuntu-24.04
29
+ python-version: "3.9"
30
+ - os: windows-latest
31
+ python-version: "3.12"
32
+
33
+ steps:
34
+ - uses: actions/checkout@v4
35
+ - name: Set up Python ${{ matrix.python-version }}
36
+ uses: actions/setup-python@v5
37
+ with:
38
+ python-version: ${{ matrix.python-version }}
39
+ cache: pip
40
+ - name: Install dependencies
41
+ run: |
42
+ python -m pip install --upgrade pip
43
+ pip install -e ".[testing]"
44
+ - name: Test with pytest
45
+ run: |
46
+ pytest --cov=netoptim --cov-report=term-missing --cov-report=xml --cov-fail-under=90
47
+ - name: Upload coverage to Codecov
48
+ if: matrix.os == 'ubuntu-latest' && matrix.python-version == '3.12'
49
+ uses: codecov/codecov-action@v4
50
+ with:
51
+ token: ${{ secrets.CODECOV_TOKEN }}
52
+ fail_ci_if_error: true
@@ -0,0 +1,45 @@
1
+ # This workflow installs Python dependencies and runs the static-analysis,
2
+ # documentation, and packaging quality gates on a single Python version.
3
+ # For more information see:
4
+ # https://help.github.com/actions/language-and-framework-guides/using-python-with-github-actions
5
+
6
+ name: Python package
7
+
8
+ on:
9
+ push:
10
+ branches: [master, dev]
11
+ pull_request:
12
+ branches: [master, dev]
13
+
14
+ permissions:
15
+ contents: read
16
+
17
+ jobs:
18
+ quality:
19
+ runs-on: ubuntu-latest
20
+
21
+ steps:
22
+ - uses: actions/checkout@v4
23
+ - name: Set up Python 3.12
24
+ uses: actions/setup-python@v5
25
+ with:
26
+ python-version: "3.12"
27
+ - name: Install dependencies
28
+ run: |
29
+ pip install --upgrade pip
30
+ pip install -e ".[testing,docs]"
31
+ pip install mypy flake8 build twine
32
+ - name: Lint (blocking errors)
33
+ run: flake8 src tests --count --select=E9,F63,F7,F82 --show-source --statistics
34
+ - name: Lint (full style)
35
+ run: flake8 src tests --count --statistics
36
+ - name: Type check with mypy
37
+ run: mypy src/
38
+ - name: Run doctests
39
+ run: pytest --doctest-modules src/netoptim -q --no-cov
40
+ - name: Build documentation
41
+ run: sphinx-build --color -b html docs docs/_build/html
42
+ - name: Build package
43
+ run: python -m build
44
+ - name: Check package metadata
45
+ run: twine check dist/*
@@ -163,7 +163,6 @@ cython_debug/
163
163
  build/*
164
164
  dist/*
165
165
  sdist/*
166
- docs/api/*
167
166
  docs/_rst/*
168
167
  docs/_build/*
169
168
  cover/*
@@ -180,3 +179,6 @@ MANIFEST
180
179
  # Cache dirs
181
180
  .ruff_cache/
182
181
  .benchmarks/
182
+
183
+ # Downloaded reference papers -- not redistributable, see refs/README.md
184
+ refs/*.pdf
@@ -2,7 +2,7 @@ exclude: "^docs/conf.py"
2
2
 
3
3
  repos:
4
4
  - repo: https://github.com/pre-commit/pre-commit-hooks
5
- rev: v4.5.0
5
+ rev: v6.0.0
6
6
  hooks:
7
7
  - id: trailing-whitespace
8
8
  - id: check-added-large-files
@@ -11,6 +11,7 @@ repos:
11
11
  - id: check-merge-conflict
12
12
  - id: check-xml
13
13
  - id: check-yaml
14
+ exclude: ^paper/slides/beamer\.yaml$
14
15
  - id: debug-statements
15
16
  - id: end-of-file-fixer
16
17
  - id: requirements-txt-fixer
@@ -38,12 +39,12 @@ repos:
38
39
  # ]
39
40
 
40
41
  - repo: https://github.com/PyCQA/isort
41
- rev: 5.12.0
42
+ rev: 9.0.2
42
43
  hooks:
43
44
  - id: isort
44
45
 
45
46
  - repo: https://github.com/psf/black
46
- rev: 23.10.1
47
+ rev: 26.10.1
47
48
  hooks:
48
49
  - id: black
49
50
  language_version: python3
@@ -55,11 +56,18 @@ repos:
55
56
  # - id: blacken-docs
56
57
  # additional_dependencies: [black]
57
58
  - repo: https://github.com/PyCQA/flake8
58
- rev: 6.1.0
59
+ rev: 7.5.0
59
60
  hooks:
60
61
  - id: flake8
61
62
  ## You can add flake8 plugins via `additional_dependencies`:
62
63
  # additional_dependencies: [flake8-bugbear]
64
+
65
+ - repo: https://github.com/pre-commit/mirrors-mypy
66
+ rev: v2.4.1
67
+ hooks:
68
+ - id: mypy
69
+ files: ^src/
70
+ additional_dependencies: [numpy]
63
71
  ## Check for misspells in documentation files:
64
72
  # - repo: https://github.com/codespell-project/codespell
65
73
  # rev: v2.2.5
@@ -30,3 +30,5 @@ sphinx:
30
30
  python:
31
31
  install:
32
32
  - requirements: docs/requirements.txt
33
+ - method: pip
34
+ path: .
netoptim-0.5/AGENTS.md ADDED
@@ -0,0 +1,121 @@
1
+ # AGENTS.md - Agent Guidelines for netoptim
2
+
3
+ ## Build/Lint/Test Commands
4
+
5
+ ### Testing
6
+ ```bash
7
+ # Run all tests (coverage on by default)
8
+ pytest
9
+
10
+ # Run single test
11
+ pytest tests/test_network_oracle.py::test_network_oracle_update
12
+
13
+ # Run tests matching a pattern
14
+ pytest -k "network_oracle"
15
+
16
+ # With explicit coverage
17
+ pytest --cov netoptim --cov-report term-missing
18
+
19
+ # Run via tox (isolated environment)
20
+ tox
21
+ ```
22
+
23
+ ### Linting & Formatting
24
+ ```bash
25
+ # Run all pre-commit hooks (recommended before committing)
26
+ pre-commit run --all-files
27
+
28
+ # Individual tools
29
+ black . # Format code (line length 256)
30
+ isort . # Sort imports
31
+ flake8 . # Lint (max_line_length=256, ignores E203/W503)
32
+ mypy src/ # Type check (Python 3.12 target)
33
+ ```
34
+
35
+ ### Build & Docs
36
+ ```bash
37
+ tox -e build # Build sdist + wheel
38
+ tox -e clean # Remove build artifacts
39
+ tox -e docs # Build HTML docs
40
+ tox -e doctests # Run doctests
41
+ tox -e linkcheck # Check for broken doc links
42
+ ```
43
+
44
+ ## Code Style Guidelines
45
+
46
+ ### Project Structure
47
+ - Source code: `src/netoptim/`
48
+ - Tests: `tests/` (test_network_oracle.py, test_network_oracle2.py, test_optscaling.py, test_ratio.py, test_stress_network_oracle.py, test_stress_optscaling.py)
49
+ - Version managed via setuptools_scm (`no-guess-dev` scheme)
50
+
51
+ ### Naming Conventions
52
+ - **Classes**: PascalCase (e.g., `NetworkOracle`, `OptScalingOracle`)
53
+ - **Inner classes**: Nested PascalCase for helpers (e.g., `OptScalingOracle.Ratio`)
54
+ - **Functions/Methods**: snake_case (e.g., `assess_feas`, `assess_optim`, `update`)
55
+ - **Type aliases**: Short PascalCase (e.g., `Cut = Tuple[Any, float]`, `Graph = Dict[...]`, `Arr = np.ndarray`)
56
+ - **Private attributes**: Single underscore prefix (e.g., `_gra`, `_potential`, `_ncf`)
57
+
58
+ ### Type Hints
59
+ - **Required**: All function parameters and return types
60
+ - Type aliases documented with module-level string docstrings
61
+ - Oracle interfaces typed against `ellalgo.ell_typing` (`OracleOptim`, `OracleFeas`)
62
+ - Generic types used where appropriate (e.g., `NegCycleFinder[Any, Any, float]`)
63
+
64
+ ### Docstrings
65
+ - **Primary style**: Sphinx/reStructuredText with `:param:`, `:type:`, `:return:`
66
+ - **Alternative**: Google-style `Args:`/`Returns:` sections
67
+ - **Examples**: doctest blocks with `>>>` (use `unittest.mock.Mock` for graph oracles)
68
+ - **Diagrams**: `.. svgbob::` ASCII art for constraint descriptions
69
+
70
+ ### Imports
71
+ - **Order**: stdlib → third-party → local (PEP8, enforced by isort)
72
+ - Relative import for package-local module:
73
+ ```python
74
+ from .network_oracle import NetworkOracle
75
+ ```
76
+
77
+ ### Error Handling
78
+ - **Minimal explicit error handling** — rely on natural exceptions
79
+ - Oracles return `(Cut, value)` tuples; `None` value signals infeasible/continuing
80
+ - No `assert` preconditions or `try/except` in algorithm code
81
+
82
+ ### Python Version
83
+ - Minimum: Python 3.9 (setup.cfg `python_requires`)
84
+ - CI tests on Python 3.9-3.13 (Ubuntu) plus Windows 3.12; quality gate on 3.12
85
+
86
+ ### Configuration Files
87
+ - `setup.cfg`: package metadata and pytest options only
88
+ - `.flake8`: the single flake8 config (formatter-friendly: max line 256, ignores E1/E2/E3/E501/W1/W2/W3/W5 and E203/W503)
89
+ - `.pre-commit-config.yaml`: pre-commit hooks
90
+ - `mypy.ini`: Python 3.12 target, ignores setuptools/matplotlib/digraphx/ellalgo/mywheel
91
+ - `pyproject.toml`: build system (setuptools_scm)
92
+ - `tox.ini`: task automation (test, build, clean, docs, doctests, linkcheck, publish)
93
+ - `.coveragerc`: branch coverage, excludes `__repr__`, debug, and assertion code
94
+
95
+ ### Pre-commit Hooks
96
+ - trailing-whitespace
97
+ - check-added-large-files
98
+ - check-ast
99
+ - check-json / check-yaml / check-xml
100
+ - check-merge-conflict
101
+ - debug-statements
102
+ - end-of-file-fixer
103
+ - requirements-txt-fixer
104
+ - mixed-line-ending (auto-fix)
105
+ - isort
106
+ - black
107
+ - flake8
108
+
109
+ ### Testing Patterns
110
+ - Framework: pytest with coverage (addopts: `--cov netoptim --cov-report term-missing --verbose`)
111
+ - Custom mock oracle classes (e.g., `MockOracle` in tests) replace external oracles
112
+ - Graph fixtures built from `networkx` (`nx.DiGraph`)
113
+ - Stress tests (`test_stress_*.py`) exercise iteration bounds
114
+
115
+ ## Key Project Context
116
+
117
+ netoptim solves parametric network flow optimization problems using cutting-plane/ellipsoid methods:
118
+ - **NetworkOracle**: feasibility oracle that detects negative cycles via Howard's algorithm (from `digraphx`) and emits a cutting plane `(gradient, intercept)` for each infeasible point
119
+ - **OptScalingOracle**: optimal matrix scaling (Orlin & Rothblum) built on the network oracle, exposing `assess_optim` for `cutting_plane_optim`
120
+ - **Solver backend**: `ellalgo` cutting-plane and ellipsoid routines; `digraphx` for negative-cycle search; `mywheel` for graph adapters
121
+ - **Key dependencies**: `digraphx`, `ellalgo`, `mywheel`, `networkx`, `numpy`
@@ -0,0 +1,73 @@
1
+ # Changelog
2
+
3
+ ## Version 0.5 (2026-11-20)
4
+
5
+ ### Features
6
+ - **`ClockScheduleOracle`**: Shipped the two-parameter (clock period, yield) separation oracle as a public API (`netoptim.css_oracle`), promoted from the inline test oracle and re-exported from the package root.
7
+
8
+ ### Bug Fixes
9
+ - **`ClockScheduleOracle` non-positive margin**: added an explicit cut for `beta <= 0`, which previously could divide by zero (or produce `nan` from `inf * 0`) on a cycle-free graph.
10
+ - **`NetworkOracle.assess_feas` most-critical cycle**: Replaced the "first negative cycle" shortcut (and its `TODO`) with selection of the minimum-mean (most critical) cycle among Howard's output.
11
+ - **Packaging**: declared `numpy` in `install_requires` (it is imported by `css_oracle` and `optscaling_oracle`).
12
+ - **Docs**: Read the Docs now installs the package itself; added the missing `networkx`/`mywheel` docs requirements; documented `netoptim.css_oracle`; removed the non-existent `sphinx.ext.apidoc` extension.
13
+
14
+ ### Testing & Code Quality
15
+ - **Deduplicated CSS tests**: `tests/test_ratio.py` now drives the shipped `ClockScheduleOracle`; removed `test_cycle_finder.py`, `test_cycle_finder2.py`, and `test_delay_padding.py`, whose CSS-oracle logic and golden values now live in `digraphx`'s canonical `tests/test_css.py`. Dropped the now-unused `icecream` test dependency.
16
+ - Tightened the `EdgeOracle` protocol (`eval`/`grad`/`update`), added `Arr`/`Dist` aliases and a `FastEdgeOracle` protocol, and typed `get_cost`.
17
+ - Removed dead `_gra` attributes, unified node-potential naming on `dist`, deduplicated the `Arr` alias and ratio math, and named the gradient constants.
18
+ - Added tests for the `TCP < 0` / `beta <= 0` guards, most-critical-cycle selection, empty/disconnected graphs, `Options` forwarding, and the `Ratio.update` no-op (24 tests, ~98% coverage).
19
+
20
+ ### Build & CI
21
+ - Test matrix now covers Python 3.9-3.13 on Ubuntu plus Windows 3.12, with a 90% coverage gate; the Python 3.9 leg is pinned to `ubuntu-24.04` because `ubuntu-latest` no longer ships a 3.9 build.
22
+ - Added mypy, doctests, Sphinx docs, and package build/`twine check` to CI; removed the unpinned git dependency installs and `setup.py develop`.
23
+ - Consolidated flake8 configuration, refreshed the pre-commit hooks (including a mypy hook), and fixed `master` branch URLs.
24
+
25
+ ## Version 0.4 (2026-10-09)
26
+
27
+ ### Features
28
+ - **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)
29
+ - **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)
30
+
31
+ ### Performance
32
+ - **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)
33
+
34
+ ### Bug Fixes
35
+ - **`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)
36
+ - **`Ratio.update()` latent `AttributeError`**: Added the missing no-op. (#9137d2f)
37
+ - **mypy config**: Removed the duplicate `ignore_missing_imports` entry. (#8aa12b1)
38
+ - **RTD docs build**: Added matplotlib to `docs/requirements.txt`. (#be689e8)
39
+
40
+ ### Testing & Code Quality
41
+ - **Oracle tests**: Added tests for the `make_weight_fn` hook, Options forwarding, and the feasibility facade. (#505fab2)
42
+
43
+ ### Code Cleanup
44
+ - **Removed AI slop**: Stripped docstring/comment boilerplate and expanded the `EdgeOracle` protocol stubs to multi-line. (#94f68b0, #d62cc66)
45
+
46
+ ### Documentation
47
+ - **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)
48
+ - **Tunable parameter reference**: Added `tunable_parameter.md`. (#7afef62)
49
+ - **AGENTS.md**: Added agent guidelines. (#6e36a7f)
50
+
51
+ ### Build & CI
52
+ - **Updated GitHub Actions**: `checkout`→v4, `setup-python`→v5, `codecov-action`→v4; removed the stale `.bak` workflow files. (#6016c29, #5351aa8)
53
+
54
+ ## Version 0.3 (2026-07-16)
55
+
56
+ ### Documentation
57
+ - **plot_directive with network flow examples**: Enabled matplotlib plot_directive for auto-generated figures. Added network flow and network oracle example plots. (#4ae94a8)
58
+
59
+ ### Bug Fixes
60
+ - **mypy type annotation fixes**: Annotated `NegCycleFinder` with `float Domain` to prevent `int` default. Fixed `NetworkOracle.__init__` parameter types to `Dict[Any, float]`. (#336ef29)
61
+ - **Float literal normalization**: Normalized integer literals to float in test graph data across cycle_finder, ratio, and stress_optscaling tests for type consistency. (#30f5d7a)
62
+ - **Re-enabled disabled tests**: Fixed type annotations in `test_delay_padding` and re-enabled `test_maximize_slack`, `test_maximize_effective_slack`. (#8a76500)
63
+
64
+ ### Testing & Code Quality
65
+ - **Delay padding implementation**: Added delay padding with enhanced cycle finder test cases. (#9df6788)
66
+ - **Additional cycle finder tests**: Added extra test cases for cycle finder algorithms. (#9df6788)
67
+
68
+ ### Code Cleanup
69
+ - **Removed PyScaffold boilerplate**: Deleted `skeleton.py`/`test_skeleton.py`, removed Python < 3.9 compat, dead entry points, stale `IFLOW.md`, duplicate `LICENSE`. (#4cd5756)
70
+
71
+ ### Build & CI
72
+ - **CI repair**: Fixed broken entry_points and remaining skeleton imports. (#c2bf0d3)
73
+ - **Dependency fixes**: Added explicit `mywheel` dep, PyPI-compatible version pins, removed redundant git+https installs. (#81b59c8, #2d232b7, #f07e1bf)
@@ -190,7 +190,7 @@ conda activate netoptim
190
190
  2. Start your work on this branch. Don't forget to add [docstrings] to new
191
191
  functions, modules and classes, especially if they are part of public APIs.
192
192
 
193
- 3. Add yourself to the list of contributors in `AUTHORS.rst`.
193
+ 3. Add yourself to the list of contributors in `AUTHORS.md`.
194
194
 
195
195
  4. When you’re done editing, do:
196
196
 
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: netoptim
3
- Version: 0.3
3
+ Version: 0.5
4
4
  Summary: Network Optimization Python Code
5
5
  Home-page: https://github.com/luk036/netoptim
6
6
  Author: Wai-Shing Luk
@@ -8,11 +8,19 @@ Author-email: luk036@gmail.com
8
8
  License: MIT
9
9
  Project-URL: Documentation, https://netoptim.readthedocs.io/
10
10
  Project-URL: Source, https://github.com/luk036/netoptim
11
- Project-URL: Changelog, https://github.com/luk036/netoptim/blob/main/CHANGELOG.md
11
+ Project-URL: Changelog, https://github.com/luk036/netoptim/blob/master/CHANGELOG.md
12
12
  Project-URL: Tracker, https://github.com/luk036/netoptim/issues
13
13
  Platform: any
14
14
  Classifier: Development Status :: 4 - Beta
15
15
  Classifier: Programming Language :: Python
16
+ Classifier: Programming Language :: Python :: 3
17
+ Classifier: Programming Language :: Python :: 3.9
18
+ Classifier: Programming Language :: Python :: 3.10
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Operating System :: OS Independent
23
+ Classifier: Typing :: Typed
16
24
  Requires-Python: >=3.9
17
25
  Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
18
26
  License-File: LICENSE.txt
@@ -20,13 +28,24 @@ Requires-Dist: digraphx>=0.3
20
28
  Requires-Dist: ellalgo>=0.4
21
29
  Requires-Dist: mywheel>=0.3
22
30
  Requires-Dist: networkx
31
+ Requires-Dist: numpy>=1.12
23
32
  Provides-Extra: testing
24
33
  Requires-Dist: setuptools; extra == "testing"
25
34
  Requires-Dist: pytest; extra == "testing"
26
35
  Requires-Dist: pytest-cov; extra == "testing"
27
36
  Requires-Dist: networkx; extra == "testing"
28
37
  Requires-Dist: numpy; extra == "testing"
29
- Requires-Dist: icecream; extra == "testing"
38
+ Provides-Extra: docs
39
+ Requires-Dist: sphinx>=3.2.1; extra == "docs"
40
+ Requires-Dist: myst-parser[linkify]; extra == "docs"
41
+ Requires-Dist: sphinxcontrib-svgbob; extra == "docs"
42
+ Requires-Dist: matplotlib; extra == "docs"
43
+ Requires-Dist: networkx; extra == "docs"
44
+ Provides-Extra: dev
45
+ Requires-Dist: pre-commit; extra == "dev"
46
+ Requires-Dist: mypy; extra == "dev"
47
+ Requires-Dist: tox; extra == "dev"
48
+ Requires-Dist: build; extra == "dev"
30
49
  Dynamic: license-file
31
50
 
32
51
  <!-- These are examples of badges you might want to add to your README:
@@ -49,7 +68,7 @@ Dynamic: license-file
49
68
 
50
69
  > Network Flow Optimization Python Code
51
70
 
52
- A longer description of your project goes here...
71
+ `netoptim` is a Python library for solving parametric network-flow optimization problems using cutting-plane and ellipsoid methods. It provides a negative-cycle feasibility oracle (`NetworkOracle`), an optimal matrix-scaling oracle (`OptScalingOracle`) based on the Orlin–Rothblum approach, and a clock-skew scheduling oracle. The package builds on `ellalgo` for cutting-plane/ellipsoid routines, `digraphx` for negative-cycle search, and `mywheel` for graph adapters.
53
72
 
54
73
  ## Dependencies
55
74
 
@@ -18,7 +18,7 @@
18
18
 
19
19
  > Network Flow Optimization Python Code
20
20
 
21
- A longer description of your project goes here...
21
+ `netoptim` is a Python library for solving parametric network-flow optimization problems using cutting-plane and ellipsoid methods. It provides a negative-cycle feasibility oracle (`NetworkOracle`), an optimal matrix-scaling oracle (`OptScalingOracle`) based on the Orlin–Rothblum approach, and a clock-skew scheduling oracle. The package builds on `ellalgo` for cutting-plane/ellipsoid routines, `digraphx` for negative-cycle search, and `mywheel` for graph adapters.
22
22
 
23
23
  ## Dependencies
24
24
 
@@ -21,7 +21,7 @@ help:
21
21
  @$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
22
22
 
23
23
  clean:
24
- rm -rf $(BUILDDIR)/* $(AUTODOCDIR)
24
+ rm -rf $(BUILDDIR)/*
25
25
 
26
26
  # Catch-all target: route all unknown targets to Sphinx using the new
27
27
  # "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
@@ -4,6 +4,14 @@ netoptim package
4
4
  Submodules
5
5
  ----------
6
6
 
7
+ netoptim.css\_oracle module
8
+ ---------------------------
9
+
10
+ .. automodule:: netoptim.css_oracle
11
+ :members:
12
+ :show-inheritance:
13
+ :undoc-members:
14
+
7
15
  netoptim.network\_oracle module
8
16
  -------------------------------
9
17
 
@@ -0,0 +1,2 @@
1
+ ```{include} ../AUTHORS.md
2
+ ```
@@ -0,0 +1,2 @@
1
+ ```{include} ../CHANGELOG.md
2
+ ```
@@ -36,7 +36,6 @@ sys.path.insert(0, os.path.join(__location__, "../src"))
36
36
  # Add any Sphinx extension module names here, as strings. They can be extensions
37
37
  # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
38
38
  extensions = [
39
- "sphinx.ext.apidoc",
40
39
  "sphinx.ext.autodoc",
41
40
  "sphinx.ext.intersphinx",
42
41
  "sphinx.ext.todo",
@@ -4,6 +4,7 @@ Network Flow Graph
4
4
 
5
5
  Visualization of a directed flow network with edge capacities.
6
6
  """
7
+
7
8
  import matplotlib.pyplot as plt
8
9
  import networkx as nx
9
10
 
@@ -4,6 +4,7 @@ Network Oracle Example
4
4
 
5
5
  Demonstrates a parametric network with an oracle for cutting-plane optimization.
6
6
  """
7
+
7
8
  import matplotlib.pyplot as plt
8
9
  import networkx as nx
9
10
 
@@ -0,0 +1,2 @@
1
+ ```{include} ../README.md
2
+ ```
@@ -1,10 +1,13 @@
1
1
  digraphx
2
2
  ellalgo
3
+ mywheel
3
4
  # Requirements file for ReadTheDocs, check .readthedocs.yml.
4
5
  # To build the module reference correctly, make sure every external package
5
6
  # under `install_requires` in `setup.cfg` is also listed here!
6
7
  # sphinx_rtd_theme
7
8
  myst-parser[linkify]
8
9
  numpy
10
+ networkx
9
11
  sphinx>=3.2.1
10
12
  sphinxcontrib-svgbob
13
+ matplotlib
@@ -3,6 +3,7 @@ channels:
3
3
  - conda-forge
4
4
  dependencies:
5
5
  - pytest
6
+ - pytest-cov
6
7
  - pytest-benchmark
7
8
  - networkx
8
- - icecream
9
+ - numpy
netoptim-0.5/mypy.ini ADDED
@@ -0,0 +1,12 @@
1
+ [mypy]
2
+ python_version = 3.12
3
+ warn_unused_configs = True
4
+
5
+ [mypy-digraphx.*]
6
+ ignore_missing_imports = True
7
+
8
+ [mypy-ellalgo.*]
9
+ ignore_missing_imports = True
10
+
11
+ [mypy-mywheel.*]
12
+ ignore_missing_imports = True
@@ -0,0 +1,8 @@
1
+ # Build artifacts (regenerable via `make`)
2
+ clock_skew_scheduling.tex
3
+ clock_skew_scheduling.html
4
+ *.aux
5
+ *.log
6
+ *.out
7
+ *.fls
8
+ *.fdb_latexmk
@@ -0,0 +1,53 @@
1
+ # Build pipeline for the "Clock Skew Scheduling" survey.
2
+ #
3
+ # Flag rationale (see also the md-to-latex skill):
4
+ # --citeproc --csl=ieee.csl : IEEE numeric in-text citations and a numeric
5
+ # reference list. ieee.csl is *vendored* in this directory and is
6
+ # self-contained (it has no <link rel="independent-parent">), so the
7
+ # build needs no network access. Verified offline with
8
+ # HTTP_PROXY=http://127.0.0.1:9.
9
+ # -N : number sections/subsections.
10
+ # --pdf-engine=pdflatex : all mathematics and text are ASCII, so pdflatex
11
+ # is sufficient; no xelatex/font fallback is required.
12
+ # -V geometry:margin=1in : comfortable single-column page.
13
+ #
14
+ # Figures are *native TikZ* included via \input{figures/*.tikz}. We do NOT
15
+ # convert the source SVGs with rsvg-convert: without a font configuration it
16
+ # silently drops every <text> element, producing empty figures. Compiling the
17
+ # original .tikz sources keeps the labels (text) intact and the output vector.
18
+ #
19
+ # We deliberately do NOT use pandoc-crossref/cleveref. Plain LaTeX
20
+ # \label/\ref/\eqref is used for every cross-reference; this is robust across
21
+ # document classes and avoids the cleveref/\newlabel conflicts that render
22
+ # references as "??" with older classes.
23
+
24
+ PANDOC ?= pandoc
25
+ CSL ?= ieee.csl
26
+ BIB ?= refs.bib
27
+ MD = clock_skew_scheduling.md
28
+ OUT = clock_skew_scheduling.pdf
29
+
30
+ PDFFLAGS = -s -t latex -N --pdf-engine=pdflatex \
31
+ --pdf-engine-opt=-interaction=nonstopmode \
32
+ --citeproc --csl=$(CSL) \
33
+ -V geometry:margin=1in
34
+
35
+ .PHONY: paper pdf html tex clean
36
+
37
+ paper: pdf
38
+
39
+ pdf: $(OUT)
40
+
41
+ $(OUT): $(MD) metadata.yaml latex.yaml $(BIB) $(CSL)
42
+ $(PANDOC) $(PDFFLAGS) metadata.yaml latex.yaml $(MD) -o $(OUT)
43
+
44
+ html: $(MD) metadata.yaml latex.yaml $(BIB) $(CSL)
45
+ $(PANDOC) -s -t html5 --citeproc --csl=$(CSL) --mathjax \
46
+ metadata.yaml latex.yaml $(MD) -o clock_skew_scheduling.html
47
+
48
+ tex: $(MD) metadata.yaml latex.yaml $(BIB) $(CSL)
49
+ $(PANDOC) -s -t latex -N --citeproc --csl=$(CSL) \
50
+ metadata.yaml latex.yaml $(MD) -o clock_skew_scheduling.tex
51
+
52
+ clean:
53
+ rm -f $(OUT) clock_skew_scheduling.tex clock_skew_scheduling.html