Release v0.3.1: Introduce runtime profiling infrastructure

Author: networmix

.gitignore

@@ -220,3 +220,4 @@ cython_debug/
 marimo/_static/
 marimo/_lsp/
 __marimo__/
+.pgo-profile/

CHANGELOG.md

@@ -5,6 +5,20 @@ 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.3.1] - 2025-12-08
+
+### Added
+
+- **Profiling**: Runtime profiling infrastructure for C++ hot paths (`shortest_paths_core`, `place_demand`, `place_on_dag`).
+  - Enable via `NGRAPH_CORE_PROFILE=1` environment variable.
+  - Python API: `profiling_enabled()`, `profiling_dump()`, `profiling_reset()`.
+  - Minimal overhead when disabled (single static bool check per instrumented scope).
+  - ~2% overhead when enabled.
+
+### Changed
+
+- **Build**: Default optimizations: LTO, loop unrolling, `-fno-math-errno`. Add `make install-native` for CPU-specific builds.
+
 ## [0.3.0] - 2025-12-06
 
 ### Changed

CMakeLists.txt

@@ -105,33 +105,125 @@ if(APPLE)
   target_compile_definitions(_netgraph_core PRIVATE _LIBCPP_DISABLE_AVAILABILITY=1 _LIBCPP_ABI_VERSION=1)
 endif()
 
-# Optional coverage instrumentation for GCC/Clang
+# =============================================================================
+# Performance optimizations (disabled when coverage/sanitizers are enabled)
+# =============================================================================
+
 option(NETGRAPH_CORE_COVERAGE "Enable C++ coverage instrumentation" OFF)
+option(NETGRAPH_CORE_SANITIZE "Enable Address/Undefined sanitizers" OFF)
+option(NETGRAPH_CORE_NATIVE "Optimize for current CPU (not portable)" OFF)
+option(NETGRAPH_CORE_FAST_MATH "Enable fast math (may affect precision)" OFF)
+option(NETGRAPH_CORE_PGO_GENERATE "Instrument for PGO profile collection" OFF)
+option(NETGRAPH_CORE_PGO_USE "Use PGO profile data (set NETGRAPH_CORE_PGO_DIR)" OFF)
+set(NETGRAPH_CORE_PGO_DIR "${CMAKE_BINARY_DIR}/pgo" CACHE PATH "Directory for PGO profile data")
+
+# Only apply optimizations when not in debug/instrumentation mode
+if(NOT NETGRAPH_CORE_COVERAGE AND NOT NETGRAPH_CORE_SANITIZE)
+  # LTO (Link Time Optimization) - enables cross-module inlining
+  include(CheckIPOSupported)
+  check_ipo_supported(RESULT ipo_supported OUTPUT ipo_error)
+  if(ipo_supported)
+    message(STATUS "Enabling LTO (Link Time Optimization)")
+    set_target_properties(netgraph_core PROPERTIES INTERPROCEDURAL_OPTIMIZATION TRUE)
+    set_target_properties(_netgraph_core PROPERTIES INTERPROCEDURAL_OPTIMIZATION TRUE)
+  else()
+    message(STATUS "LTO not supported: ${ipo_error}")
+  endif()
+
+  if(CMAKE_CXX_COMPILER_ID MATCHES "GNU|Clang")
+    # GCC-only: allow aggressive inlining by promising symbols won't be interposed
+    if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+      target_compile_options(netgraph_core PRIVATE -fno-semantic-interposition)
+      target_compile_options(_netgraph_core PRIVATE -fno-semantic-interposition)
+    endif()
+
+    # Safe floating-point optimizations (we don't use errno, FP exceptions, or change rounding mode)
+    target_compile_options(netgraph_core PRIVATE -fno-math-errno -fno-trapping-math)
+    target_compile_options(_netgraph_core PRIVATE -fno-math-errno -fno-trapping-math)
+
+    # Aggressive loop optimizations
+    target_compile_options(netgraph_core PRIVATE -funroll-loops)
+    target_compile_options(_netgraph_core PRIVATE -funroll-loops)
+
+    # Native CPU instructions (AVX2, etc.) - only for local builds
+    if(NETGRAPH_CORE_NATIVE)
+      message(STATUS "Enabling native CPU optimizations (-march=native)")
+      target_compile_options(netgraph_core PRIVATE -march=native)
+      target_compile_options(_netgraph_core PRIVATE -march=native)
+    endif()
+
+    # Fast math - trades IEEE compliance for speed
+    if(NETGRAPH_CORE_FAST_MATH)
+      message(STATUS "Enabling fast math optimizations")
+      target_compile_options(netgraph_core PRIVATE -ffast-math)
+      target_compile_options(_netgraph_core PRIVATE -ffast-math)
+    endif()
+
+    # PGO (Profile-Guided Optimization) - uses runtime profile to guide inlining decisions
+    # GCC: -fprofile-generate/-fprofile-use, Clang: -fprofile-instr-*
+    if(NETGRAPH_CORE_PGO_GENERATE)
+      message(STATUS "PGO: Instrumenting for profile generation -> ${NETGRAPH_CORE_PGO_DIR}")
+      file(MAKE_DIRECTORY ${NETGRAPH_CORE_PGO_DIR})
+      if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+        target_compile_options(netgraph_core PRIVATE -fprofile-generate=${NETGRAPH_CORE_PGO_DIR})
+        target_compile_options(_netgraph_core PRIVATE -fprofile-generate=${NETGRAPH_CORE_PGO_DIR})
+        target_link_options(netgraph_core PRIVATE -fprofile-generate=${NETGRAPH_CORE_PGO_DIR})
+        target_link_options(_netgraph_core PRIVATE -fprofile-generate=${NETGRAPH_CORE_PGO_DIR})
+      else()
+        # Clang/AppleClang: use LLVM instrumentation PGO
+        target_compile_options(netgraph_core PRIVATE -fprofile-instr-generate=${NETGRAPH_CORE_PGO_DIR}/default.profraw)
+        target_compile_options(_netgraph_core PRIVATE -fprofile-instr-generate=${NETGRAPH_CORE_PGO_DIR}/default.profraw)
+        target_link_options(netgraph_core PRIVATE -fprofile-instr-generate=${NETGRAPH_CORE_PGO_DIR}/default.profraw)
+        target_link_options(_netgraph_core PRIVATE -fprofile-instr-generate=${NETGRAPH_CORE_PGO_DIR}/default.profraw)
+      endif()
+    elseif(NETGRAPH_CORE_PGO_USE)
+      message(STATUS "PGO: Using profile data from ${NETGRAPH_CORE_PGO_DIR}")
+      if(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
+        target_compile_options(netgraph_core PRIVATE -fprofile-use=${NETGRAPH_CORE_PGO_DIR} -fprofile-correction)
+        target_compile_options(_netgraph_core PRIVATE -fprofile-use=${NETGRAPH_CORE_PGO_DIR} -fprofile-correction)
+      else()
+        # Clang/AppleClang: use merged .profdata file
+        target_compile_options(netgraph_core PRIVATE -fprofile-instr-use=${NETGRAPH_CORE_PGO_DIR}/default.profdata)
+        target_compile_options(_netgraph_core PRIVATE -fprofile-instr-use=${NETGRAPH_CORE_PGO_DIR}/default.profdata)
+      endif()
+    endif()
+  elseif(MSVC)
+    # /O2: full optimization, /GL: whole program optimization (MSVC's LTO)
+    target_compile_options(netgraph_core PRIVATE /O2 /GL)
+    target_compile_options(_netgraph_core PRIVATE /O2 /GL)
+    if(NETGRAPH_CORE_FAST_MATH)
+      target_compile_options(netgraph_core PRIVATE /fp:fast)
+      target_compile_options(_netgraph_core PRIVATE /fp:fast)
+    endif()
+  endif()
+endif()
+
+# =============================================================================
+# Debug/instrumentation options (mutually exclusive with optimizations above)
+# =============================================================================
+
 if(NETGRAPH_CORE_COVERAGE)
-  message(STATUS "Enabling coverage instrumentation for C++ targets")
+  message(STATUS "Enabling coverage instrumentation (disables optimizations)")
   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")
+    message(WARNING "NETGRAPH_CORE_COVERAGE requires GCC or Clang")
   endif()
 endif()
 
-# Optional sanitizers for debug testing
-option(NETGRAPH_CORE_SANITIZE "Enable Address/Undefined sanitizers" OFF)
 if(NETGRAPH_CORE_SANITIZE)
+  message(STATUS "Enabling sanitizers (disables optimizations)")
   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")
+    message(WARNING "NETGRAPH_CORE_SANITIZE requires GCC or Clang")
   endif()
 endif()
 

Makefile

@@ -1,6 +1,6 @@
 # NetGraph-Core Development Makefile
 
-.PHONY: help venv clean-venv dev install check check-ci lint format test qt build clean check-dist publish-test publish info hooks check-python cpp-test cov sanitize-test rebuild
+.PHONY: help venv clean-venv dev install install-native install-pgo check check-ci lint format test qt build clean check-dist publish-test publish info hooks check-python cpp-test cov sanitize-test rebuild
 
 .DEFAULT_GOAL := help
 
@@ -41,7 +41,9 @@ help:
 	@echo "Setup & Installation:"
 	@echo "  make venv          - Create a local virtualenv (./venv)"
 	@echo "  make dev           - Full development environment (package + dev deps + hooks)"
-	@echo "  make install       - Install package for usage (no dev dependencies)"
+	@echo "  make install       - Install package (default optimizations: LTO, loop unrolling)"
+	@echo "  make install-native - Install with CPU-specific optimizations (faster, not portable)"
+	@echo "  make install-pgo   - Profile-guided optimization (two-phase build, experimental)"
 	@echo "  make clean-venv    - Remove virtual environment"
 	@echo "  make rebuild       - Clean and rebuild (respects CMAKE_ARGS)"
 	@echo ""
@@ -115,9 +117,39 @@ clean-venv:
 	@rm -rf venv/
 
 install:
-	@echo "📦 Installing package (editable)"
+	@echo "📦 Installing package (editable, default optimizations)"
 	@$(DEV_ENV) $(PIP) install -e .
 
+install-native:
+	@echo "📦 Installing with native CPU optimizations (-march=native)"
+	@echo "   Note: Binary will only work on this CPU architecture"
+	@$(ENV_MACOS) $(ENV_CC) $(ENV_CXX) CMAKE_ARGS="$(strip $(CMAKE_ARGS) -DNETGRAPH_CORE_NATIVE=ON)" $(PIP) install -e .
+
+# PGO profile stored outside build/ so it survives rebuild
+PGO_DIR := $(PWD)/.pgo-profile
+
+install-pgo:
+	@echo "📦 PGO Build Phase 1/3: Instrumenting..."
+	@rm -rf build/ $(PGO_DIR)
+	@mkdir -p $(PGO_DIR)
+	@$(ENV_MACOS) $(ENV_CC) $(ENV_CXX) CMAKE_ARGS="$(strip $(CMAKE_ARGS) -DNETGRAPH_CORE_PGO_GENERATE=ON -DNETGRAPH_CORE_PGO_DIR=$(PGO_DIR) -DNETGRAPH_CORE_NATIVE=ON)" $(PIP) install -e .
+	@echo "📦 PGO Build Phase 2/3: Collecting profile (running benchmark)..."
+	@$(PYTHON) dev/benchmark_profiling_overhead.py --mesh-size 25 --spf-iters 1000 --flow-iters 200 >/dev/null 2>&1
+	@# Clang: merge raw profiles into .profdata (profile may be in cwd or PGO_DIR)
+	@if ls $(PGO_DIR)/*.profraw >/dev/null 2>&1; then \
+		echo "   Merging Clang profile data..."; \
+		xcrun llvm-profdata merge -output=$(PGO_DIR)/default.profdata $(PGO_DIR)/*.profraw 2>/dev/null || \
+		llvm-profdata merge -output=$(PGO_DIR)/default.profdata $(PGO_DIR)/*.profraw; \
+	elif ls *.profraw >/dev/null 2>&1; then \
+		mv *.profraw $(PGO_DIR)/; \
+		xcrun llvm-profdata merge -output=$(PGO_DIR)/default.profdata $(PGO_DIR)/*.profraw 2>/dev/null || \
+		llvm-profdata merge -output=$(PGO_DIR)/default.profdata $(PGO_DIR)/*.profraw; \
+	fi
+	@echo "📦 PGO Build Phase 3/3: Rebuilding with profile data..."
+	@rm -rf build/
+	@$(ENV_MACOS) $(ENV_CC) $(ENV_CXX) CMAKE_ARGS="$(strip $(CMAKE_ARGS) -DNETGRAPH_CORE_PGO_USE=ON -DNETGRAPH_CORE_PGO_DIR=$(PGO_DIR) -DNETGRAPH_CORE_NATIVE=ON)" $(PIP) install -e .
+	@echo "✅ PGO build complete"
+
 check:
 	@PYTHON=$(PYTHON) bash dev/run-checks.sh
 

README.md

@@ -64,6 +64,14 @@ Or from source:
 pip install -e .
 ```
 
+### Build Optimizations
+
+Default builds include LTO and loop unrolling. For local development:
+
+```bash
+make install-native   # CPU-specific optimizations (not portable)
+```
+
 ## Repository Structure
 
 ```
@@ -81,9 +89,9 @@ tests/py/               # Python tests (pytest)
 make dev        # Setup: venv, dependencies, pre-commit hooks
 make check      # Run all tests and linting (auto-fix formatting)
 make check-ci   # Strict checks without auto-fix (for CI)
+make test       # Python tests with coverage
 make cpp-test   # C++ tests only
-make py-test    # Python tests only
-make cov        # Coverage report (C++ + Python)
+make cov        # Combined coverage report (C++ + Python)
 ```
 
 ## Requirements

bindings/python/module.cpp

@@ -23,6 +23,7 @@
 #include "netgraph/core/backend.hpp"
 #include "netgraph/core/algorithms.hpp"
 #include "netgraph/core/options.hpp"
+#include "netgraph/core/profiling.hpp"
 
 namespace py = pybind11;
 using namespace netgraph::core;
@@ -604,4 +605,12 @@ PYBIND11_MODULE(_netgraph_core, m) {
            py::arg("flow_graph"), py::arg("src"), py::arg("dst"), py::arg("flowClass"), py::arg("target"))
       .def("remove_demand", [](FlowPolicy& p, FlowGraph& fg){ py::gil_scoped_release rel; p.remove_demand(fg); py::gil_scoped_acquire acq; })
       .def_property_readonly("flows", [](const FlowPolicy& p){ py::dict out; for (auto const& kv : p.flows()) { const auto& idx = kv.first; const auto& f = kv.second; out[py::make_tuple(idx.src, idx.dst, idx.flowClass, idx.flowId)] = py::make_tuple(f.src, f.dst, f.cost, f.placed_flow); } return out; });
+
+  // Profiling functions (enabled via NGRAPH_CORE_PROFILE=1 environment variable)
+  m.def("profiling_enabled", &profiling_enabled,
+        "Return True if profiling is enabled (NGRAPH_CORE_PROFILE=1).");
+  m.def("profiling_dump", []{ ProfilingStats::instance().dump(); },
+        "Print profiling statistics to stderr.");
+  m.def("profiling_reset", []{ ProfilingStats::instance().reset(); },
+        "Clear all profiling statistics.");
 }