Update to v0.12.1

- Added `ngraph.lib.nx` module for NetworkX integration, including `from_networkx()` and `to_networkx()` functions for graph conversion.
- Introduced `NodeMap` and `EdgeMap` classes for bidirectional lookups of node and edge IDs post-conversion.
- Updated documentation to reflect new features and usage examples.

Author: networmix

CHANGELOG.md

@@ -5,6 +5,13 @@ 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.1] - 2025-12-07
+
+### Added
+
+- **NetworkX interop**: New `ngraph.lib.nx` module with `from_networkx()` and `to_networkx()` for converting between NetworkX graphs and netgraph_core.StrictMultiDiGraph
+- **Mapping classes**: `NodeMap` and `EdgeMap` for bidirectional node/edge ID lookups after conversion
+
 ## [0.12.0] - 2025-12-06
 
 ### Changed

docs/reference/api-full.md

@@ -12,9 +12,15 @@ Quick links:
 - [CLI Reference](cli.md)
 - [DSL Reference](dsl.md)
 
-Generated from source code on: December 06, 2025 at 12:38 UTC
+Generated from source code on: December 06, 2025 at 18:54 UTC
 
-Modules auto-discovered: 42
+Modules auto-discovered: 44
+
+---
+
+## ngraph._version
+
+ngraph version metadata.
 
 ---
 
@@ -2600,6 +2606,152 @@ Attributes:
 
 ---
 
+## ngraph.lib.nx
+
+NetworkX graph conversion utilities.
+
+This module provides functions to convert between NetworkX graphs and the
+internal graph representation used by ngraph for high-performance algorithms.
+
+Example:
+    >>> import networkx as nx
+    >>> from ngraph.lib.nx import from_networkx, to_networkx
+    >>>
+    >>> # Create a NetworkX graph
+    >>> G = nx.DiGraph()
+    >>> G.add_edge("A", "B", capacity=100.0, cost=10)
+    >>> G.add_edge("B", "C", capacity=50.0, cost=5)
+    >>>
+    >>> # Convert to ngraph format for analysis
+    >>> graph, node_map, edge_map = from_networkx(G)
+    >>>
+    >>> # Use with ngraph algorithms...
+    >>>
+    >>> # Convert back to NetworkX
+    >>> G_out = to_networkx(graph, node_map)
+
+### EdgeMap
+
+Bidirectional mapping between internal edge IDs and original edge references.
+
+When converting a NetworkX graph, each edge is assigned an internal integer ID
+(ext_edge_id). This class preserves the mapping for interpreting algorithm
+results and updating the original graph.
+
+Attributes:
+    to_ref: Maps internal edge ID to original (source, target, key) tuple
+    from_ref: Maps original (source, target, key) to list of internal edge IDs
+        (list because bidirectional=True creates two IDs per edge)
+
+Example:
+    >>> graph, node_map, edge_map = from_networkx(G)
+    >>> # After running algorithms, map flow results back to original edges
+    >>> for ext_id, flow in enumerate(flow_state.edge_flow_view()):
+    ...     if flow > 0:
+    ...         u, v, key = edge_map.to_ref[ext_id]
+    ...         G.edges[u, v, key]["flow"] = flow
+
+**Attributes:**
+
+- `to_ref` (Dict[int, EdgeRef]) = {}
+- `from_ref` (Dict[EdgeRef, List[int]]) = {}
+
+### NodeMap
+
+Bidirectional mapping between node names and integer indices.
+
+When converting a NetworkX graph to the internal representation, node names
+(which can be any hashable type) are mapped to contiguous integer indices
+starting from 0. This class preserves the mapping for result interpretation
+and back-conversion.
+
+Attributes:
+    to_index: Maps original node names to integer indices
+    to_name: Maps integer indices back to original node names
+
+Example:
+    >>> node_map = NodeMap.from_names(["A", "B", "C"])
+    >>> node_map.to_index["A"]
+    0
+    >>> node_map.to_name[1]
+    'B'
+
+**Attributes:**
+
+- `to_index` (Dict[Hashable, int]) = {}
+- `to_name` (Dict[int, Hashable]) = {}
+
+**Methods:**
+
+- `from_names(names: 'List[Hashable]') -> "'NodeMap'"` - Create a NodeMap from a list of node names.
+
+### from_networkx(G: 'NxGraph', *, capacity_attr: 'str' = 'capacity', cost_attr: 'str' = 'cost', default_capacity: 'float' = 1.0, default_cost: 'int' = 1, bidirectional: 'bool' = False) -> 'Tuple[netgraph_core.StrictMultiDiGraph, NodeMap, EdgeMap]'
+
+Convert a NetworkX graph to ngraph's internal graph format.
+
+Converts any NetworkX graph (DiGraph, MultiDiGraph, Graph, MultiGraph) to
+netgraph_core.StrictMultiDiGraph. Node names are mapped to integer indices;
+the returned NodeMap and EdgeMap preserve mappings for result interpretation.
+
+Args:
+    G: NetworkX graph (DiGraph, MultiDiGraph, Graph, or MultiGraph)
+    capacity_attr: Edge attribute name for capacity (default: "capacity")
+    cost_attr: Edge attribute name for cost (default: "cost")
+    default_capacity: Capacity value when attribute is missing (default: 1.0)
+    default_cost: Cost value when attribute is missing (default: 1)
+    bidirectional: If True, add reverse edge for each edge. Useful for
+        undirected connectivity analysis. (default: False)
+
+Returns:
+    Tuple of (graph, node_map, edge_map) where:
+
+- graph: netgraph_core.StrictMultiDiGraph ready for algorithms
+- node_map: NodeMap for converting node indices back to names
+- edge_map: EdgeMap for converting edge IDs back to (u, v, key) refs
+
+Raises:
+    TypeError: If G is not a NetworkX graph
+    ValueError: If graph has no nodes
+
+Example:
+    >>> import networkx as nx
+    >>> G = nx.DiGraph()
+    >>> G.add_edge("src", "dst", capacity=100.0, cost=10)
+    >>> graph, node_map, edge_map = from_networkx(G)
+    >>> graph.num_nodes()
+    2
+    >>> node_map.to_index["src"]
+    0
+    >>> edge_map.to_ref[0]  # First edge
+    ('dst', 'src', 0)  # sorted node order: dst < src
+
+### to_networkx(graph: 'netgraph_core.StrictMultiDiGraph', node_map: 'Optional[NodeMap]' = None, *, capacity_attr: 'str' = 'capacity', cost_attr: 'str' = 'cost') -> "'nx.MultiDiGraph'"
+
+Convert ngraph's internal graph format back to NetworkX MultiDiGraph.
+
+Reconstructs a NetworkX graph from the internal representation. If a
+NodeMap is provided, original node names are restored; otherwise, nodes
+are labeled with integer indices.
+
+Args:
+    graph: netgraph_core.StrictMultiDiGraph to convert
+    node_map: Optional NodeMap to restore original node names.
+        If None, nodes are labeled 0, 1, 2, ...
+    capacity_attr: Edge attribute name for capacity (default: "capacity")
+    cost_attr: Edge attribute name for cost (default: "cost")
+
+Returns:
+    nx.MultiDiGraph with edges and attributes from the internal graph
+
+Example:
+    >>> graph, node_map, edge_map = from_networkx(G)
+    >>> # ... run algorithms ...
+    >>> G_out = to_networkx(graph, node_map)
+    >>> list(G_out.nodes())
+    ['A', 'B', 'C']
+
+---
+
 
 ## Error Handling
 

docs/reference/api.md

@@ -132,7 +132,74 @@ print(list(all_data["steps"].keys()))
 
 **Integration:** Used by all workflow steps for result storage. Provides consistent access pattern for analysis outputs.
 
-## 3. Basic Analysis
+## 3. NetworkX Integration
+
+Convert between NetworkX graphs and the internal graph format for algorithm execution.
+
+### Converting from NetworkX
+
+```python
+import networkx as nx
+from ngraph import from_networkx, to_networkx
+import netgraph_core
+
+# Create or load a NetworkX graph
+G = nx.DiGraph()
+G.add_edge("A", "B", capacity=100.0, cost=10)
+G.add_edge("B", "C", capacity=50.0, cost=5)
+G.add_edge("A", "C", capacity=30.0, cost=25)
+
+# Convert to internal format
+graph, node_map, edge_map = from_networkx(G)
+
+# Use with Core algorithms
+backend = netgraph_core.Backend.cpu()
+algorithms = netgraph_core.Algorithms(backend)
+handle = algorithms.build_graph(graph)
+
+# Run shortest path
+src_idx = node_map.to_index["A"]
+dst_idx = node_map.to_index["C"]
+dists, _ = algorithms.spf(handle, src=src_idx, dst=dst_idx)
+print(f"Shortest path cost A->C: {dists[dst_idx]}")  # 15 (via B)
+```
+
+**Key Functions:**
+
+- `from_networkx(G, *, capacity_attr, cost_attr, default_capacity, default_cost, bidirectional)` - Convert NetworkX graph to internal format
+- `to_networkx(graph, node_map, *, capacity_attr, cost_attr)` - Convert back to NetworkX MultiDiGraph
+
+**Mapping Classes:**
+
+- `NodeMap` - Bidirectional mapping between node names and integer indices
+  - `to_index[name]` - Get integer index for node name
+  - `to_name[idx]` - Get node name for integer index
+- `EdgeMap` - Bidirectional mapping between edge IDs and original edge references
+  - `to_ref[edge_id]` - Get (source, target, key) tuple for edge ID
+  - `from_ref[(u, v, key)]` - Get list of edge IDs for original edge
+
+**Options:**
+
+- `bidirectional=True` - Add reverse edge for each edge (for undirected analysis)
+- `capacity_attr` / `cost_attr` - Custom attribute names for capacity and cost
+- `default_capacity` / `default_cost` - Default values when attributes missing
+
+### Writing Results Back
+
+```python
+# After algorithm execution, map results back to original graph
+flow_state = netgraph_core.FlowState(graph)
+# ... place flow ...
+
+# Use edge_map to update original NetworkX graph
+edge_flows = flow_state.edge_flow_view()
+for edge_id, flow in enumerate(edge_flows):
+    if flow > 0:
+        u, v, key = edge_map.to_ref[edge_id]
+        G.edges[u, v, key]["flow"] = float(flow)
+```
+
+## 4. Basic Analysis
 
 Essential analysis capabilities for network evaluation.
 
@@ -266,7 +333,7 @@ for pair, edge_impacts in sensitivity.items():
         print(f"  {edge_key}: -{flow_reduction:.2f}")
 ```
 
-## 4. Monte Carlo Analysis
+## 5. Monte Carlo Analysis
 
 Probabilistic failure analysis using FailureManager.
 
@@ -321,7 +388,7 @@ for iter_result in results["results"]:
 - `run_demand_placement_monte_carlo(...)` - Traffic demand placement under failures
 - `run_monte_carlo_analysis(analysis_func, ...)` - Generic Monte Carlo with custom function
 
-## 5. Workflow Steps
+## 6. Workflow Steps
 
 Pre-built analysis steps for YAML-driven workflows.
 
@@ -388,7 +455,7 @@ workflow:
     aggregation_level: 2
 ```
 
-## 6. Types Reference
+## 7. Types Reference
 
 ### Enums
 
@@ -435,7 +502,7 @@ iter_result.flows    # List[FlowEntry]
 iter_result.summary  # FlowSummary
 ```
 
-## 7. Complete Example
+## 8. Complete Example
 
 ```python
 from ngraph import Network, Node, Link, analyze, Mode
@@ -480,7 +547,7 @@ for pair, impacts in sensitivity.items():
         print(f"  {edge}: {impact:.1f}")
 ```
 
-## 8. Performance Notes
+## 9. Performance Notes
 
 NetGraph uses a hybrid Python+C++ architecture:
 

ngraph/__init__.py

@@ -7,6 +7,8 @@
     analyze() - Create an analysis context for network queries
     AnalysisContext - Prepared state for efficient repeated analysis
     Network, Node, Link - Network topology model
+    from_networkx() - Convert NetworkX graph to internal format
+    to_networkx() - Convert internal format back to NetworkX
 
 Example:
     from ngraph import Network, Node, Link, analyze
@@ -28,29 +30,22 @@
 
 from __future__ import annotations
 
-# Utilities
 from ngraph import cli, logging
-
-# Analysis (primary API)
+from ngraph._version import __version__
 from ngraph.analysis import AnalysisContext, analyze
-
-# Execution
 from ngraph.exec.failure.manager import FailureManager
+from ngraph.lib.nx import EdgeMap, NodeMap, from_networkx, to_networkx
 from ngraph.model.demand.matrix import TrafficMatrixSet
-
-# Model
 from ngraph.model.network import Link, Network, Node, RiskGroup
 from ngraph.model.path import Path
 from ngraph.results.artifacts import CapacityEnvelope
-
-# Results
 from ngraph.results.flow import FlowEntry, FlowIterationResult, FlowSummary
-
-# Types
 from ngraph.types.base import EdgeSelect, FlowPlacement, Mode
 from ngraph.types.dto import EdgeRef, MaxFlowResult
 
 __all__ = [
+    # Version
+    "__version__",
     # Model
     "Network",
     "Node",
@@ -74,6 +69,11 @@
     "CapacityEnvelope",
     # Execution
     "FailureManager",
+    # Library integrations (NetworkX)
+    "EdgeMap",
+    "NodeMap",
+    "from_networkx",
+    "to_networkx",
     # Utilities
     "cli",
     "logging",

ngraph/_version.py

@@ -0,0 +1,5 @@
+"""ngraph version metadata."""
+
+__all__ = ["__version__"]
+
+__version__ = "0.12.1"

ngraph/lib/__init__.py

@@ -0,0 +1,13 @@
+"""Library utilities for ngraph.
+
+This package contains integration modules for external libraries.
+"""
+
+from ngraph.lib.nx import EdgeMap, NodeMap, from_networkx, to_networkx
+
+__all__ = [
+    "EdgeMap",
+    "NodeMap",
+    "from_networkx",
+    "to_networkx",
+]