netoptim 0.1__py3-none-any.whl

netoptim/__init__.py

@@ -0,0 +1,16 @@
+import sys
+
+if sys.version_info[:2] >= (3, 8):
+    # TODO: Import directly (no need for conditional) when `python_requires = >= 3.9`
+    from importlib.metadata import PackageNotFoundError, version  # pragma: no cover
+else:
+    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/network_oracle.py

@@ -0,0 +1,72 @@
+from typing import Any, Optional, Tuple
+
+from digraphx.neg_cycle import NegCycleFinder
+
+Cut = Tuple[Any, float]
+
+
+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.
+
+    |   find    x, u
+    |   s.t.    u[j] − u[i] ≤ h(edge, x)
+    |           ∀ edge(i, j) ∈ E
+    """
+
+    def __init__(self, gra, u, h):
+        """
+        The function initializes an object with a directed graph, a list or dictionary, and a function for
+        evaluation and gradient.
+
+        :param gra: The parameter `gra` is a directed graph represented by a tuple `(Node, E)`. `Node`
+        represents the set of nodes in the graph, and `E` represents the set of edges in the graph
+        :param u: The `u` parameter is either a list or a dictionary. It represents the initial values
+        of the variables in the optimization problem. The specific meaning of these variables depends on the
+        context of the optimization problem being solved
+        :param h: The parameter `h` is a function that is used for evaluation and gradient calculations. It
+        takes in some input and returns the evaluation value and gradient of that input
+        """
+        self._gra = gra
+        self._potential = u
+        self._h = h
+        self._ncf = NegCycleFinder(gra)
+
+    def update(self, t):
+        """[summary]
+
+        Arguments:
+            t (float): the best-so-far optimal value
+        """
+        self._h.update(t)
+
+    def assess_feas(self, x) -> Optional[Cut]:
+        """Make object callable for cutting_plane_feas()
+
+        Arguments:
+            x ([type]): [description]
+
+        Returns:
+            Optional[Cut]: [description]
+        """
+
+        def get_weight(edge):
+            """[summary]
+
+            Arguments:
+                edge ([type]): [description]
+
+            Returns:
+                Any: [description]
+            """
+            return self._h.eval(edge, x)
+
+        for cycle in self._ncf.howard(self._potential, get_weight):
+            f = -sum(self._h.eval(edge, x) for edge in cycle)
+            g = -sum(self._h.grad(edge, x) for edge in cycle)
+            # TODO: choose the minumum cycle
+            return g, f  # use the first cycle only
+
+        return None

netoptim/optscaling_oracle.py

@@ -0,0 +1,90 @@
+from typing import Optional, Tuple
+
+import numpy as np
+
+from .network_oracle import NetworkOracle
+
+Arr = np.ndarray
+Cut = Tuple[Arr, float]
+
+
+class OptScalingOracle:
+    """Oracle for Optimal Matrix Scaling
+
+    This example is taken from[Orlin and Rothblum, 1985]
+
+    |    min     π/ψ
+    |    s.t.    ψ ≤ u[i] * |aij| * u[j]^{−1} ≤ π,
+    |            ∀ aij != 0,
+    |            π, ψ, utx, positive
+    """
+
+    class Ratio:
+        def __init__(self, gra, get_cost):
+            """[summary]
+
+            Arguments:
+                gra ([type]): [description]
+            """
+            self._gra = gra
+            self._get_cost = get_cost
+
+        def eval(self, edge, x: Arr) -> float:
+            """[summary]
+
+            Arguments:
+                edge ([type]): [description]
+                x (Arr): (π, ψ) in log scale
+
+            Returns:
+                float: function evaluation
+            """
+            aij, aji = self._get_cost(edge)
+            return min(x[0] - aji, aij - x[1])
+
+        def grad(self, edge, x: Arr) -> Arr:
+            """[summary]
+
+            Arguments:
+                edge ([type]): [description]
+                x (Arr): (π, ψ) in log scale
+
+            Returns:
+                [type]: [description]
+            """
+            aij, aji = self._get_cost(edge)
+            if x[0] - aji < aij - x[1]:
+                return np.array([1.0, 0.0])
+            return np.array([0.0, -1.0])
+
+    def __init__(self, gra, utx, get_cost):
+        """Construct a new optscaling oracle object
+
+        Arguments:
+            gra ([type]): [description]
+        """
+        self._network = NetworkOracle(gra, utx, self.Ratio(gra, get_cost))
+
+    def assess_optim(self, x: Arr, t: float) -> Tuple[Cut, Optional[float]]:
+        """
+        Make object callable for cutting_plane_optim()
+
+        Arguments:
+            x (Arr): (π, ψ) in log scale
+            t (float): the best-so-far optimal value
+
+        Returns:
+            Tuple[Cut, Optional[float]]
+
+        See also:
+            cutting_plane_optim
+        """
+        if cut := self._network.assess_feas(x):
+            return cut, None
+
+        s = x[0] - x[1]
+        g = np.array([1.0, -1.0])
+        if (fj := s - t) > 0.0:
+            return (g, fj), None
+
+        return (g, 0.0), s

netoptim/skeleton.py

@@ -0,0 +1,149 @@
+"""
+This is a skeleton file that can serve as a starting point for a Python
+console script. To run this script uncomment the following lines in the
+``[options.entry_points]`` section in ``setup.cfg``::
+
+    console_scripts =
+         fibonacci = netoptim.skeleton:run
+
+Then run ``pip install .`` (or ``pip install -e .`` for editable mode)
+which will install the command ``fibonacci`` inside your current environment.
+
+Besides console scripts, the header (i.e. until ``_logger``...) of this file can
+also be used as template for Python modules.
+
+Note:
+    This file can be renamed depending on your needs or safely removed if not needed.
+
+References:
+    - https://setuptools.pypa.io/en/latest/userguide/entry_point.html
+    - https://pip.pypa.io/en/stable/reference/pip_install
+"""
+
+import argparse
+import logging
+import sys
+
+from netoptim import __version__
+
+__author__ = "Wai-Shing Luk"
+__copyright__ = "Wai-Shing Luk"
+__license__ = "MIT"
+
+_logger = logging.getLogger(__name__)
+
+
+# ---- Python API ----
+# The functions defined in this section can be imported by users in their
+# Python scripts/interactive interpreter, e.g. via
+# `from netoptim.skeleton import fib`,
+# when using this Python module as a library.
+
+
+def fib(n):
+    """Fibonacci example function
+
+    Args:
+      n (int): integer
+
+    Returns:
+      int: n-th Fibonacci number
+    """
+    assert n > 0
+    a, b = 1, 1
+    for _i in range(n - 1):
+        a, b = b, a + b
+    return a
+
+
+# ---- CLI ----
+# The functions defined in this section are wrappers around the main Python
+# API allowing them to be called directly from the terminal as a CLI
+# executable/script.
+
+
+def parse_args(args):
+    """Parse command line parameters
+
+    Args:
+      args (List[str]): command line parameters as list of strings
+          (for example  ``["--help"]``).
+
+    Returns:
+      :obj:`argparse.Namespace`: command line parameters namespace
+    """
+    parser = argparse.ArgumentParser(description="Just a Fibonacci demonstration")
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"netoptim {__version__}",
+    )
+    parser.add_argument(dest="n", help="n-th Fibonacci number", type=int, metavar="INT")
+    parser.add_argument(
+        "-v",
+        "--verbose",
+        dest="loglevel",
+        help="set loglevel to INFO",
+        action="store_const",
+        const=logging.INFO,
+    )
+    parser.add_argument(
+        "-vv",
+        "--very-verbose",
+        dest="loglevel",
+        help="set loglevel to DEBUG",
+        action="store_const",
+        const=logging.DEBUG,
+    )
+    return parser.parse_args(args)
+
+
+def setup_logging(loglevel):
+    """Setup basic logging
+
+    Args:
+      loglevel (int): minimum loglevel for emitting messages
+    """
+    logformat = "[%(asctime)s] %(levelname)s:%(name)s:%(message)s"
+    logging.basicConfig(
+        level=loglevel, stream=sys.stdout, format=logformat, datefmt="%Y-%m-%d %H:%M:%S"
+    )
+
+
+def main(args):
+    """Wrapper allowing :func:`fib` to be called with string arguments in a CLI fashion
+
+    Instead of returning the value from :func:`fib`, it prints the result to the
+    ``stdout`` in a nicely formatted message.
+
+    Args:
+      args (List[str]): command line parameters as list of strings
+          (for example  ``["--verbose", "42"]``).
+    """
+    args = parse_args(args)
+    setup_logging(args.loglevel)
+    _logger.debug("Starting crazy calculations...")
+    print(f"The {args.n}-th Fibonacci number is {fib(args.n)}")
+    _logger.info("Script ends here")
+
+
+def run():
+    """Calls :func:`main` passing the CLI arguments extracted from :obj:`sys.argv`
+
+    This function can be used as entry point to create console scripts with setuptools.
+    """
+    main(sys.argv[1:])
+
+
+if __name__ == "__main__":
+    # ^  This is a guard statement that will prevent the following code from
+    #    being executed in the case someone imports this file instead of
+    #    executing it as a script.
+    #    https://docs.python.org/3/library/__main__.html
+
+    # After installing your project with pip, users can also run your Python
+    # modules as scripts via the ``-m`` flag, as defined in PEP 338::
+    #
+    #     python -m netoptim.skeleton 42
+    #
+    run()

netoptim-0.1.dist-info/METADATA

@@ -0,0 +1,60 @@
+Metadata-Version: 2.4
+Name: netoptim
+Version: 0.1
+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/
+Platform: any
+Classifier: Development Status :: 4 - Beta
+Classifier: Programming Language :: Python
+Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
+License-File: LICENSE.txt
+Requires-Dist: importlib-metadata; python_version < "3.9"
+Requires-Dist: networkx
+Provides-Extra: testing
+Requires-Dist: setuptools; extra == "testing"
+Requires-Dist: pytest; extra == "testing"
+Requires-Dist: pytest-cov; extra == "testing"
+Requires-Dist: networkx; extra == "testing"
+Requires-Dist: numpy; extra == "testing"
+Dynamic: license-file
+
+<!-- These are examples of badges you might want to add to your README:
+     please update the URLs accordingly
+
+[![Built Status](https://api.cirrus-ci.com/github/<USER>/netoptim.svg?branch=main)](https://cirrus-ci.com/github/<USER>/netoptim)
+[![ReadTheDocs](https://readthedocs.org/projects/netoptim/badge/?version=latest)](https://netoptim.readthedocs.io/en/stable/)
+[![Coveralls](https://img.shields.io/coveralls/github/<USER>/netoptim/main.svg)](https://coveralls.io/r/<USER>/netoptim)
+[![PyPI-Server](https://img.shields.io/pypi/v/netoptim.svg)](https://pypi.org/project/netoptim/)
+[![Conda-Forge](https://img.shields.io/conda/vn/conda-forge/netoptim.svg)](https://anaconda.org/conda-forge/netoptim)
+[![Monthly Downloads](https://pepy.tech/badge/netoptim/month)](https://pepy.tech/project/netoptim)
+[![Twitter](https://img.shields.io/twitter/url/http/shields.io.svg?style=social&label=Twitter)](https://twitter.com/netoptim)
+-->
+
+[![Project generated with PyScaffold](https://img.shields.io/badge/-PyScaffold-005CA0?logo=pyscaffold)](https://pyscaffold.org/)
+[![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
+
+> Network Optimization Python Code
+
+A longer description of your project goes here...
+
+## Dependencies
+
+- [luk036/ellalgo](https://github.com/luk036/ellalgo)
+- [luk036/mywheel](https://github.com/luk036/mywheel)
+- [luk036/digraphx](https://github.com/luk036/digraphx)
+- networkx
+- numpy
+
+<!-- pyscaffold-notes -->
+
+## 👉 Note
+
+This project has been set up using PyScaffold 4.5. For details and usage
+information on PyScaffold see https://pyscaffold.org/.

netoptim-0.1.dist-info/RECORD

@@ -0,0 +1,9 @@
+netoptim/__init__.py,sha256=ethe4DV1CwbXvO2DSjEzt5SL_7jt2fxQnF4RPgRgTDI,577
+netoptim/network_oracle.py,sha256=hJaiJ1Bc40OOq4RDCCCAPFno7WKrNkB11XfMqsS2510,2478
+netoptim/optscaling_oracle.py,sha256=T6HevOn5SA0xnFUWq7eKyMbHNttygr30-RObsVxHKu8,2400
+netoptim/skeleton.py,sha256=V1dgm3AdkUOtJOvW77z79V9ZSR0awv7HQ8LJqK-gSag,4219
+netoptim-0.1.dist-info/licenses/LICENSE.txt,sha256=MyvlyWiWdJ3ZpAOA4wziXlNa9Hbx8XnEL1Aztt9F7W8,1080
+netoptim-0.1.dist-info/METADATA,sha256=0hFlLDCEMY9kXRiWVe15Nozs4Pd6C5pfyXbVmVTYKiU,2609
+netoptim-0.1.dist-info/WHEEL,sha256=CmyFI0kx5cdEMTLiONQRbGQwjIoR1aIYB7eCAQ4KPJ0,91
+netoptim-0.1.dist-info/top_level.txt,sha256=z782jnxUdVszVSqfpR6FM3fVfxDmxIB5rN4LpqyI1HA,9
+netoptim-0.1.dist-info/RECORD,,

netoptim-0.1.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (78.1.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

netoptim-0.1.dist-info/licenses/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2023 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
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

netoptim-0.1.dist-info/top_level.txt

@@ -0,0 +1 @@
+netoptim