Add NetworkView class for filtered access to Network objects

Author: networmix

docs/reference/api-full.md

@@ -10,9 +10,9 @@ For a curated, example-driven API guide, see **[api.md](api.md)**.
 > - **[CLI Reference](cli.md)** - Command-line interface
 > - **[DSL Reference](dsl.md)** - YAML syntax guide
 
-**Generated from source code on:** July 05, 2025 at 16:54 UTC
+**Generated from source code on:** July 05, 2025 at 19:29 UTC
 
-**Modules auto-discovered:** 50
+**Modules auto-discovered:** 51
 
 ---
 
@@ -578,8 +578,6 @@ Attributes:
     links (Dict[str, Link]): Mapping from link ID -> Link object.
     risk_groups (Dict[str, RiskGroup]): Top-level risk groups by name.
     attrs (Dict[str, Any]): Optional metadata about the network.
-    _cached_graph (Optional[StrictMultiDiGraph]): Cached graph representation of the network.
-    _graph_cache_valid (bool): Indicates whether the cached graph is valid.
 
 **Attributes:**
 
@@ -640,7 +638,7 @@ the key in the Network's node dictionary.
 
 Attributes:
     name (str): Unique identifier for the node.
-    disabled (bool): Whether the node is disabled (excluded from calculations).
+    disabled (bool): Whether the node is disabled in the scenario configuration.
     risk_groups (Set[str]): Set of risk group names this node belongs to.
     attrs (Dict[str, Any]): Additional metadata (e.g., coordinates, region).
 
@@ -677,6 +675,73 @@ Returns:
 
 ---
 
+## ngraph.network_view
+
+NetworkView class for read-only filtered access to Network objects.
+
+### NetworkView
+
+Read-only overlay that hides selected nodes/links from a base Network.
+
+NetworkView provides filtered access to a Network where both scenario-disabled
+elements (Node.disabled, Link.disabled) and analysis-excluded elements are
+hidden from algorithms. This enables failure simulation and what-if analysis
+without mutating the base Network.
+
+Multiple NetworkView instances can safely operate on the same base Network
+concurrently, each with different exclusion sets.
+
+Example:
+    ```python
+    # Create view excluding specific nodes for failure analysis
+    view = NetworkView.from_failure_sets(
+        base_network,
+        failed_nodes=["node1", "node2"],
+        failed_links=["link1"]
+    )
+
+    # Run analysis on filtered topology
+    flows = view.max_flow("source.*", "sink.*")
+    ```
+
+Attributes:
+    _base: The underlying Network object.
+    _excluded_nodes: Frozen set of node names to exclude from analysis.
+    _excluded_links: Frozen set of link IDs to exclude from analysis.
+
+**Attributes:**
+
+- `_base` ('Network')
+- `_excluded_nodes` (frozenset[str]) = frozenset()
+- `_excluded_links` (frozenset[str]) = frozenset()
+
+**Methods:**
+
+- `from_failure_sets(base: "'Network'", failed_nodes: 'Iterable[str]' = (), failed_links: 'Iterable[str]' = ()) -> "'NetworkView'"`
+  - Create a NetworkView with specified failure exclusions.
+- `is_link_hidden(self, link_id: 'str') -> 'bool'`
+  - Check if a link is hidden in this view.
+- `is_node_hidden(self, name: 'str') -> 'bool'`
+  - Check if a node is hidden in this view.
+- `max_flow(self, source_path: 'str', sink_path: 'str', mode: 'str' = 'combine', shortest_path: 'bool' = False, flow_placement: "Optional['FlowPlacement']" = None) -> 'Dict[Tuple[str, str], float]'`
+  - Compute maximum flow between node groups in this view.
+- `max_flow_detailed(self, source_path: 'str', sink_path: 'str', mode: 'str' = 'combine', shortest_path: 'bool' = False, flow_placement: "Optional['FlowPlacement']" = None) -> "Dict[Tuple[str, str], Tuple[float, 'FlowSummary', 'StrictMultiDiGraph']]"`
+  - Compute maximum flow with complete analytics and graph.
+- `max_flow_with_graph(self, source_path: 'str', sink_path: 'str', mode: 'str' = 'combine', shortest_path: 'bool' = False, flow_placement: "Optional['FlowPlacement']" = None) -> "Dict[Tuple[str, str], Tuple[float, 'StrictMultiDiGraph']]"`
+  - Compute maximum flow and return flow-assigned graph.
+- `max_flow_with_summary(self, source_path: 'str', sink_path: 'str', mode: 'str' = 'combine', shortest_path: 'bool' = False, flow_placement: "Optional['FlowPlacement']" = None) -> "Dict[Tuple[str, str], Tuple[float, 'FlowSummary']]"`
+  - Compute maximum flow with detailed analytics summary.
+- `saturated_edges(self, source_path: 'str', sink_path: 'str', mode: 'str' = 'combine', tolerance: 'float' = 1e-10, shortest_path: 'bool' = False, flow_placement: "Optional['FlowPlacement']" = None) -> 'Dict[Tuple[str, str], List[Tuple[str, str, str]]]'`
+  - Identify saturated edges in max flow solutions.
+- `select_node_groups_by_path(self, path: 'str') -> "Dict[str, List['Node']]"`
+  - Select and group visible nodes matching a regex pattern.
+- `sensitivity_analysis(self, source_path: 'str', sink_path: 'str', mode: 'str' = 'combine', change_amount: 'float' = 1.0, shortest_path: 'bool' = False, flow_placement: "Optional['FlowPlacement']" = None) -> 'Dict[Tuple[str, str], Dict[Tuple[str, str, str], float]]'`
+  - Perform sensitivity analysis on capacity changes.
+- `to_strict_multidigraph(self, add_reverse: 'bool' = True) -> "'StrictMultiDiGraph'"`
+  - Create a StrictMultiDiGraph representation of this view.
+
+---
+
 ## ngraph.profiling
 
 Performance profiling instrumentation for NetGraph workflow execution.

docs/reference/api.md

@@ -46,6 +46,37 @@ network = Network()
 - `add_node(name, **attrs)` - Add network node
 - `add_link(source, target, **params)` - Add network link
 
+### NetworkView
+Provides a read-only filtered view of a Network for failure analysis without modifying the base network.
+
+```python
+from ngraph.network_view import NetworkView
+
+# Create view with specific nodes/links excluded (failure simulation)
+view = NetworkView.from_failure_sets(
+    network,
+    failed_nodes=["spine1", "spine2"],
+    failed_links=["link_id_123"]
+)
+
+# Run analysis on filtered topology
+max_flow = view.max_flow("source_path", "sink_path")
+```
+
+**Key Features:**
+
+- Read-only overlay that hides disabled and excluded elements
+- Supports concurrent analysis with different failure scenarios
+- Identical API to Network for flow analysis methods
+- Cached graph building for performance
+
+**Key Methods:**
+
+- `from_failure_sets(network, failed_nodes, failed_links)` - Create view with exclusions
+- `max_flow()`, `saturated_edges()`, `sensitivity_analysis()` - Same as Network
+- `is_node_hidden(name)` - Check if node is visible in this view
+- `is_link_hidden(link_id)` - Check if link is visible in this view
+
 ### NetworkExplorer
 Provides network visualization and exploration capabilities.
 
@@ -157,6 +188,8 @@ manager = FailureManager(
 )
 ```
 
+**Note:** For failure analysis without modifying the base network, consider using `NetworkView` instead of directly disabling nodes/links. This allows concurrent analysis of different failure scenarios.
+
 ### Risk Groups
 Model correlated component failures.
 

docs/reference/dsl.md

@@ -488,13 +488,17 @@ workflow:
 
 **Available Workflow Steps:**
 
-- **`BuildGraph`**: Builds the network graph from the scenario definition
+- **`BuildGraph`**: Builds a StrictMultiDiGraph from scenario.network
+- **`CapacityProbe`**: Probes capacity (max flow) between selected groups of nodes
+- **`NetworkStats`**: Computes basic capacity and degree statistics
 - **`EnableNodes`**: Enables previously disabled nodes matching a path pattern
-- **`DistributeExternalConnectivity`**: Creates external connectivity across attachment points
-- **`CapacityProbe`**: Probes maximum flow capacity between node groups
+- **`DistributeExternalConnectivity`**: Distributes external connectivity to attachment nodes
 - **`CapacityEnvelopeAnalysis`**: Performs Monte-Carlo capacity analysis across failure scenarios
-- **`NetworkStats`**: Computes basic node/link capacity and degree statistics
-- **`NotebookExport`**: Saves scenario results to a Jupyter notebook with configurable content and visualizations
+
+**Note:** NetGraph separates scenario-wide state (persistent configuration) from analysis-specific state (temporary failures). The `NetworkView` class provides a clean way to analyze networks under different failure conditions without modifying the base network, enabling concurrent analysis of multiple failure scenarios.
+
+- **NetworkTransform steps** (like `EnableNodes`, `DistributeExternalConnectivity`) permanently modify the Network's scenario state
+- **Analysis steps** (like `CapacityProbe`, `CapacityEnvelopeAnalysis`) should use NetworkView for temporary failure simulation to avoid corrupting the scenario
 
   ```yaml
   - step_type: NotebookExport
@@ -582,139 +586,3 @@ When using capturing groups `(...)` in regex patterns, NetGraph groups matching
 # All matching nodes are grouped under the original pattern string:
 #   "SEA/spine/switch-\\d+": [SEA/spine/switch-1, SEA/spine/switch-2, ...]
 ```
-
-### Usage in Different DSL Sections
-
-**Adjacency Matching:**
-
-In `adjacency` blocks (both in blueprints and top-level network):
-
-- `source` and `target` fields accept regex patterns
-- Blueprint paths can be relative (no leading `/`) or absolute (with leading `/`)
-- Relative paths are resolved relative to the blueprint instance's path
-
-```yaml
-adjacency:
-  - source: "^my_clos1/leaf/switch-\\d+$"
-    target: "^my_clos1/spine/switch-\\d+$"
-    pattern: mesh
-```
-
-**Node and Link Overrides:**
-
-Use `path` field for nodes or `source`/`target` for links:
-
-```yaml
-node_overrides:
-  - path: ^my_clos1/spine/switch-(1|3|5)$  # Specific switches
-    disabled: true
-    attrs:
-      maintenance_mode: "active"
-
-link_overrides:
-  - source: ^my_clos1/leaf/switch-1$
-    target: ^my_clos1/spine/switch-1$
-    disabled: true
-```
-
-**Workflow Steps:**
-
-Workflow steps like `EnableNodes`, `CapacityProbe`, etc., use path patterns:
-
-```yaml
-workflow:
-  - step_type: EnableNodes
-    path: "^my_clos2/leaf/switch-\\d+$"  # All leaf switches
-    count: 4
-
-  - step_type: CapacityProbe
-    source_path: "^(dc\\d+)/client"  # Capturing group creates per-DC groups
-    sink_path: "^(dc\\d+)/server"
-    mode: pairwise  # Test dc1 client -> dc1 server, dc2 client -> dc2 server
-
-  - step_type: CapacityEnvelopeAnalysis
-    source_path: "(.+)"    # Captures each node as its own group
-    sink_path: "(.+)"      # Creates N×N any-to-any analysis
-    mode: pairwise         # Required for per-node analysis
-```
-
-### Any-to-Any Analysis Pattern
-
-The pattern `(.+)` is a useful regex for network analysis in workflow steps like `CapacityProbe` and `CapacityEnvelopeAnalysis`:
-
-- **Individual Node Groups**: The capturing group `(.+)` matches each node name, creating separate groups for each node
-- **Automatic Combinations**: In pairwise mode, this creates N×N flow analysis for N nodes
-- **Full Coverage**: Tests connectivity between every pair of nodes in the network
-
-**Example Use Cases:**
-```yaml
-# Test capacity between every pair of nodes in the network
-- step_type: CapacityEnvelopeAnalysis
-  source_path: "(.+)"     # Every node as source
-  sink_path: "(.+)"       # Every node as sink
-  mode: pairwise          # Creates all node-to-node combinations
-  iterations: 100         # Monte-Carlo analysis across failures
-
-# Test capacity from all datacenter nodes to all others
-- step_type: CapacityProbe
-  source_path: "(datacenter.*)"  # Each datacenter node individually
-  sink_path: "(datacenter.*)"    # Each datacenter node individually
-  mode: pairwise                 # All datacenter-to-datacenter flows
-```
-
-### Best Practices
-
-1. **Use anchors for precision**: Always use `$` at the end if you want exact matches
-2. **Escape special characters in YAML**:
-   - For digit patterns: Use `\\d+` instead of `\d+` in quoted YAML strings
-   - For simple wildcards: `.*/spine/.*` works directly in YAML
-   - In Python code: Use raw strings `r"pattern"` or double escaping `"\\d+"`
-3. **Test patterns**: Use capturing groups strategically to create meaningful node groups
-4. **Relative vs absolute paths**: In blueprints, prefer relative paths for reusability
-5. **Group meaningfully**: Design capturing groups to create logical node groupings for workflow steps
-
-### Common Pitfalls
-
-1. **Missing end anchors**: `switch-1` matches `switch-10`, `switch-11`, etc.
-   - Fix: Use `switch-1$` for exact match
-
-2. **YAML escaping inconsistencies**:
-   - Simple patterns like `.*` work directly: `path: .*/spine/.*`
-   - Complex patterns need escaping: `path: "spine-\\d+$"`
-   - Python code always needs proper escaping: `"(SEA/leaf\\d)"`
-
-3. **Greedy matching**: `.*` can match more than intended
-   - Fix: Use specific patterns like `[^/]+` to match within path segments
-
-4. **Empty groups**: Patterns that don't match any nodes create empty results
-   - Fix: Test patterns against your actual node names
-
-### Regex Escaping Reference
-
-NetGraph processes regex patterns differently depending on context:
-
-**YAML Files (Scenarios):**
-```yaml
-# Simple wildcards - no escaping needed
-adjacency:
-  - source: .*/spine/.*    # Matches any spine nodes
-    target: .*/spine/.*
-
-# Complex patterns - use quotes and double backslashes
-node_overrides:
-  - path: "spine-\\d+$"    # Matches spine-1, spine-2, etc.
-    attrs:
-      hw_type: "high_performance"
-
-# Traffic matrix set with capturing groups
-traffic_matrix_set:
-  default:
-    - source_path: "my_clos1/b.*/t1"    # Works in YAML
-      sink_path: "my_clos2/b.*/t1"
-```
-
-**Python Code:**
-```python
-# Use raw strings (preferred)
-pattern = r"^S(\d+)$"
-```