Cache (#99)

* Update to v0.12.3

- Implemented SPF caching in demand placement to optimize shortest path computations, reducing redundant calculations for cacheable policies (ECMP, WCMP, TE_WCMP_UNLIM).

* Enhance TrafficDemand handling and context caching

Author: networmix

CHANGELOG.md

@@ -5,6 +5,17 @@ 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.12.3] - 2025-12-11
+
+### Changed
+
+- **SPF caching in demand placement**: `demand_placement_analysis()` caches SPF results by (source, policy_preset) for ECMP, WCMP, and TE_WCMP_UNLIM policies; TE policies recompute when capacity constraints require alternate paths
+- **MSD AnalysisContext caching**: `MaximumSupportedDemand` builds `AnalysisContext` once and reuses it across all binary search probes
+
+### Fixed
+
+- **TrafficDemand ID preservation**: Fixed context caching with `mode: combine` by ensuring `TrafficDemand.id` is preserved through serialization; pseudo node names now remain consistent across context build and analysis
+
 ## [0.12.2] - 2025-12-08
 
 ### Fixed

docs/reference/api-full.md

@@ -12,7 +12,7 @@ Quick links:
 - [CLI Reference](cli.md)
 - [DSL Reference](dsl.md)
 
-Generated from source code on: December 07, 2025 at 00:13 UTC
+Generated from source code on: December 11, 2025 at 23:43 UTC
 
 Modules auto-discovered: 44
 
@@ -460,12 +460,12 @@ Attributes:
     demand: Total demand volume.
     demand_placed: Portion of this demand placed so far.
     flow_policy_config: Policy preset (FlowPolicyPreset enum) used to build
-        a `FlowPolicy` if ``flow_policy`` is not provided.
+        a `FlowPolicy`` if ``flow_policy`` is not provided.
     flow_policy: Concrete policy instance. If set, it overrides
         ``flow_policy_config``.
     mode: Expansion mode, ``"combine"`` or ``"pairwise"``.
     attrs: Arbitrary user metadata.
-    id: Unique identifier assigned at initialization.
+    id: Unique identifier. Auto-generated if empty or not provided.
 
 **Attributes:**
 
@@ -1238,6 +1238,9 @@ placeable for a given matrix. Stores results under `data` as:
 - `base_demands`: serialized base demand specs
 - `probes`: bracket/bisect evaluations with feasibility
 
+Performance: AnalysisContext is built once at search start and reused across
+all binary search probes. Only demand volumes change per probe.
+
 ### MaximumSupportedDemand
 
 MaximumSupportedDemand(name: 'str' = '', seed: 'Optional[int]' = None, _seed_source: 'str' = '', matrix_name: 'str' = 'default', acceptance_rule: 'str' = 'hard', alpha_start: 'float' = 1.0, growth_factor: 'float' = 2.0, alpha_min: 'float' = 1e-06, alpha_max: 'float' = 1000000000.0, resolution: 'float' = 0.01, max_bracket_iters: 'int' = 32, max_bisect_iters: 'int' = 32, seeds_per_alpha: 'int' = 1, placement_rounds: 'int | str' = 'auto')
@@ -2345,6 +2348,10 @@ with FailureManager's caching and multiprocessing systems.
 Graph caching enables efficient repeated analysis with different exclusion
 sets by building the graph once and using O(|excluded|) masks for exclusions.
 
+SPF caching enables efficient demand placement by computing shortest paths once
+per unique source node rather than once per demand. For networks with many demands
+sharing the same sources, this can reduce SPF computations by an order of magnitude.
+
 ### build_demand_context(network: "'Network'", demands_config: 'list[dict[str, Any]]') -> 'AnalysisContext'
 
 Build an AnalysisContext for repeated demand placement analysis.
@@ -2383,8 +2390,15 @@ This function:
 
 1. Builds Core infrastructure (graph, algorithms, flow_graph) or uses cached
 2. Expands demands into concrete (src, dst, volume) tuples
-3. Places each demand using Core's FlowPolicy with exclusion masks
-4. Aggregates results into FlowIterationResult
+3. Places each demand using SPF caching for cacheable policies
+4. Falls back to FlowPolicy for complex multi-flow policies
+5. Aggregates results into FlowIterationResult
+
+SPF Caching Optimization:
+    For cacheable policies (ECMP, WCMP, TE_WCMP_UNLIM), SPF results are
+    cached by source node. This reduces SPF computations from O(demands)
+    to O(unique_sources), typically a 5-10x reduction for workloads with
+    many demands sharing the same sources.
 
 Args:
     network: Network instance.
@@ -2509,7 +2523,7 @@ Attributes:
     volume: Traffic volume to place.
     priority: Priority class (lower is higher priority).
     policy_preset: FlowPolicy configuration preset.
-    demand_id: Parent TrafficDemand ID (for tracking).
+    demand_id: Parent TrafficDemand ID for tracking.
 
 **Attributes:**
 

docs/reference/design.md

@@ -654,7 +654,7 @@ Managers handle scenario dynamics and prepare inputs for algorithmic steps.
 - Deterministic expansion: source/sink node lists sorted alphabetically; no randomization
 - Supports `combine` mode (aggregate via pseudo nodes) and `pairwise` mode (individual (src,dst) pairs with volume split)
 - Demands sorted by ascending priority before placement (lower value = higher priority)
-- Placement handled by Core's FlowPolicy with configurable presets (ECMP, WCMP, TE modes)
+- Placement uses SPF caching for simple policies (ECMP, WCMP, TE_WCMP_UNLIM), FlowPolicy for complex multi-flow policies
 - Non-mutating: operates on Core flow graphs with exclusions; Network remains unmodified
 
 **Failure Manager** (`ngraph.exec.failure.manager`): Applies a `FailurePolicy` to compute exclusion sets and runs analyses with those exclusions.
@@ -737,6 +737,16 @@ For Monte Carlo analysis with many failure iterations, graph construction is amo
 
 This optimization is critical for performance: graph construction involves Python processing, NumPy array creation, and C++ object initialization. Building the graph once eliminates this overhead from the per-iteration critical path, enabling the GIL-releasing C++ algorithms to execute with minimal Python overhead.
 
+**SPF Caching for Demand Placement:**
+
+For demand placement with cacheable policies (ECMP, WCMP, TE_WCMP_UNLIM), SPF results are cached by (source_node, policy_preset):
+
+- Initial SPF computed once per unique source; subsequent demands from the same source reuse the cached DAG
+- For TE policies, DAG is recomputed when capacity constraints require alternate paths
+- Complex multi-flow policies (TE_ECMP_16_LSP, TE_ECMP_UP_TO_256_LSP) use FlowPolicy directly
+
+This reduces SPF computations from O(demands) to O(unique_sources) for workloads where many demands share the same source nodes.
+
 **Monte Carlo Deduplication:**
 
 FailureManager collapses identical failure patterns into single executions. Runtime

ngraph/_version.py

@@ -2,4 +2,4 @@
 
 __all__ = ["__version__"]
 
-__version__ = "0.12.2"
+__version__ = "0.12.3"