netoptim 0.1__tar.gz → 0.2__tar.gz

{netoptim-0.1 → netoptim-0.2}/.github/workflows/ci.bak

@@ -8,7 +8,7 @@ on:
   push:
     # Avoid using all the resources/limits available by checking only
     # relevant branches and tags. Other branches can be checked via PRs.
-    branches: [master]
+    branches: [ master, dev ]
     tags: ['v[0-9]*', '[0-9]+.[0-9]+*']  # Match tags that resemble a version
   pull_request:  # Run in every PR
   workflow_dispatch:  # Allow manually triggering the workflow

{netoptim-0.1 → netoptim-0.2}/.github/workflows/multi-platforms.yml

@@ -8,10 +8,10 @@ jobs:
     strategy:
       matrix:
         os: ["ubuntu-latest", "windows-latest"]
-        version: ["3.9", "3.12"]
+        version: ["3.9", "3.11"]
     steps:
-      - uses: actions/checkout@v2
-      - uses: conda-incubator/setup-miniconda@v2
+      - uses: actions/checkout@v3
+      - uses: conda-incubator/setup-miniconda@v3
         with:
           activate-environment: test
           environment-file: environment.yml
@@ -31,10 +31,11 @@ jobs:
         shell: bash -l {0}
         run: |
           conda install pytest
-          python -m pip install --upgrade pip
+          conda install pip
+          conda install setuptools wheel setuptools_scm
           if [ -f requirements.txt ]; then pip install -r requirements.txt; fi
           pip install git+https://github.com/luk036/mywheel.git
           pip install git+https://github.com/luk036/ellalgo.git
           pip install git+https://github.com/luk036/digraphx.git
-          python setup.py develop
+          pip install -e .
           pytest

{netoptim-0.1 → netoptim-0.2}/.github/workflows/python-app.yml

@@ -5,9 +5,9 @@ name: Python application
 
 on:
   push:
-    branches: [master]
+    branches: [ master, dev ]
   pull_request:
-    branches: [master]
+    branches: [ master, dev ]
 
 jobs:
   build:

{netoptim-0.1 → netoptim-0.2}/.github/workflows/python-package.yml

@@ -5,9 +5,9 @@ name: Python package
 
 on:
   push:
-    branches: [master]
+    branches: [ master, dev ]
   pull_request:
-    branches: [master]
+    branches: [ master, dev ]
 
 jobs:
   build:
@@ -15,7 +15,7 @@ jobs:
     strategy:
       fail-fast: false
       matrix:
-        python-version: ["3.9", "3.12"]
+        python-version: ["3.9", "3.11"]
 
     steps:
       - uses: actions/checkout@v2

{netoptim-0.1 → netoptim-0.2}/.pre-commit-config.yaml

@@ -14,8 +14,10 @@ repos:
       - id: debug-statements
       - id: end-of-file-fixer
       - id: requirements-txt-fixer
+        exclude: "requirements[.]txt$"
       - id: mixed-line-ending
         args: ["--fix=auto"] # replace 'auto' with 'lf' to enforce Linux/Mac line endings or 'crlf' for Windows
+        exclude: "requirements[.]txt$"
 
   ## If you want to automatically "modernize" your Python code:
   # - repo: https://github.com/asottile/pyupgrade

{netoptim-0.1 → netoptim-0.2}/.readthedocs.yml

@@ -9,7 +9,7 @@ version: 2
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.12"
+    python: "3.11"
     # You can also specify other tool versions:
     # nodejs: "19"
     # rust: "1.64"

{netoptim-0.1 → netoptim-0.2}/CONTRIBUTING.md

@@ -69,27 +69,29 @@ by adding missing information and correcting mistakes.
 This means that the docs are kept in the same repository as the project code, and
 that any documentation update is done in the same way was a code contribution.
 
-```{todo} Don't forget to mention which markup language you are using.
+```{todo}
+Don't forget to mention which markup language you are using.
 
-    e.g.,  [reStructuredText] or [CommonMark] with [MyST] extensions.
+e.g.,  [reStructuredText] or [CommonMark] with [MyST] extensions.
 ```
 
-```{todo} If your project is hosted on GitHub, you can also mention the following tip:
-
-   :::{tip}
-      Please notice that the [GitHub web interface] provides a quick way of
-      propose changes in `netoptim`'s files. While this mechanism can
-      be tricky for normal code contributions, it works perfectly fine for
-      contributing to the docs, and can be quite handy.
-
-      If you are interested in trying this method out, please navigate to
-      the `docs` folder in the source [repository], find which file you
-      would like to propose changes and click in the little pencil icon at the
-      top, to open [GitHub's code editor]. Once you finish editing the file,
-      please write a message in the form at the bottom of the page describing
-      which changes have you made and what are the motivations behind them and
-      submit your proposal.
-   :::
+```{todo}
+If your project is hosted on GitHub, you can also mention the following tip:
+
+:::{tip}
+   Please notice that the [GitHub web interface] provides a quick way of
+   propose changes in `netoptim`'s files. While this mechanism can
+   be tricky for normal code contributions, it works perfectly fine for
+   contributing to the docs, and can be quite handy.
+
+   If you are interested in trying this method out, please navigate to
+   the `docs` folder in the source [repository], find which file you
+   would like to propose changes and click in the little pencil icon at the
+   top, to open [GitHub's code editor]. Once you finish editing the file,
+   please write a message in the form at the bottom of the page describing
+   which changes have you made and what are the motivations behind them and
+   submit your proposal.
+:::
 ```
 
 When working on documentation changes in your local machine, you can

netoptim-0.2/GEMINI.md

@@ -0,0 +1,64 @@
+# Gemini Code Assistant Context
+
+## Project Overview
+
+This is a Python project for **Network Optimization**. It uses `networkx` for graph-related operations. The project is set up using `PyScaffold`, and the packaging is configured in `setup.cfg`.
+
+The project's source code is located in the `src` directory, and the tests are in the `tests` directory.
+
+## Building and Running
+
+### Dependencies
+
+The main dependencies are:
+- `networkx`
+- `ellalgo`
+- `mywheel`
+- `digraphx`
+- `numpy`
+
+To install all the necessary dependencies, you can use the `requirements.txt` file:
+
+```bash
+pip install -r requirements.txt
+```
+
+### Running Tests
+
+The project uses `pytest` for testing. To run the tests, use the following command:
+
+```bash
+pytest
+```
+
+You can also use `tox` to run the tests in an isolated environment:
+
+```bash
+tox
+```
+
+### Building the Project
+
+To build the project, you can use the `build` environment in `tox`:
+
+```bash
+tox -e build
+```
+
+This will create a `dist` directory with the built package.
+
+## Development Conventions
+
+### Code Style
+
+The project uses the following tools to maintain code quality:
+
+- **Formatting:** `black` is used for code formatting.
+- **Import Sorting:** `isort` is used to sort imports automatically.
+- **Linting:** `flake8` is used for linting the code.
+
+These tools are configured in the `.pre-commit-config.yaml` file and are run automatically before each commit.
+
+### Contribution Guidelines
+
+The `CONTRIBUTING.md` file provides guidelines for contributing to the project. It is recommended to read this file before making any contributions.

netoptim-0.2/IFLOW.md

@@ -0,0 +1,85 @@
+# IFLOW.md - Network Optimization Python Code (netoptim)
+
+## 项目概述
+
+`netoptim` 是一个用于网络优化的 Python 代码库，基于 PyScaffold 4.5 创建。该项目主要解决参数化网络问题，包括网络流优化和最优矩阵缩放等。项目依赖于一些专门的库，如 `ellalgo`（椭球算法优化库）、`digraphx`（有向图处理）和 `mywheel`（工具库）。
+
+核心功能包括：
+- `NetworkOracle`：用于解决参数化网络问题的 oracle 类，通过寻找负圈来评估约束满足性
+- `OptScalingOracle`：用于最优矩阵缩放问题的 oracle 类，实现 Orlin 和 Rothblum (1985) 提出的算法
+
+## 项目结构
+
+```
+netoptim/
+├── src/netoptim/           # 源代码目录
+│   ├── __init__.py
+│   ├── network_oracle.py   # 网络 oracle 实现
+│   ├── optscaling_oracle.py # 最优缩放 oracle 实现
+│   └── py.typed
+├── tests/                  # 测试文件目录
+├── requirements/           # 依赖文件目录
+│   ├── default.txt
+│   ├── test.txt
+│   └── doc.txt
+├── pyproject.toml          # 项目构建配置
+├── setup.cfg               # 项目配置
+├── README.md               # 项目说明
+└── ...
+```
+
+## 依赖
+
+- `luk036/ellalgo` - 椭球优化算法库
+- `luk036/mywheel` - 工具库
+- `luk036/digraphx` - 有向图处理库
+- `networkx` - 网络分析库
+- `numpy` - 数值计算库
+- `icecream` - 调试输出库
+
+## 构建和运行
+
+### 安装依赖
+
+```bash
+pip install -r requirements/default.txt
+pip install -r requirements/test.txt  # 测试依赖
+```
+
+### 运行测试
+
+```bash
+pytest                    # 运行所有测试
+pytest tests/ -v          # 运行测试并显示详细信息
+pytest --cov=netoptim     # 运行测试并生成覆盖率报告
+```
+
+### 使用示例
+
+```python
+from netoptim.network_oracle import NetworkOracle
+from unittest.mock import Mock
+
+# 创建图结构
+gra = {
+    "v1": {"v2": {"w": 3}, "v3": {"w": 4}},
+    "v2": {"v1": {"w": -2}, "v3": {"w": 1}},
+    "v3": {"v1": {"w": -3}, "v2": {"w": -2}},
+}
+
+u = {"v1": 0, "v2": 0, "v3": 0}
+oracle = Mock()
+oracle.eval.side_effect = lambda e, x: e["w"] - x
+oracle.grad.side_effect = lambda e, x: -1
+
+network = NetworkOracle(gra, u, oracle)
+result = network.assess_feas(1)
+```
+
+## 开发约定
+
+- 代码遵循 PEP 8 编码风格
+- 使用 pytest 进行单元测试
+- 项目使用语义化版本控制
+- 通过 `setup.cfg` 配置项目选项和测试参数
+- 使用 `flake8` 进行代码风格检查

{netoptim-0.1 → netoptim-0.2}/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2023 Wai-Shing Luk
+Copyright (c) 2025 Wai-Shing Luk
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

{netoptim-0.1/src/netoptim.egg-info → netoptim-0.2}/PKG-INFO

@@ -1,15 +1,19 @@
 Metadata-Version: 2.4
 Name: netoptim
-Version: 0.1
+Version: 0.2
 Summary: Network Optimization Python Code
 Home-page: https://github.com/luk036/netoptim
 Author: Wai-Shing Luk
 Author-email: luk036@gmail.com
 License: MIT
-Project-URL: Documentation, https://pyscaffold.org/
+Project-URL: Documentation, https://netoptim.readthedocs.io/
+Project-URL: Source, https://github.com/luk036/netoptim
+Project-URL: Changelog, https://github.com/luk036/netoptim/blob/main/CHANGELOG.md
+Project-URL: Tracker, https://github.com/luk036/netoptim/issues
 Platform: any
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
+Requires-Python: >=3.9
 Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
 License-File: LICENSE.txt
 Requires-Dist: importlib-metadata; python_version < "3.9"
@@ -20,6 +24,7 @@ Requires-Dist: pytest; extra == "testing"
 Requires-Dist: pytest-cov; extra == "testing"
 Requires-Dist: networkx; extra == "testing"
 Requires-Dist: numpy; extra == "testing"
+Requires-Dist: icecream; extra == "testing"
 Dynamic: license-file
 
 <!-- These are examples of badges you might want to add to your README:
@@ -38,9 +43,9 @@ Dynamic: license-file
 [![Documentation Status](https://readthedocs.org/projects/netoptim/badge/?version=latest)](https://netoptim.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/luk036/netoptim/graph/badge.svg?token=BqErpMZbCK)](https://codecov.io/gh/luk036/netoptim)
 
-# 🖧 netoptim
+# 🌊 netoptim
 
-> Network Optimization Python Code
+> Network Flow Optimization Python Code
 
 A longer description of your project goes here...
 

{netoptim-0.1 → netoptim-0.2}/README.md

@@ -14,9 +14,9 @@
 [![Documentation Status](https://readthedocs.org/projects/netoptim/badge/?version=latest)](https://netoptim.readthedocs.io/en/latest/?badge=latest)
 [![codecov](https://codecov.io/gh/luk036/netoptim/graph/badge.svg?token=BqErpMZbCK)](https://codecov.io/gh/luk036/netoptim)
 
-# 🖧 netoptim
+# 🌊 netoptim
 
-> Network Optimization Python Code
+> Network Flow Optimization Python Code
 
 A longer description of your project goes here...
 

{netoptim-0.1 → netoptim-0.2}/docs/api/netoptim.rst

@@ -9,29 +9,21 @@ netoptim.network\_oracle module
 
 .. automodule:: netoptim.network_oracle
    :members:
-   :undoc-members:
    :show-inheritance:
+   :undoc-members:
 
 netoptim.optscaling\_oracle module
 ----------------------------------
 
 .. automodule:: netoptim.optscaling_oracle
    :members:
-   :undoc-members:
    :show-inheritance:
-
-netoptim.skeleton module
-------------------------
-
-.. automodule:: netoptim.skeleton
-   :members:
    :undoc-members:
-   :show-inheritance:
 
 Module contents
 ---------------
 
 .. automodule:: netoptim
    :members:
-   :undoc-members:
    :show-inheritance:
+   :undoc-members:

{netoptim-0.1 → netoptim-0.2}/docs/conf.py

@@ -9,7 +9,6 @@
 
 import os
 import sys
-import shutil
 
 # -- Path setup --------------------------------------------------------------
 
@@ -28,31 +27,6 @@ sys.path.insert(0, os.path.join(__location__, "../src"))
 # setup.py install" in the RTD Advanced Settings.
 # Additionally it helps us to avoid running apidoc manually
 
-try:  # for Sphinx >= 1.7
-    from sphinx.ext import apidoc
-except ImportError:
-    from sphinx import apidoc
-
-output_dir = os.path.join(__location__, "api")
-module_dir = os.path.join(__location__, "../src/netoptim")
-try:
-    shutil.rmtree(output_dir)
-except FileNotFoundError:
-    pass
-
-try:
-    import sphinx
-
-    cmd_line = f"sphinx-apidoc --implicit-namespaces -f -o {output_dir} {module_dir}"
-
-    args = cmd_line.split(" ")
-    if tuple(sphinx.__version__.split(".")) >= ("1", "7"):
-        # This is a rudimentary parse_version to avoid external dependencies
-        args = args[1:]
-
-    apidoc.main(args)
-except Exception as e:
-    print("Running `sphinx-apidoc` failed!\n{}".format(e))
 
 # -- General configuration ---------------------------------------------------
 
@@ -62,6 +36,7 @@ except Exception as e:
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
+    "sphinx.ext.apidoc",
     "sphinx.ext.autodoc",
     "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
@@ -72,6 +47,7 @@ extensions = [
     "sphinx.ext.ifconfig",
     "sphinx.ext.mathjax",
     "sphinx.ext.napoleon",
+    "sphinxcontrib.svgbob",
 ]
 
 # Add any paths that contain templates here, relative to this directory.
@@ -249,7 +225,7 @@ htmlhelp_basename = "netoptim-doc"
 
 # -- Options for LaTeX output ------------------------------------------------
 
-latex_elements = {
+latex_elements: dict[str, str] = {
     # The paper size ("letterpaper" or "a4paper").
     # "papersize": "letterpaper",
     # The font size ("10pt", "11pt" or "12pt").

{netoptim-0.1 → netoptim-0.2}/docs/requirements.txt

@@ -1,6 +1,10 @@
+digraphx
+ellalgo
 # Requirements file for ReadTheDocs, check .readthedocs.yml.
 # To build the module reference correctly, make sure every external package
 # under `install_requires` in `setup.cfg` is also listed here!
 # sphinx_rtd_theme
 myst-parser[linkify]
+numpy
 sphinx>=3.2.1
+sphinxcontrib-svgbob

{netoptim-0.1 → netoptim-0.2}/environment.yml

@@ -5,3 +5,4 @@ dependencies:
   - pytest
   - pytest-benchmark
   - networkx
+  - icecream

{netoptim-0.1 → netoptim-0.2}/requirements/default.txt

@@ -1,3 +1,4 @@
 decorator>=4.1.0
+icecream>=1.0
 networkx>=2.1
 numpy>=1.12.0

{netoptim-0.1 → netoptim-0.2}/requirements/doc.txt

@@ -1,2 +1,3 @@
 sphinx>=1.6.3
 sphinx_rtd_theme>=0.2.4
+sphinxcontrib-svgbob>=1.0.0

{netoptim-0.1 → netoptim-0.2}/setup.cfg

@@ -9,7 +9,10 @@ long_description = file: README.md
 long_description_content_type = text/markdown; charset=UTF-8; variant=GFM
 url = https://github.com/luk036/netoptim
 project_urls = 
-	Documentation = https://pyscaffold.org/
+	Documentation = https://netoptim.readthedocs.io/
+	Source = https://github.com/luk036/netoptim
+	Changelog = https://github.com/luk036/netoptim/blob/main/CHANGELOG.md
+	Tracker = https://github.com/luk036/netoptim/issues
 platforms = any
 classifiers = 
 	Development Status :: 4 - Beta
@@ -21,6 +24,7 @@ packages = find_namespace:
 include_package_data = True
 package_dir = 
 	=src
+python_requires = >=3.9
 install_requires = 
 	importlib-metadata; python_version<"3.9"
 	networkx
@@ -37,6 +41,7 @@ testing =
 	pytest-cov
 	networkx
 	numpy
+	icecream
 
 [options.entry_points]
 

netoptim-0.2/src/netoptim/__init__.py

@@ -0,0 +1,16 @@
+"""Network Flow Optimization Package.
+
+Provides tools for solving parametric network flow problems
+using cutting-plane methods and ellipsoid algorithms.
+"""
+
+from importlib.metadata import PackageNotFoundError, version  # pragma: no cover
+
+try:
+    # Change here if project is renamed and does not equal the package name
+    dist_name = __name__
+    __version__ = version(dist_name)
+except PackageNotFoundError:  # pragma: no cover
+    __version__ = "unknown"
+finally:
+    del version, PackageNotFoundError

netoptim-0.2/src/netoptim/network_oracle.py

@@ -0,0 +1,115 @@
+from typing import Any, Dict, Optional, Tuple, Union
+
+from digraphx.neg_cycle import NegCycleFinder
+
+Cut = Tuple[Any, float]
+"""A cutting plane represented as a tuple of (gradient, intercept).
+
+The gradient is typically a vector representing the subgradient of the
+objective function, and the intercept is the constant term in the
+linear cut.
+"""
+
+Graph = Dict[Any, Dict[Any, Union[Dict[str, Any], Tuple[Any, Any]]]]
+"""A directed graph represented as an adjacency dictionary.
+
+The outer dict maps each node to a dict of its neighbors.
+Each neighbor maps to either a dict of edge attributes (e.g., {'w': weight})
+or a tuple of (source, target) edge information.
+"""
+
+
+class NetworkOracle:
+    """Oracle for Parametric Network Problem:
+
+    The `NetworkOracle` class represents an oracle for solving a parametric network problem, where the
+    goal is to find values for variables `x` and `u` that satisfy certain constraints.
+
+    .. svgbob::
+
+        (u_i) ------ w(i,j) ------> (u_j)
+
+        u_j - u_i <= w(i,j)
+
+    |   find    x, u
+    |   s.t.    u[j] − u[i] ≤ oracle(edge, x)
+    |           ∀ edge(i, j) ∈ E
+
+    Examples:
+        >>> from unittest.mock import Mock
+        >>> gra = {
+        ...     "v1": {"v2": {"w": 3}, "v3": {"w": 4}},
+        ...     "v2": {"v1": {"w": -2}, "v3": {"w": 1}},
+        ...     "v3": {"v1": {"w": -3}, "v2": {"w": -2}},
+        ... }
+        >>> u = {"v1": 0, "v2": 0, "v3": 0}
+        >>> oracle = Mock()
+        >>> oracle.eval.side_effect = lambda e, x: e["w"] - x
+        >>> oracle.grad.side_effect = lambda e, x: -1
+        >>> network = NetworkOracle(gra, u, oracle)
+        >>> network.assess_feas(1)
+        (2, 3)
+    """
+
+    def __init__(self, gra: Graph, u: Dict[Any, int], oracle: Any) -> None:
+        """
+        Initialize the network oracle with a graph, node potentials, and an edge oracle.
+
+        :param gra: The directed graph represented as an adjacency dictionary
+            mapping each node to its neighbors and edge attributes.
+        :param u: The initial node potentials, a dictionary mapping each node
+            to its starting potential value.
+        :param oracle: The oracle object that provides `eval(edge, x)` and
+            `grad(edge, x)` methods for evaluating edge weights and their
+            subgradients at a given iterate x.
+        """
+        self._gra = gra
+        self._potential = u
+        self._oracle = oracle
+        self._ncf = NegCycleFinder(gra)
+
+    def update(self, t: float) -> None:
+        """Update the oracle with the best-so-far optimal value.
+
+        This method notifies the underlying oracle about the current best
+        feasible solution value, which may be used to refine cutting planes.
+
+        Args:
+            t: The best-so-far optimal value to update the oracle with.
+        """
+        self._oracle.update(t)
+
+    def assess_feas(self, x: Any) -> Optional[Cut]:
+        """Assess feasibility and generate a cutting plane if infeasible.
+
+        This method implements the feasibility oracle for the parametric
+        network problem. It searches for negative cycles in the graph
+        using Howard's algorithm. If a negative cycle exists, it returns
+        a cutting plane (gradient, intercept) to cut off the infeasible point.
+
+        Args:
+            x: The current iterate value to assess for feasibility.
+
+        Returns:
+            A Cut tuple (gradient, intercept) if the point is infeasible
+            (negative cycle exists), or None if feasible.
+        """
+
+        def get_weight(edge: Any) -> float:
+            """Compute the weight of an edge given the current iterate.
+
+            Args:
+                edge: The edge (i, j) to compute weight for.
+
+            Returns:
+                The oracle evaluation value for the edge at iterate x.
+            """
+            return self._oracle.eval(edge, x)
+
+        for cycle in self._ncf.howard(self._potential, get_weight):
+            f = -sum(self._oracle.eval(edge, x) for edge in cycle)
+            g = -sum(self._oracle.grad(edge, x) for edge in cycle)
+            # TODO: choose the minumum cycle
+            return g, f  # use the first cycle only
+
+        return None