digraphx 0.2__tar.gz → 0.3__tar.gz

{digraphx-0.2 → digraphx-0.3}/.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,8 +31,9 @@ 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
-          python setup.py develop
+          pip install -e .
           pytest

{digraphx-0.2 → digraphx-0.3}/.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

digraphx-0.3/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "cmake.sourceDirectory": "D:/github/py/digraphx/cpp_ai"
+}

digraphx-0.3/AGENTS.md

@@ -0,0 +1,127 @@
+# AGENTS.md
+
+This file guides agentic coding assistants working in the digraphx repository.
+
+## Build / Lint / Test Commands
+
+```bash
+# Run all tests with coverage
+pytest
+
+# Run single test file
+pytest tests/test_tiny_digraph.py
+
+# Run specific test
+pytest tests/test_tiny_digraph.py::test_tiny_digraph
+
+# Run tests matching pattern
+pytest -k "tiny_digraph"
+
+# Build package
+tox -e build
+
+# Run linting (pre-commit)
+pre-commit run --all-files
+
+# Run specific lint tools
+black src/digraphx tests
+isort src/digraphx tests
+flake8 src/digraphx tests
+```
+
+**Testing Notes:**
+- Tests located in `tests/` directory
+- Pytest configured in `setup.cfg` with coverage enabled
+- Fixtures defined in `tests/conftest.py`
+- Use `-k` flag to run tests matching name pattern
+
+## Code Style Guidelines
+
+### Formatting
+- **Line length**: 256 characters (flake8 config)
+- **Formatter**: Black (auto-enforced via pre-commit)
+- **Import sorting**: isort (auto-enforced via pre-commit)
+- **Linting**: flake8 with E203, W503 ignored (Black-compatible)
+
+### Type Hints
+- **Required**: All functions must use type hints
+- **Imports**: Use `from typing import List, Dict, Set, Tuple, Optional, Union, Generic, TypeVar, Callable, Mapping, MutableMapping, Iterator, Generator`
+- **Generic types**: Use TypeVar for generic classes (e.g., `Node = TypeVar("Node")`)
+- **External deps**: Use `# type: ignore` for missing stub files (e.g., `from mywheel.map_adapter import MapAdapter  # type: ignore`)
+
+### Naming Conventions
+- **Classes**: PascalCase (TinyDiGraph, NegCycleFinder, MinCycleRatioSolver)
+- **Functions/methods**: snake_case (init_nodes, find_cycle, howard)
+- **Constants**: UPPER_SNAKE_CASE (WEIGHT_0_1, SELF_LOOP_WEIGHT, NUM_NODES)
+- **Private methods**: underscore prefix (`_helper_function`)
+- **Type aliases**: PascalCase or short caps (Node, Edge, Domain, Cycle)
+
+### Documentation
+- **Docstrings**: Required for all public classes and methods
+- **Style**: Google-style with Args, Returns, Examples sections
+- **Examples**: Include doctest-style examples for key methods
+- **Module docstrings**: Describe purpose, inputs, outputs, algorithms used
+
+### Error Handling
+- Use type annotations for validation (e.g., `Mapping[Node, Edge]`)
+- Avoid empty catch blocks
+- Use pytest.raises for testing expected exceptions
+- Raise specific exceptions (NotImplementedError, ValueError, TypeError)
+
+### Import Style
+```python
+# Standard library imports first
+from fractions import Fraction
+from typing import List, Dict, TypeVar
+
+# Third-party imports second
+import networkx as nx
+
+# Local imports third (relative preferred within package)
+from .neg_cycle import NegCycleFinder
+from digraphx.tiny_digraph import TinyDiGraph
+```
+
+### Code Patterns
+- Use generics for reusable components: `class Solver(Generic[Node, Edge, Ratio]):`
+- Prefer composition over inheritance
+- Use generators for large sequences: `def find_cycle() -> Generator[Node, None, None]:`
+- Use dataclasses or named tuples for structured data
+- Mutable and immutable types: Separate Mapping (immutable) from MutableMapping (mutable)
+
+### Graph-Specific Conventions
+- Node identifiers: Generic hashable types (int, str, tuple)
+- Edge data: MutableMapping[str, Any] for attributes
+- Use NetworkX DiGraph patterns extended with custom storage
+- Separate graph structure from algorithms (adapter pattern)
+- Use fractional arithmetic for exact ratios (from fractions import Fraction)
+
+## Project Structure
+```
+src/digraphx/          # Main package
+├── __init__.py        # Version info, exports
+├── tiny_digraph.py    # Graph data structures
+├── neg_cycle.py       # Negative cycle algorithms
+├── parametric.py      # Parametric solver framework
+└── min_cycle_ratio.py # Minimum cycle ratio solver
+
+tests/                 # Test suite
+├── conftest.py        # Shared fixtures
+└── test_*.py          # Test files
+
+setup.cfg              # Package config, pytest options
+pyproject.toml         # Build config
+.pre-commit-config.yaml # Linting hooks
+```
+
+## Dependencies
+- **networkx**: Graph library base
+- **luk036/mywheel**: Custom utilities (MapAdapter)
+- Testing: pytest, pytest-cov
+- Development: black, isort, flake8, pre-commit
+
+## Key Algorithms
+- **Howard's algorithm**: Negative cycle detection
+- **Bellman-Ford**: Shortest paths with negative edges
+- **Parametric optimization**: Maximize/minimize ratio-based objectives
+- **Cycle ratio**: Find cycle with minimum/maximum cost/time ratio

{digraphx-0.2 → digraphx-0.3}/CONTRIBUTING.md

@@ -1,31 +1,3 @@
-```{todo} THIS IS SUPPOSED TO BE AN EXAMPLE. MODIFY IT ACCORDING TO YOUR NEEDS!
-
-   The document assumes you are using a source repository service that promotes a
-   contribution model similar to [GitHub's fork and pull request workflow].
-   While this is true for the majority of services (like GitHub, GitLab,
-   BitBucket), it might not be the case for private repositories (e.g., when
-   using Gerrit).
-
-   Also notice that the code examples might refer to GitHub URLs or the text
-   might use GitHub specific terminology (e.g., *Pull Request* instead of *Merge
-   Request*).
-
-   Please make sure to check the document having these assumptions in mind
-   and update things accordingly.
-```
-
-```{todo} Provide the correct links/replacements at the bottom of the document.
-
-```
-
-```{todo} You might want to have a look on [PyScaffold's contributor's guide],
-
-   especially if your project is open source. The text should be very similar to
-   this template, but there are a few extra contents that you might decide to
-   also include, like mentioning labels of your issue tracker or automated
-   releases.
-```
-
 # Contributing
 
 Welcome to `digraphx` contributor's guide.
@@ -69,29 +41,6 @@ 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.
-
-    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 `digraphx`'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
 compile them using [tox] :
 
@@ -108,13 +57,6 @@ python3 -m http.server --directory 'docs/_build/html'
 
 ## Code Contributions
 
-```{todo} Please include a reference or explanation about the internals of the project.
-
-   An architecture description, design principles or at least a summary of the
-   main concepts will make it easy for potential contributors to get started
-   quickly.
-```
-
 ### Submit an issue
 
 Before you work on any non-trivial code contribution it's best to first create
@@ -161,10 +103,6 @@ conda activate digraphx
 
    to be able to import the package under development in the Python REPL.
 
-   ```{todo} if you are not using pre-commit, please remove the following item:
-
-   ```
-
 5. Install [pre-commit]:
 
    ```
@@ -199,10 +137,6 @@ conda activate digraphx
 
    to record your changes in [git].
 
-   ```{todo} if you are not using pre-commit, please remove the following item:
-
-   ```
-
    Please make sure to see the validation messages from [pre-commit] and fix
    any eventual issues.
    This should automatically use [flake8]/[black] to check/fix the code style
@@ -244,14 +178,6 @@ conda activate digraphx
 2. Go to the web page of your fork and click "Create pull request"
    to send your changes for review.
 
-   ```{todo} if you are using GitHub, you can uncomment the following paragraph
-
-      Find more detailed information in [creating a PR]. You might also want to open
-      the PR as a draft first and mark it as ready for review after the feedbacks
-      from the continuous integration (CI) system or any required fixes.
-
-   ```
-
 ### Troubleshooting
 
 The following tips can be used when facing problems to build or test the
@@ -309,12 +235,6 @@ package:
 
 ### Releases
 
-```{todo} This section assumes you are using PyPI to publicly release your package.
-
-   If instead you are using a different/private package index, please update
-   the instructions accordingly.
-```
-
 If you are part of the group of maintainers and have correct user permissions
 on [PyPI], the following steps can be used to release a new version for
 `digraphx`:
@@ -366,9 +286,5 @@ on [PyPI], the following steps can be used to release a new version for
 [virtual environment]: https://realpython.com/python-virtual-environments-a-primer/
 [virtualenv]: https://virtualenv.pypa.io/en/stable/
 
-```{todo} Please review and change the following definitions:
-
-```
-
-[repository]: https://github.com/<USERNAME>/digraphx
-[issue tracker]: https://github.com/<USERNAME>/digraphx/issues
+[repository]: https://github.com/luk036/digraphx
+[issue tracker]: https://github.com/luk036/digraphx/issues

{digraphx-0.2 → digraphx-0.3}/GEMINI.md

@@ -16,7 +16,7 @@ The project is structured as a standard Python library using a `src` layout and
 ### Core Modules
 
 *   `min_cycle_ratio.py`: Implements the Minimum Cycle Ratio (MCR) solver.
-*   `parametric.py` & `min_parmetric_q.py`: Implements solvers for parametric network problems.
+*   `parametric.py` & `min_parametric_q.py`: Implements solvers for parametric network problems.
 *   `neg_cycle.py` & `neg_cycle_q.py`: Implements negative cycle detection using Howard's algorithm.
 *   `tiny_digraph.py`: Defines a memory-efficient `TinyDiGraph` data structure.
 

digraphx-0.3/IFLOW.md

@@ -0,0 +1,103 @@
+# digraphx 项目上下文
+
+## 项目概述
+
+`digraphx` 是一个用 Python 编写的有向图（Directed Graph）优化库，专注于网络优化问题。该项目基于 PyScaffold 4.5 创建，旨在提供一个轻量级且高效的有向图操作和分析工具。
+
+主要特性包括：
+- 负环检测（Negative Cycle Detection）
+- 最小环比率计算（Minimum Cycle Ratio Calculation）
+- 参数化优化算法
+- 高效的图数据结构实现（TinyDiGraph）
+
+## 依赖关系
+
+- [luk036/mywheel](https://github.com/luk036/mywheel) - 自定义数据结构库
+- networkx - 图论算法库
+- decorator
+- numpy
+
+## 核心模块
+
+### 1. TinyDiGraph (`tiny_digraph.py`)
+一个轻量级的有向图实现，优化了性能和内存效率。通过继承自 NetworkX 的 DiGraph 类，并使用自定义的 MapAdapter 作为底层存储结构。
+
+### 2. 负环检测 (`neg_cycle.py`)
+实现了基于 Howard 方法的负环检测算法，使用 Bellman-Ford 算法进行边的松弛操作。
+
+### 3. 最小环比率求解器 (`min_cycle_ratio.py`)
+提供最小环比率问题的求解，使用参数化方法结合最大参数化求解器。
+
+### 4. 其他模块
+- `min_parametric_q.py` - 参数化 Q 优化
+- `neg_cycle_q.py` - 负环 Q 检测
+- `parametric.py` - 参数化算法接口
+
+## 构建和测试
+
+该项目使用标准的 Python 包管理工具：
+
+安装依赖：
+```bash
+pip install -r requirements/default.txt
+pip install -r requirements/test.txt
+```
+
+运行测试：
+```bash
+pytest tests/
+```
+
+代码覆盖率测试：
+```bash
+pytest --cov digraphx --cov-report term-missing
+```
+
+## 开发规范
+
+- 代码使用 Python 3.9+ 编写
+- 遵循 PEP 8 代码风格
+- 使用 type hints 提供类型信息
+- 测试使用 pytest 框架
+
+## 项目结构
+
+```
+src/digraphx/ - 源代码目录
+├── __init__.py
+├── tiny_digraph.py - 轻量级有向图实现
+├── neg_cycle.py - 负环检测算法
+├── min_cycle_ratio.py - 最小环比率求解器
+├── parametric.py - 参数化算法接口
+├── neg_cycle_q.py - 负环 Q 检测
+├── min_parametric_q.py - 参数化 Q 优化
+└── py.typed - 类型提示标记文件
+
+tests/ - 测试目录
+├── test_cycle_ratio.py - 环比率相关测试
+├── test_neg_cycle.py - 负环检测测试
+├── test_tiny_digraph.py - TinyDiGraph 测试
+└── 其他测试文件
+```
+
+## 使用示例
+
+从 TinyDiGraph 的文档可以看出，基本用法如下：
+
+```python
+from digraphx.tiny_digraph import TinyDiGraph
+
+digraph = TinyDiGraph()
+digraph.init_nodes(1000)  # 初始化 1000 个节点
+digraph.add_edge(2, 1)    # 添加从节点 2 到节点 1 的边
+```
+
+## 项目状态
+
+根据 setup.cfg 中的分类器，该项目处于 Beta 开发阶段，使用 MIT 许可证。
+
+## 备注
+
+- 该项目专注于网络优化算法，特别是负环检测和最小环比率问题
+- 使用了自定义的高效数据结构以优化性能
+- 与 NetworkX 集成，利用其丰富的图算法功能

{digraphx-0.2 → digraphx-0.3}/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

digraphx-0.3/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.4
+Name: digraphx
+Version: 0.3
+Summary: Network Optimization Python Code
+Home-page: https://github.com/luk036/digraphx
+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"
+Dynamic: license-file
+
+[![Project generated with PyScaffold](https://img.shields.io/badge/-PyScaffold-005CA0?logo=pyscaffold)](https://pyscaffold.org/)
+[![Documentation Status](https://readthedocs.org/projects/digraphx/badge/?version=latest)](https://digraphx.readthedocs.io/en/latest/?badge=latest)
+[![codecov](https://codecov.io/gh/luk036/digraphx/branch/main/graph/badge.svg?token=U7PKg0lceH)](https://codecov.io/gh/luk036/digraphx)
+
+# 🔀 digraphx
+
+> Efficient directed graph algorithms for network optimization in Python
+
+digraphx is a Python library that provides high-performance implementations of directed graph algorithms, optimized for large-scale network optimization problems. It extends NetworkX with specialized data structures and algorithms for negative cycle detection, cycle ratio optimization, and parametric network analysis.
+
+Note that digraphx does not directly handle multi-edges (same as networkx)
+
+## Features
+
+- **High-performance graph storage**: `TinyDiGraph` with memory-efficient `MapAdapter` backend
+- **Negative cycle detection**: Howard's algorithm for finding negative cycles in weighted directed graphs
+- **Minimum/Maximum Cycle Ratio**: Efficient algorithms for finding cycles with optimal cost/time ratios
+- **Parametric network optimization**: Generic framework for ratio-based optimization problems
+- **Type-safe**: Full type hints throughout codebase
+- **Well-tested**: Comprehensive test coverage with pytest
+
+## When to Use digraphx vs NetworkX
+
+**Use digraphx when:**
+- Working with very large graphs (thousands to millions of nodes)
+- Need memory-efficient storage for graphs with known node counts
+- Optimizing cycles based on cost/time ratios
+- Finding negative cycles in weighted graphs
+- Implementing parametric optimization algorithms
+
+**Use standard NetworkX when:**
+- Need a general-purpose graph library
+- Working with small to medium-sized graphs
+- Need extensive graph algorithms not in digraphx
+- Dynamic graph operations (frequent node/edge additions/removals)
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install digraphx
+```
+
+### From Source
+
+```bash
+git clone https://github.com/luk036/digraphx.git
+cd digraphx
+pip install -e .
+```
+
+## Dependencies
+
+- [NetworkX](https://networkx.org/) - Graph library foundation
+- [luk036/mywheel](https://github.com/luk036/mywheel) - Custom utilities (MapAdapter for efficient storage)
+
+## Quick Start
+
+### Detect Negative Cycles
+
+```python
+from digraphx import NegCycleFinder
+
+# Create a directed graph with a negative cycle
+digraph = {
+    'a': {'b': 7, 'c': 5},
+    'b': {'a': 0, 'c': 3},
+    'c': {'a': 2, 'b': 1}
+}
+
+# Initialize distances
+dist = {node: 0 for node in digraph}
+
+# Find negative cycles using Howard's algorithm
+finder = NegCycleFinder(digraph)
+for cycle in finder.howard(dist, lambda edge: edge):
+    print(f"Found negative cycle: {cycle}")
+```
+
+### Minimum Cycle Ratio
+
+```python
+from digraphx import MinCycleRatioSolver
+from digraphx import DiGraphAdapter
+from fractions import Fraction
+
+# Create a graph with cost and time attributes
+graph = DiGraphAdapter()
+graph.add_edge('a', 'b', cost=5, time=1)
+graph.add_edge('b', 'c', cost=3, time=1)
+graph.add_edge('c', 'a', cost=-2, time=1)
+
+# Solve for minimum cycle ratio
+solver = MinCycleRatioSolver(graph)
+dist = {node: Fraction(0) for node in graph}
+ratio, cycle = solver.run(dist, Fraction(10))
+print(f"Minimum cycle ratio: {ratio}")
+```
+
+### High-Performance Graph with TinyDiGraph
+
+```python
+from digraphx import TinyDiGraph
+
+# Create a graph optimized for 1000 nodes
+graph = TinyDiGraph()
+graph.init_nodes(1000)
+
+# Add edges efficiently
+for i in range(1000):
+    for j in range(i+1, min(i+10, 1000)):
+        graph.add_edge(i, j, weight=i+j)
+
+# Access graph properties
+print(f"Nodes: {graph.number_of_nodes()}")
+print(f"Edges: {graph.number_of_edges()}")
+```
+
+## Algorithms Implemented
+
+### Core Algorithms
+
+- **Howard's Algorithm**: Efficient negative cycle detection using policy iteration
+- **Bellman-Ford**: Shortest paths with negative edge weights
+- **Parametric Optimization**: Generic framework for ratio-based objectives
+- **Cycle Ratio**: Find cycles with minimum/maximum cost/time ratios
+
+### Data Structures
+
+- **TinyDiGraph**: Memory-efficient directed graph for fixed-size node sets
+- **DiGraphAdapter**: NetworkX compatibility layer with custom storage
+- **MapAdapter**: List-based dictionary for O(1) node/edge access
+
+## Documentation
+
+Full API documentation is available at [https://digraphx.readthedocs.io/](https://digraphx.readthedocs.io/)
+
+## Testing
+
+Run's test suite:
+
+```bash
+# Run all tests
+pytest
+
+# Run specific test file
+pytest tests/test_tiny_digraph.py
+
+# Run with coverage
+pytest --cov=digraphx --cov-report=html
+```
+
+## Development
+
+```bash
+# Install development dependencies
+pip install -e ".[testing]"
+
+# Run linting
+pre-commit run --all-files
+
+# Format code
+black src/digraphx tests
+isort src/digraphx tests
+
+# Build package
+tox -e build
+```
+
+## Contributing
+
+Contributions are welcome! Please ensure:
+- All tests pass
+- Code follows the project's style guidelines (see AGENTS.md)
+- New features include tests and documentation
+- Pre-commit hooks pass before pushing
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE.txt file for details.
+
+## Acknowledgments
+
+Built on top of [NetworkX](https://networkx.org/)
+Uses [PyScaffold](https://pyscaffold.org/) for project structure
+
+## Contact
+
+- Author: Wai-Shing Luk
+- Email: luk036@gmail.com
+- GitHub: [@luk036](https://github.com/luk036)
+
+## Citation
+
+If you use digraphx in your research, please cite:
+
+```
+@software{digraphx,
+  title = {digraphx: Directed Graph X in Python},
+  author = {Luk, Wai-Shing},
+  url = {https://github.com/luk036/digraphx},
+  year = {2026}
+}
+```
+
+<!-- pyscaffold-notes -->