finishing migration for 0.9.0

Author: networmix

docs/getting-started/tutorial.md

@@ -10,6 +10,8 @@ Let's start by defining a simple two-tier Clos (leaf-spine) fabric:
 from ngraph.scenario import Scenario
 
 scenario_yaml = """
+seed: 42  # Optional: ensures reproducible results for debugging/testing
+
 network:
   name: "Two-Tier Clos Fabric"
   groups:
@@ -76,9 +78,10 @@ blueprints:
           capacity: 40
           cost: 1
 
+seed: 42  # Optional: ensures reproducible results for debugging/testing
+
 network:
   name: "Three-Tier Clos Fabric"
-  seed: 42  # Optional: ensures reproducible results for debugging/testing
   groups:
     pod[1-2]:  # Creates pod1 and pod2
       use_blueprint: clos_pod

docs/reference/api-full.md

@@ -12,7 +12,7 @@ Quick links:
 - [CLI Reference](cli.md)
 - [DSL Reference](dsl.md)
 
-Generated from source code on: August 11, 2025 at 21:22 UTC
+Generated from source code on: August 12, 2025 at 16:01 UTC
 
 Modules auto-discovered: 67
 
@@ -114,6 +114,34 @@ Example (YAML-like):
 - `get(self, name: 'str') -> 'Optional[Component]'` - Retrieves a Component by its name from the library.
 - `merge(self, other: 'ComponentsLibrary', override: 'bool' = True) -> 'ComponentsLibrary'` - Merges another ComponentsLibrary into this one. By default (override=True),
 
+### resolve_hw_component(attrs: 'Dict[str, Any]', library: 'ComponentsLibrary') -> 'Tuple[Optional[Component], float]'
+
+Resolve hardware component and multiplier from entity attributes.
+
+Looks up ``attrs['hw_component']`` in the provided ``library``. If present,
+also reads an optional ``attrs['hw_count']`` multiplier. The multiplier
+defaults to 1 if not provided.
+
+Args:
+    attrs: Attribute mapping from a node or link.
+    library: Component library used for lookups.
+
+Returns:
+    A tuple ``(component, hw_count)`` where ``component`` is ``None`` if
+    ``hw_component`` is absent or unknown, and ``hw_count`` is a positive
+    float multiplier (defaults to 1.0).
+
+### totals_with_multiplier(comp: 'Component', hw_count: 'float') -> 'Tuple[float, float, float]'
+
+Return (capex, power_watts, capacity) totals multiplied by ``hw_count``.
+
+Args:
+    comp: Component definition (may include nested children and internal ``count``).
+    hw_count: External multiplier (e.g., number of modules used for a link or node).
+
+Returns:
+    Tuple of total capex, total power (typical), and total capacity as floats.
+
 ---
 
 ## ngraph.config
@@ -974,7 +1002,7 @@ Returns:
 
 Maximum-flow computation via iterative shortest-path augmentation.
 
-Implements a practical Edmonds–Karp-like procedure using SPF with capacity
+Implements a practical Edmonds-Karp-like procedure using SPF with capacity
 constraints and configurable flow-splitting across equal-cost parallel edges.
 Provides helpers for saturated-edge detection and simple sensitivity analysis.
 
@@ -2083,7 +2111,9 @@ or by risk-group children.
 
 ### FailureCondition
 
-Alias for the shared condition dataclass for backward compatibility.
+Alias to the shared condition dataclass.
+
+This maintains a consistent import path within the failure policy module.
 
 **Attributes:**
 
@@ -2641,10 +2671,15 @@ Attributes:
 
 ## ngraph.workflow.cost_power_efficiency
 
-Workflow step to compute cost/power efficiency metrics.
+Workflow step to compute cost/power efficiency metrics and optional HW inventory.
+
+Computes total capex and power for the selected network inventory (all or only
+active), and normalizes by a provided delivered-bandwidth figure (e.g., BAC at
+availability target).
 
-Computes total capex and power for the active network inventory, and normalizes
-by a provided delivered-bandwidth figure (e.g., BAC at availability target).
+Optionally collects node and/or link hardware entries to provide an inventory
+view of hardware usage. Each entry includes hardware capacity, allocated
+capacity, typical and maximum power, component name, and component count.
 
 This step does not compute BAC itself; it expects callers to pass the delivered
 bandwidth value explicitly or to point to a prior step result.
@@ -2657,16 +2692,27 @@ YAML Configuration Example:
         name: "cost_power_efficiency"   # Optional custom name
         delivered_bandwidth_gbps: 10000  # Optional explicit denominator (float)
         delivered_bandwidth_key: "delivered_bandwidth_gbps"  # Lookup key in results
-        include_disabled: true           # Whether to include disabled nodes/links in totals
+        include_disabled: true           # Whether to include disabled nodes/links
+        collect_node_hw_entries: true    # Optional: collect per-node HW entries
+        collect_link_hw_entries: false   # Optional: collect per-link HW entries
     ```
 
-Results stored in `scenario.results` under the step name:
+Results stored in `scenario.results`:
 
 - total_capex: Sum of component capex (float)
 - total_power_watts: Sum of component power (float)
 - delivered_bandwidth_gbps: Denominator used for normalization (float)
 - dollars_per_gbit: Normalized capex (float, inf if denominator <= 0)
 - watts_per_gbit: Normalized power (float, inf if denominator <= 0)
+- node_hw_entries: Optional list of node-level hardware dicts with keys:
+
+        node, hw_component, hw_count, hw_capacity, allocated_capacity,
+        power_watts, power_watts_max
+
+- link_hw_entries: Optional list of link-level hardware dicts with keys:
+
+        link_id, source, target, capacity, hw_component, hw_count, hw_capacity,
+        power_watts, power_watts_max
 
 ### CostPowerEfficiency
 
@@ -2681,6 +2727,10 @@ Attributes:
         not present, the key is treated as a global results key.
     include_disabled: If False, only enabled nodes/links are counted for totals.
         Default ``True`` aggregates regardless of disabled flags.
+    collect_node_hw_entries: If True, store per-node hardware entries with
+        component, count, capacity, allocated capacity, and power metrics.
+    collect_link_hw_entries: If True, store per-link hardware entries with
+        component, count, capacity, and power metrics.
 
 **Attributes:**
 
@@ -2689,6 +2739,8 @@ Attributes:
 - `delivered_bandwidth_gbps` (Optional[float])
 - `delivered_bandwidth_key` (str) = delivered_bandwidth_gbps
 - `include_disabled` (bool) = True
+- `collect_node_hw_entries` (bool) = False
+- `collect_link_hw_entries` (bool) = False
 
 **Methods:**
 

docs/reference/api.md

@@ -26,7 +26,7 @@ from ngraph.scenario import Scenario
 scenario = Scenario.from_yaml(yaml_content)
 
 # Or build programmatically
-from ngraph.network import Network
+from ngraph.model.network import Network
 scenario = Scenario(network=Network(), workflow=[])
 
 # Execute the scenario
@@ -50,7 +50,7 @@ print(scenario.results.get("NetworkStats", "node_count"))
 **When to use:** Core component for representing network structure. Used directly for programmatic topology creation or accessed via `scenario.network`.
 
 ```python
-from ngraph.network import Network, Node, Link
+from ngraph.model.network import Network, Node, Link
 
 # Create network topology
 network = Network()
@@ -126,7 +126,7 @@ Essential analysis capabilities for network evaluation.
 **When to use:** Fundamental analysis for understanding network capacity, bottlenecks, and traffic engineering scenarios.
 
 ```python
-from ngraph.core.algorithms.base import FlowPlacement
+from ngraph.algorithms.base import FlowPlacement
 
 # Basic maximum flow (returns dict)
 max_flow = network.max_flow(
@@ -177,7 +177,7 @@ print(f"Cost distribution: {summary.cost_distribution}")
 **When to use:** Simulate component failures, analyze degraded network states, or perform parallel analysis with different exclusions.
 
 ```python
-from ngraph.network_view import NetworkView
+from ngraph.model.view import NetworkView
 
 # Create view with failed components (for failure simulation)
 failed_view = NetworkView.from_excluded_sets(
@@ -212,9 +212,9 @@ Sophisticated analysis capabilities using Monte Carlo methods and parallel proce
 **When to use:** Capacity envelope analysis, demand placement studies, component sensitivity analysis, or custom Monte Carlo simulations.
 
 ```python
-from ngraph.failure_manager import FailureManager
-from ngraph.failure_policy import FailurePolicy, FailureRule
-from ngraph.results_artifacts import FailurePolicySet
+from ngraph.failure.manager.manager import FailureManager
+from ngraph.failure.policy import FailurePolicy, FailureRule
+from ngraph.results.artifacts import FailurePolicySet
 
 # Setup failure policies
 policy_set = FailurePolicySet()
@@ -297,7 +297,7 @@ Working with analysis outputs and implementing custom result storage.
 **When to use:** Working with stored analysis results, implementing custom workflow steps, or exporting data for external analysis.
 
 ```python
-from ngraph.results_artifacts import CapacityEnvelope, FailurePatternResult
+from ngraph.results.artifacts import CapacityEnvelope, FailurePatternResult
 
 # Access capacity envelopes from analysis results
 envelope_dict = scenario.results.get("CapacityEnvelopeAnalysis", "capacity_envelopes")
@@ -389,9 +389,9 @@ Advanced capabilities for custom analysis and low-level operations.
 **When to use:** Custom analysis requiring NetworkX integration, performance-critical algorithms, or when you need direct control over graph operations.
 
 ```python
-from ngraph.core.util import to_digraph, from_digraph
-from ngraph.core.algorithms.spf import spf
-from ngraph.core.algorithms.max_flow import calc_max_flow
+from ngraph.graph.convert import to_digraph, from_digraph
+from ngraph.algorithms.spf import spf
+from ngraph.algorithms.max_flow import calc_max_flow
 
 # Convert to NetworkX for custom algorithms
 nx_graph = to_digraph(scenario.network.to_strict_multidigraph())

docs/reference/dsl.md

@@ -61,6 +61,12 @@ network:
         hw_type: "router_model_B"
 ```
 
+Recognized keys for each node entry:
+
+- `disabled`: boolean (optional)
+- `attrs`: mapping of attributes (optional)
+- `risk_groups`: list of risk-group names (optional)
+
 **Individual Links:**
 
 ```yaml
@@ -76,6 +82,12 @@ network:
           media_type: "fiber"
 ```
 
+Recognized keys for each link entry:
+
+- `source`, `target`: node names (required)
+- `link_params`: mapping with only these keys allowed: `capacity`, `cost`, `disabled`, `risk_groups`, `attrs`
+- `link_count`: integer number of parallel links to create (optional; default 1)
+
 ### Group-Based Definitions
 
 **Node Groups:**
@@ -106,9 +118,12 @@ network:
       link_params:
         capacity: 10
         cost: 1
+        # Only the following keys are allowed inside link_params:
+        # capacity, cost, disabled, risk_groups, attrs
     - source: /switches
       target: /switches
       pattern: "one_to_one"     # Connect switches pairwise
+      link_count: 2              # Create 2 parallel links per adjacency (optional)
       link_params:
         capacity: 40
         cost: 1
@@ -148,11 +163,16 @@ network:
 Notes:
 
 - `path` uses the same semantics as before: regex on node name or `attr:<name>` directive grouping.
-- Supported operators: `==`, `!=`, `<`, `<=`, `>`, `>=`, `contains`, `not_contains`, `any_value`, `no_value`.
+- `match.conditions` uses the failure-policy language (same operators as below): `==`, `!=`, `<`, `<=`, `>`, `>=`, `contains`, `not_contains`, `any_value`, `no_value`.
 - Conditions evaluate over a flat view of node attributes combining top-level fields (`name`, `disabled`, `risk_groups`) and `node.attrs`.
+- `logic` in the `match` block accepts `"and"` or `"or"` (default `"or"`).
 - Selectors filter node candidates before the adjacency `pattern` is applied.
 - Cross-endpoint predicates (e.g., comparing a source attribute to a target attribute) are not supported.
 
+Path semantics inside blueprints:
+
+- Within a blueprint's `adjacency`, a leading `/` is treated as relative to the blueprint instantiation path, not a global root. For example, if a blueprint is used under group `pod1`, then `source: /leaf` resolves to `pod1/leaf`.
+
 Example with OR logic to match multiple roles:
 
 ```yaml
@@ -191,15 +211,14 @@ Create multiple similar groups using bracket notation:
 ```yaml
 network:
   groups:
-    dc[1-3]/rack[a-b]:     # Creates dc1/racka, dc1/rackb, dc2/racka, etc.
+    dc[1-3]/rack[a,b]:     # Creates dc1/racka, dc1/rackb, dc2/racka, etc.
       node_count: 4
       name_template: "srv-{node_num}"
 ```
 
 **Expansion Types:**
 
 - Numeric ranges: `[1-4]` → 1, 2, 3, 4
-- Character ranges: `[a-c]` → a, b, c
 - Explicit lists: `[red,blue,green]` → red, blue, green
 
 ### Variable Expansion in Adjacency
@@ -280,14 +299,20 @@ network:
   link_overrides:
     - source: "^pod1/leaf/.*$"
       target: "^pod1/spine/.*$"
-      capacity: 100                     # Override capacity
+      link_params:
+        capacity: 100                   # Override capacity
     - source: ".*/spine/.*"
       target: ".*/spine/.*"
       any_direction: true               # Bidirectional matching
       link_params:
         cost: 5
         attrs:
           link_type: "backbone"
+
+Notes:
+
+- For `link_overrides`, only the keys `source`, `target`, `link_params`, and optional `any_direction` are allowed at the top level. All parameter changes must be nested under `link_params`.
+- `any_direction` defaults to `true` if omitted.
 ```
 
 ## `components` - Hardware Library
@@ -444,29 +469,35 @@ Define failure policies for resilience testing:
 ```yaml
 failure_policy_set:
   single_link_failure:
-    rules:
-      - entity_scope: "link"
-        rule_type: "choice"
-        count: 1
+    modes:                       # Weighted modes; exactly one mode fires per iteration
+      - weight: 1.0
+        rules:
+          - entity_scope: "link"
+            rule_type: "choice"
+            count: 1
 
   random_failures:
-    fail_risk_groups: true
-    rules:
-      - entity_scope: "node"
-        rule_type: "random"
-        probability: 0.001
-      - entity_scope: "link"
-        rule_type: "random"
-        probability: 0.002
+    fail_risk_groups: true       # Optional expansion by shared-risk groups
+    modes:
+      - weight: 1.0
+        rules:
+          - entity_scope: "node"
+            rule_type: "random"
+            probability: 0.001
+          - entity_scope: "link"
+            rule_type: "random"
+            probability: 0.002
 
   maintenance_scenario:
-    rules:
-      - entity_scope: "node"
-        conditions:
-          - attr: "maintenance_mode"
-            operator: "=="
-            value: "scheduled"
-        rule_type: "all"
+    modes:
+      - weight: 1.0
+        rules:
+          - entity_scope: "node"
+            conditions:
+              - attr: "maintenance_mode"
+                operator: "=="
+                value: "scheduled"
+            rule_type: "all"
 ```
 
 **Rule Types:**
@@ -475,6 +506,12 @@ failure_policy_set:
 - `choice`: Select specific count of entities
 - `random`: Select entities with given probability
 
+Notes:
+
+- Policies are mode-based. Each mode has a non-negative `weight`. One mode is chosen per iteration with probability proportional to weights, then all rules in that mode are applied and their selections are unioned.
+- Each rule has `entity_scope` ("node" | "link" | "risk_group"), optional `logic` ("and" | "or"; defaults to "or"), optional `conditions`, and one of `rule_type` parameters (`count` for choice, `probability` for random). `weight_by` can be provided for weighted sampling in `choice` rules.
+- Condition language is the same as used in adjacency `match` selectors (see below) and supports: `==`, `!=`, `<`, `<=`, `>`, `>=`, `contains`, `not_contains`, `any_value`, `no_value`. Conditions evaluate on a flat attribute mapping that includes top-level fields and `attrs`.
+
 **Conditions:**
 
 - Target entities based on attributes

ngraph/algorithms/max_flow.py

@@ -1,6 +1,6 @@
 """Maximum-flow computation via iterative shortest-path augmentation.
 
-Implements a practical Edmonds–Karp-like procedure using SPF with capacity
+Implements a practical Edmonds-Karp-like procedure using SPF with capacity
 constraints and configurable flow-splitting across equal-cost parallel edges.
 Provides helpers for saturated-edge detection and simple sensitivity analysis.
 """