netgraph-core 0.1.0__tar.gz

netgraph_core-0.1.0/.coveragerc

@@ -0,0 +1,11 @@
+[run]
+branch = True
+data_file = build/coverage/.coverage
+source =
+    netgraph_core
+omit =
+    python/netgraph_core/_docs.py
+
+[report]
+show_missing = True
+skip_covered = True

netgraph_core-0.1.0/.gcovr.cfg

@@ -0,0 +1,20 @@
+[gcovr]
+root = .
+
+# Object dirs for Python extension and standalone C++ test builds
+object-directory = build
+object-directory = build/cpp-tests-cov
+
+# Only include our sources
+filter = include/netgraph
+filter = src
+
+# Exclude tests and third-party deps
+exclude = tests
+exclude = bindings/.*
+exclude-directories = .*/_deps/.*
+exclude-directories = .*/venv/.*
+exclude-directories = .*/site-packages/.*
+
+# Work around odd temp working dirs on macOS/pybind11
+gcov-ignore-errors = all

netgraph_core-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,77 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+  pull_request:
+    paths-ignore:
+      - "docs/**"
+      - "**.md"
+  workflow_dispatch:
+
+jobs:
+  build_wheels:
+    name: Wheel (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-13]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      # Build wheels using cibuildwheel
+      # ENV variables control the build (architectures, python versions)
+      - name: Build wheels
+        uses: pypa/cibuildwheel@v2.21.3
+        env:
+          # Build for Python 3.9+
+          CIBW_BUILD: "cp39-* cp310-* cp311-* cp312-* cp313-*"
+          # Skip PyPy and musllinux for now (unless desired)
+          CIBW_SKIP: "pp* *-musllinux_*"
+
+          # macOS: Build Universal2 wheels on Intel runner (macos-13)
+          CIBW_ARCHS_MACOS: "universal2"
+          CIBW_TEST_COMMAND: 'python -c "import netgraph_core; print(netgraph_core.__version__)"'
+          CIBW_BEFORE_ALL_LINUX: "yum install -y libatomic || (apt-get update && apt-get install -y libatomic1) || apk add libatomic"
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-wheels-${{ matrix.os }}-${{ strategy.job-index }}
+          path: ./wheelhouse/*.whl
+
+  build_sdist:
+    name: Build SDist
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Build SDist
+        run: pipx run build --sdist
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: cibw-sdist
+          path: dist/*.tar.gz
+
+  publish_pypi:
+    name: Publish to PyPI
+    needs: [build_wheels, build_sdist]
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write # Required for Trusted Publishing (OIDC)
+
+    # Only publish on tag pushes
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          pattern: cibw-*
+          path: dist
+          merge-multiple: true
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

netgraph_core-0.1.0/.github/workflows/tests.yml

@@ -0,0 +1,51 @@
+name: Tests
+
+on:
+  push:
+    branches: [ main, master ]
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  test:
+    name: Unit tests (${{ matrix.os }}, py${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-22.04, macos-13]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install deps
+        run: |
+          python -m pip install -U pip wheel
+          python -m pip install -e .[dev]
+      - name: Run CI checks (lint + C++/Python tests)
+        run: make check-ci
+
+  coverage:
+    name: Coverage (ubuntu, py3.11)
+    runs-on: ubuntu-22.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install deps
+        run: |
+          python -m pip install -U pip wheel
+          python -m pip install -e .[dev]
+      - name: Generate coverage (Python + C++)
+        run: make cov
+      - name: Upload coverage artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-reports
+          path: |
+            build/coverage/coverage-python.xml
+            build/coverage/coverage-cpp.xml
+            build/coverage/coverage-combined.html

netgraph_core-0.1.0/.gitignore

@@ -0,0 +1,222 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+.benchmarks/
+cover/
+
+# Consolidated coverage artifacts
+build/coverage/
+
+# CTest output if created in project root
+Testing/
+CTestTestfile.cmake
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer,
+#  you could uncomment the following to ignore the entire vscode folder
+.vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# OS-specific
+.DS_Store
+
+# IDEs
+.idea/
+*.code-workspace
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/

netgraph_core-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,24 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: check-merge-conflict
+      - id: check-yaml
+      - id: end-of-file-fixer
+      - id: trailing-whitespace
+      - id: mixed-line-ending
+      - id: debug-statements
+
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.11.13
+    hooks:
+      - id: ruff
+        args: ["--fix"]
+      - id: ruff-format
+
+  - repo: https://github.com/RobertCraigie/pyright-python
+    rev: v1.1.401
+    hooks:
+      - id: pyright
+        additional_dependencies: ["numpy>=1.22"]
+        # Pyright reads configuration from pyproject.toml

netgraph_core-0.1.0/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0] - 2025-11-23
+
+### Added
+
+- **Core Library**: Initial release of C++ implementation for graph algorithms and flow tracking.
+- **Graph Structures**:
+  - `StrictMultiDiGraph`: Immutable directed multigraph using CSR (Compressed Sparse Row) adjacency.
+  - `FlowGraph`: Manages flow state, per-flow edge allocations, and residual capacities.
+- **Algorithms**:
+  - Shortest paths (Dijkstra variant returning a DAG for ECMP; supports node/edge masking and residual-aware tie-breaking).
+  - K-Shortest paths (Yen's algorithm).
+  - Max-flow (Successive Shortest Path with ECMP/WCMP placement; supports capacity-aware (TE) and cost-only (IP) routing modes).
+  - Sensitivity analysis (identifies bottlenecks).
+- **Flow Policy**:
+  - **Modeling**: Unified configuration for IP routing (cost-based ECMP) and Traffic Engineering (capacity-aware TE).
+  - **Placement**: `Proportional` (WCMP) and `EqualBalanced` (ECMP) strategies.
+  - **Lifecycle**: Manages demand placement, static/dynamic path selection, and re-optimization.
+  - **Constraints**: Enforces limits on path cost, stretch factor, and flow counts.
+- **Python Bindings**:
+  - Python 3.9+ support via pybind11.
+  - NumPy integration using zero-copy views where applicable.
+  - Releases GIL during long-running graph algorithms.
+- **Testing**:
+  - Python and C++ test suites.

netgraph_core-0.1.0/CMakeLists.txt

@@ -0,0 +1,142 @@
+cmake_minimum_required(VERSION 3.23)
+project(netgraph_core LANGUAGES CXX)
+# Silence pybind11 FindPython compatibility warning by selecting the modern mode
+set(PYBIND11_FINDPYTHON NEW CACHE STRING "Use modern FindPython in pybind11")
+# Optional C++ tests
+option(NETGRAPH_CORE_BUILD_TESTS "Build C++ unit tests" OFF)
+if(NETGRAPH_CORE_BUILD_TESTS)
+  include(FetchContent)
+  FetchContent_Declare(
+    googletest
+    URL https://github.com/google/googletest/archive/refs/tags/v1.14.0.zip
+    DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+  )
+  FetchContent_MakeAvailable(googletest)
+  enable_testing()
+add_executable(netgraph_core_tests
+  tests/cpp/smoke_test.cpp
+  tests/cpp/flow_policy_tests.cpp
+  tests/cpp/strict_multidigraph_tests.cpp
+  tests/cpp/shortest_paths_tests.cpp
+  tests/cpp/flow_state_tests.cpp
+  tests/cpp/flow_graph_tests.cpp
+  tests/cpp/max_flow_tests.cpp
+  tests/cpp/k_shortest_paths_tests.cpp
+  tests/cpp/masking_tests.cpp
+)
+  target_link_libraries(netgraph_core_tests PRIVATE netgraph_core GTest::gtest_main)
+  target_include_directories(netgraph_core_tests PRIVATE tests/cpp)
+  if(NETGRAPH_CORE_COVERAGE AND (CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang"))
+    target_compile_options(netgraph_core_tests PRIVATE -O0 -g --coverage)
+    target_link_options(netgraph_core_tests PRIVATE --coverage)
+  endif()
+  include(GoogleTest)
+  gtest_discover_tests(netgraph_core_tests)
+endif()
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+set(CMAKE_CXX_EXTENSIONS OFF)
+set(CMAKE_POSITION_INDEPENDENT_CODE ON)
+
+# macOS: enforce consistent deployment target and architecture for wheels/builds
+if(APPLE)
+  # Allow environment to override, otherwise choose a sensible default
+  if(DEFINED ENV{MACOSX_DEPLOYMENT_TARGET})
+    set(CMAKE_OSX_DEPLOYMENT_TARGET "$ENV{MACOSX_DEPLOYMENT_TARGET}" CACHE STRING "" FORCE)
+  elseif(NOT DEFINED CMAKE_OSX_DEPLOYMENT_TARGET)
+    set(CMAKE_OSX_DEPLOYMENT_TARGET "15.0" CACHE STRING "" FORCE)
+  endif()
+  if(NOT DEFINED CMAKE_OSX_ARCHITECTURES)
+    # Default to arm64 on Apple Silicon hosts
+    if(CMAKE_SYSTEM_PROCESSOR MATCHES "arm64|aarch64")
+      set(CMAKE_OSX_ARCHITECTURES "arm64" CACHE STRING "" FORCE)
+    endif()
+  endif()
+endif()
+
+# Dependencies
+find_package(pybind11 3 CONFIG QUIET)
+if(NOT pybind11_FOUND)
+  message(STATUS "pybind11 not found via config; using FetchContent")
+  include(FetchContent)
+  FetchContent_Declare(
+    pybind11
+    GIT_REPOSITORY https://github.com/pybind/pybind11.git
+    GIT_TAG v3.0.0
+    DOWNLOAD_EXTRACT_TIMESTAMP TRUE
+  )
+  FetchContent_MakeAvailable(pybind11)
+endif()
+
+
+add_library(netgraph_core STATIC
+  src/strict_multidigraph.cpp
+  src/shortest_paths.cpp
+  src/k_shortest_paths.cpp
+  src/max_flow.cpp
+  src/flow_state.cpp
+  src/flow_graph.cpp
+  src/flow_policy.cpp
+  src/cpu_backend.cpp
+)
+target_include_directories(netgraph_core PUBLIC
+  $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
+  $<INSTALL_INTERFACE:include>
+)
+target_compile_definitions(netgraph_core PRIVATE _USE_MATH_DEFINES)
+## C++ standard is set globally above.
+target_compile_features(netgraph_core PUBLIC cxx_std_20)
+
+# Warnings
+if(MSVC)
+  target_compile_options(netgraph_core PRIVATE /W4 /permissive-)
+else()
+  target_compile_options(netgraph_core PRIVATE -Wall -Wextra -Wpedantic)
+endif()
+
+# Python extension
+pybind11_add_module(_netgraph_core bindings/python/module.cpp)
+target_link_libraries(_netgraph_core PRIVATE netgraph_core)
+target_compile_features(_netgraph_core PRIVATE cxx_std_20)
+if(APPLE)
+  # Prefer maximum runtime compatibility for libc++ on macOS
+  target_compile_definitions(netgraph_core PUBLIC _LIBCPP_DISABLE_AVAILABILITY=1 _LIBCPP_ABI_VERSION=1)
+  target_compile_definitions(_netgraph_core PRIVATE _LIBCPP_DISABLE_AVAILABILITY=1 _LIBCPP_ABI_VERSION=1)
+endif()
+
+# Optional coverage instrumentation for GCC/Clang
+option(NETGRAPH_CORE_COVERAGE "Enable C++ coverage instrumentation" OFF)
+if(NETGRAPH_CORE_COVERAGE)
+  message(STATUS "Enabling coverage instrumentation for C++ targets")
+  if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+    foreach(tgt netgraph_core _netgraph_core)
+      # Use no optimizations and include debug info for accurate line mapping
+      target_compile_options(${tgt} PRIVATE -O0 -g --coverage)
+      # Link coverage runtime
+      target_link_options(${tgt} PRIVATE --coverage)
+    endforeach()
+  else()
+    message(WARNING "NETGRAPH_CORE_COVERAGE is set but compiler '${CMAKE_CXX_COMPILER_ID}' is not supported")
+  endif()
+endif()
+
+# Optional sanitizers for debug testing
+option(NETGRAPH_CORE_SANITIZE "Enable Address/Undefined sanitizers" OFF)
+if(NETGRAPH_CORE_SANITIZE)
+  if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+    set(SAN_FLAGS "-fsanitize=address,undefined -fno-omit-frame-pointer")
+    foreach(tgt netgraph_core _netgraph_core)
+      target_compile_options(${tgt} PRIVATE ${SAN_FLAGS})
+      target_link_options(${tgt} PRIVATE ${SAN_FLAGS})
+    endforeach()
+  else()
+    message(WARNING "NETGRAPH_CORE_SANITIZE is set but compiler '${CMAKE_CXX_COMPILER_ID}' is not supported")
+  endif()
+endif()
+
+# Install
+install(TARGETS _netgraph_core
+  LIBRARY DESTINATION .
+  RUNTIME DESTINATION .
+)

netgraph_core-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,77 @@
+# Contributing to NetGraph-Core
+
+This document provides guidelines for setting up your development environment and submitting contributions.
+
+## Development Setup
+
+NetGraph-Core is a hybrid C++/Python project. You will need:
+
+- Python 3.9+
+- C++20 compatible compiler (GCC 10+, Clang 12+, MSVC 2019+)
+- CMake 3.23+
+- Ninja (recommended)
+
+### 1. Clone the repository
+
+```bash
+git clone https://github.com/networmix/NetGraph-Core.git
+cd NetGraph-Core
+```
+
+### 2. Create a virtual environment and install dependencies
+
+We use a `Makefile` to simplify development tasks.
+
+```bash
+make dev
+source venv/bin/activate
+```
+
+This will:
+
+- Create a virtual environment in `./venv`
+- Install all development dependencies
+- Install pre-commit hooks
+
+## Workflow
+
+### Running Tests
+
+Run all checks (linting + C++ tests + Python tests):
+
+```bash
+make check
+```
+
+Run specific test suites:
+
+```bash
+make cpp-test   # C++ tests (GoogleTest)
+make py-test    # Python tests (pytest)
+```
+
+### Code Style
+
+- **Python**: We use `ruff` for linting and formatting, and `pyright` for static type checking.
+- **C++**: We follow standard C++20 practices.
+
+Auto-fix Python formatting:
+
+```bash
+make format
+```
+
+## Release Process
+
+Releases are automated via GitHub Actions when a new tag is pushed.
+
+1. Bump version in `pyproject.toml` and `python/netgraph_core/_version.py`.
+2. Commit and push.
+3. Create and push a tag:
+
+   ```bash
+   git tag v0.1.0
+   git push origin v0.1.0
+   ```
+
+4. The CI pipeline will build wheels, sdist, and publish to PyPI.