ngraph 0.12.2__tar.gz

ngraph-0.12.2/LICENSE

@@ -0,0 +1,148 @@
+GNU AFFERO GENERAL PUBLIC LICENSE
+Version 3, 19 November 2007
+
+Copyright (C) 2007 Free Software Foundation, Inc. <https://fsf.org/>
+Everyone is permitted to copy and distribute verbatim copies
+of this license document, but changing it is not allowed.
+
+Preamble
+
+The GNU Affero General Public License is a free, copyleft license for
+software and other kinds of works, specifically designed to ensure
+cooperation with the community in the case of network server software.
+
+The licenses for most software and other practical works are designed
+to take away your freedom to share and change the works.  By contrast,
+our General Public Licenses are intended to guarantee your freedom to
+share and change all versions of a program--to make sure it remains free
+software for all its users.
+
+When we speak of free software, we are referring to freedom, not
+price.  Our General Public Licenses are designed to make sure that you
+have the freedom to distribute copies of free software (and charge for
+them if you wish), that you receive source code or can get it if you
+want it, that you can change the software or use pieces of it in new
+free programs, and that you know you can do these things.
+
+Developers that use our General Public Licenses protect your rights
+with two steps: (1) assert copyright on the software, and (2) offer
+you this License which gives you legal permission to copy, distribute
+and/or modify the software.
+
+A secondary benefit of defending all users' freedom is that
+improvements made in alternate versions of the program, if they
+receive widespread use, become available for other developers to
+incorporate.  Many developers of free software are heartened and
+encouraged by the resulting cooperation.  However, in the case of
+software used on network servers, this result may fail to come about.
+The GNU General Public License permits making a modified version and
+letting the public access it on a server without ever releasing its
+source code to the public.
+
+The GNU Affero General Public License is designed specifically to
+ensure that, in such cases, the modified source code becomes available
+to the community.  It requires the operator of a network server to
+provide the source code of the modified version running there to the
+users of that server.  Therefore, public use of a modified version, on
+a publicly accessible server, gives the public access to the source
+code of the modified version.
+
+An older license, called the Affero General Public License and
+published by Affero, was designed to accomplish similar goals.  This is
+a different license, not a version of the Affero GPL, but Affero has
+released a new version of the Affero GPL which permits relicensing under
+this license.
+
+The precise terms and conditions for copying, distribution and
+modification follow.
+
+TERMS AND CONDITIONS
+
+0. Definitions.
+
+"This License" refers to version 3 of the GNU Affero General Public License.
+
+"Copyright" also means copyright-like laws that apply to other kinds of
+works, such as semiconductor masks.
+
+"The Program" refers to any copyrightable work licensed under this
+License.  Each licensee is addressed as "you".  "Licensees" and
+"recipients" may be individuals or organizations.
+
+To "modify" a work means to copy from or adapt all or part of the work
+in a fashion requiring copyright permission, other than the making of an
+exact copy.  The resulting work is called a "modified version" of the
+earlier work or a work "based on" the earlier work.
+
+A "covered work" means either the unmodified Program or a work based
+on the Program.
+
+To "propagate" a work means to do anything with it that, without
+permission, would make you directly or secondarily liable for
+infringement under applicable copyright law, except executing it on a
+computer or modifying a private copy.  Propagation includes copying,
+distribution (with or without modification), making available to the
+public, and in some countries other activities as well.
+
+To "convey" a work means any kind of propagation that enables other
+parties to make or receive copies.  Mere interaction with a user through
+a computer network, with no transfer of a copy, is not conveying.
+
+An interactive user interface displays "Appropriate Legal Notices"
+to the extent that it includes a convenient and prominently visible
+feature that (1) displays an appropriate copyright notice, and (2)
+tells the user that there is no warranty for the work (except to the
+extent that warranties are provided), that licensees may convey the
+work under this License, and how to view a copy of this License.  If
+the interface presents a list of user commands or options, such as a
+menu, a prominent item in the list meets this criterion.
+
+1. Source Code.
+
+The "source code" for a work means the preferred form of the work
+for making modifications to it.  "Object code" means any non-source
+form of a work.
+
+... (AGPLv3 full text continues; include the entire standard text without modification) ...
+
+How to Apply These Terms to Your New Programs
+
+If you develop a new program, and you want it to be of the greatest
+possible use to the public, the best way to achieve this is to make it
+free software which everyone can redistribute and change under these terms.
+
+To do so, attach the following notices to the program.  It is safest
+to attach them to the start of each source file to most effectively
+state the exclusion of warranty; and each file should have at least
+the "copyright" line and a pointer to where the full notice is found.
+
+    <one line to give the program's name and a brief idea of what it does.>
+    Copyright (C) <year>  <name of author>
+
+    This program is free software: you can redistribute it and/or modify
+    it under the terms of the GNU Affero General Public License as published by
+    the Free Software Foundation, either version 3 of the License, or
+    (at your option) any later version.
+
+    This program is distributed in the hope that it will be useful,
+    but WITHOUT ANY WARRANTY; without even the implied warranty of
+    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+    GNU Affero General Public License for more details.
+
+    You should have received a copy of the GNU Affero General Public License
+    along with this program.  If not, see <https://www.gnu.org/licenses/>.
+
+Also add information on how to contact you by electronic and paper mail.
+
+If your software can interact with users remotely through a computer
+network, you should also make sure that it provides a way for users to
+get its source.  For example, if your program is a web application, its
+interface could display a "Source" link that leads users to an archive
+of the code.  There are many ways you could offer source, and different
+solutions will be better for different programs; see section 13 for the
+specific requirements.
+
+You should also get your employer (if you work as a programmer) or school,
+if any, to sign a "copyright disclaimer" for the program, if necessary.
+For more information on this, and how to apply and follow the GNU AGPL, see
+<https://www.gnu.org/licenses/>.

ngraph-0.12.2/PKG-INFO

@@ -0,0 +1,238 @@
+Metadata-Version: 2.4
+Name: ngraph
+Version: 0.12.2
+Summary: A tool and a library for network modeling and analysis.
+Author: Andrey Golovanov
+License-Expression: AGPL-3.0-or-later
+Project-URL: Homepage, https://github.com/networmix/NetGraph
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Operating System :: OS Independent
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: networkx>=3.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: pandas>=2.0
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: netgraph-core>=0.3.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Requires-Dist: pytest-benchmark; extra == "dev"
+Requires-Dist: pytest-mock; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: numpy; extra == "dev"
+Requires-Dist: matplotlib; extra == "dev"
+Requires-Dist: seaborn; extra == "dev"
+Requires-Dist: mkdocs-material; extra == "dev"
+Requires-Dist: pdoc; extra == "dev"
+Requires-Dist: ruff==0.11.13; extra == "dev"
+Requires-Dist: pyright==1.1.401; extra == "dev"
+Requires-Dist: pandas-stubs; extra == "dev"
+Requires-Dist: pre-commit; extra == "dev"
+Requires-Dist: build; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+Requires-Dist: jsonschema; extra == "dev"
+Dynamic: license-file
+
+# NetGraph
+
+[![Python-test](https://github.com/networmix/NetGraph/actions/workflows/python-test.yml/badge.svg?branch=main)](https://github.com/networmix/NetGraph/actions/workflows/python-test.yml)
+
+Scenario-driven network modeling and analysis framework combining Python's flexibility with high-performance C++ algorithms.
+
+## Overview
+
+NetGraph enables declarative modeling of network topologies, traffic matrices, and failure scenarios. It delegates computationally intensive graph algorithms to [NetGraph-Core](https://github.com/networmix/NetGraph-Core) while providing a rich Python API and CLI for orchestration.
+
+## Architecture
+
+NetGraph employs a **hybrid Python+C++ architecture**:
+
+- **Python layer (NetGraph)**: Scenario DSL parsing, workflow orchestration, result aggregation, and high-level APIs.
+- **C++ layer (NetGraph-Core)**: Performance-critical graph algorithms (SPF, KSP, Max-Flow) executing in optimized C++ with the GIL released.
+
+## Key Features
+
+### 1. Modeling & DSL
+
+- **Declarative Scenarios**: Define topology, traffic, and workflows in validated YAML.
+- **Blueprints**: Reusable topology templates (e.g., Clos fabrics, regions) with parameterized expansion.
+- **Strict Multigraph**: Deterministic graph representation with stable edge IDs.
+
+### 2. Failure Analysis
+
+- **Policy Engine**: Weighted failure modes with multiple policy rules per mode.
+- **Non-Destructive**: Runtime exclusions simulate failures without modifying the base topology.
+- **Risk Groups**: Model shared fate (e.g., fiber cuts, power zones).
+
+### 3. Traffic Engineering
+
+- **Routing Modes**: Unified modeling of **IP Routing** (static costs, oblivious to congestion) and **Traffic Engineering** (dynamic residuals, congestion-aware).
+- **Flow Placement**: Strategies for **ECMP** (Equal-Cost Multi-Path) and **WCMP** (Weighted Cost Multi-Path).
+- **Capacity Analysis**: Compute max-flow envelopes and demand allocation with configurable placement policies.
+
+### 4. Workflow & Integration
+
+- **Structured Results**: Export analysis artifacts to JSON for downstream processing.
+- **CLI**: Comprehensive command-line interface for validation and execution.
+- **Python API**: Full programmatic access to all modeling and solving capabilities.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install ngraph
+```
+
+### From Source
+
+```bash
+git clone https://github.com/networmix/NetGraph
+cd NetGraph
+make dev    # Install in editable mode with dev dependencies
+make check  # Run full test suite
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Validate and inspect a scenario
+ngraph inspect scenarios/backbone_clos.yml --detail
+
+# Run analysis workflow
+ngraph run scenarios/backbone_clos.yml --results clos.results.json
+```
+
+### Python API
+
+```python
+from ngraph import Network, Node, Link, analyze, Mode
+
+# Build network programmatically
+network = Network()
+network.add_node(Node("A"))
+network.add_node(Node("B"))
+network.add_node(Node("C"))
+network.add_link(Link("A", "B", capacity=10.0, cost=1.0))
+network.add_link(Link("B", "C", capacity=10.0, cost=1.0))
+
+# Compute max flow with the analyze() API
+flow = analyze(network).max_flow("^A$", "^C$", mode=Mode.COMBINE)
+print(f"Max flow: {flow}")  # {('^A$', '^C$'): 10.0}
+
+# Efficient repeated analysis with bound context
+ctx = analyze(network, source="^A$", sink="^C$", mode=Mode.COMBINE)
+baseline = ctx.max_flow()
+degraded = ctx.max_flow(excluded_nodes={"B"})  # Test failure scenario
+```
+
+## Example Scenario
+
+NetGraph scenarios define topology, configuration, and analysis steps in a unified YAML file. This example demonstrates **blueprints** for modular topology definition:
+
+```yaml
+seed: 42
+
+# Define reusable topology templates
+blueprints:
+  Clos_Fabric:
+    groups:
+      spine: {node_count: 2, name_template: "spine{node_num}"}
+      leaf:  {node_count: 4, name_template: "leaf{node_num}"}
+    adjacency:
+    - source: /leaf
+      target: /spine
+      pattern: mesh
+      link_params: {capacity: 100, cost: 1}
+    - source: /spine
+      target: /leaf
+      pattern: mesh
+      link_params: {capacity: 100, cost: 1}
+
+# Instantiate network from templates
+network:
+  groups:
+    site1: {use_blueprint: Clos_Fabric}
+    site2: {use_blueprint: Clos_Fabric}
+  adjacency:
+  - source: {path: site1/spine}
+    target: {path: site2/spine}
+    pattern: one_to_one
+    link_params: {capacity: 50, cost: 10}
+
+# Define traffic matrix
+traffic_matrix_set:
+  global_traffic:
+    - source_path: ^site1/leaf/
+      sink_path: ^site2/leaf/
+      demand: 100.0
+      mode: combine
+      flow_policy_config: SHORTEST_PATHS_ECMP
+
+# Define analysis workflow
+workflow:
+- step_type: NetworkStats
+  name: stats
+- step_type: MaxFlow
+  name: site_capacity
+  source_path: ^site1/leaf/
+  sink_path: ^site2/leaf/
+  mode: combine
+  shortest_path: false
+- step_type: MaximumSupportedDemand
+  name: max_demand
+  matrix_name: global_traffic
+```
+
+## Repository Structure
+
+```text
+ngraph/             # Python package source
+  dsl/              # Scenario parsing and blueprint expansion
+  model/            # Network and flow domain models
+  solver/           # Algorithms and Core wrappers
+  workflow/         # Analysis steps and orchestration
+scenarios/          # Example scenario definitions
+tests/              # Pytest suite (unit and integration)
+docs/               # Documentation source (MkDocs)
+dev/                # Development tools and scripts
+```
+
+## Development
+
+```bash
+make dev        # Setup environment
+make check      # Run tests and linting
+make lint       # Run linting only
+make test       # Run tests only
+make docs-serve # Preview documentation
+```
+
+## Requirements
+
+- **Python**: 3.9+
+- **NetGraph-Core**: Compatible C++ backend version
+
+## Documentation
+
+- **Site**: [networmix.github.io/NetGraph](https://networmix.github.io/NetGraph/)
+- **Tutorial**: [Getting Started](https://networmix.github.io/NetGraph/getting-started/tutorial/)
+- **Reference**: [API](https://networmix.github.io/NetGraph/reference/api/) | [CLI](https://networmix.github.io/NetGraph/reference/cli/) | [DSL](https://networmix.github.io/NetGraph/reference/dsl/)
+
+## License
+
+[GNU Affero General Public License v3.0 or later](LICENSE)

ngraph-0.12.2/README.md

@@ -0,0 +1,191 @@
+# NetGraph
+
+[![Python-test](https://github.com/networmix/NetGraph/actions/workflows/python-test.yml/badge.svg?branch=main)](https://github.com/networmix/NetGraph/actions/workflows/python-test.yml)
+
+Scenario-driven network modeling and analysis framework combining Python's flexibility with high-performance C++ algorithms.
+
+## Overview
+
+NetGraph enables declarative modeling of network topologies, traffic matrices, and failure scenarios. It delegates computationally intensive graph algorithms to [NetGraph-Core](https://github.com/networmix/NetGraph-Core) while providing a rich Python API and CLI for orchestration.
+
+## Architecture
+
+NetGraph employs a **hybrid Python+C++ architecture**:
+
+- **Python layer (NetGraph)**: Scenario DSL parsing, workflow orchestration, result aggregation, and high-level APIs.
+- **C++ layer (NetGraph-Core)**: Performance-critical graph algorithms (SPF, KSP, Max-Flow) executing in optimized C++ with the GIL released.
+
+## Key Features
+
+### 1. Modeling & DSL
+
+- **Declarative Scenarios**: Define topology, traffic, and workflows in validated YAML.
+- **Blueprints**: Reusable topology templates (e.g., Clos fabrics, regions) with parameterized expansion.
+- **Strict Multigraph**: Deterministic graph representation with stable edge IDs.
+
+### 2. Failure Analysis
+
+- **Policy Engine**: Weighted failure modes with multiple policy rules per mode.
+- **Non-Destructive**: Runtime exclusions simulate failures without modifying the base topology.
+- **Risk Groups**: Model shared fate (e.g., fiber cuts, power zones).
+
+### 3. Traffic Engineering
+
+- **Routing Modes**: Unified modeling of **IP Routing** (static costs, oblivious to congestion) and **Traffic Engineering** (dynamic residuals, congestion-aware).
+- **Flow Placement**: Strategies for **ECMP** (Equal-Cost Multi-Path) and **WCMP** (Weighted Cost Multi-Path).
+- **Capacity Analysis**: Compute max-flow envelopes and demand allocation with configurable placement policies.
+
+### 4. Workflow & Integration
+
+- **Structured Results**: Export analysis artifacts to JSON for downstream processing.
+- **CLI**: Comprehensive command-line interface for validation and execution.
+- **Python API**: Full programmatic access to all modeling and solving capabilities.
+
+## Installation
+
+### From PyPI
+
+```bash
+pip install ngraph
+```
+
+### From Source
+
+```bash
+git clone https://github.com/networmix/NetGraph
+cd NetGraph
+make dev    # Install in editable mode with dev dependencies
+make check  # Run full test suite
+```
+
+## Quick Start
+
+### CLI Usage
+
+```bash
+# Validate and inspect a scenario
+ngraph inspect scenarios/backbone_clos.yml --detail
+
+# Run analysis workflow
+ngraph run scenarios/backbone_clos.yml --results clos.results.json
+```
+
+### Python API
+
+```python
+from ngraph import Network, Node, Link, analyze, Mode
+
+# Build network programmatically
+network = Network()
+network.add_node(Node("A"))
+network.add_node(Node("B"))
+network.add_node(Node("C"))
+network.add_link(Link("A", "B", capacity=10.0, cost=1.0))
+network.add_link(Link("B", "C", capacity=10.0, cost=1.0))
+
+# Compute max flow with the analyze() API
+flow = analyze(network).max_flow("^A$", "^C$", mode=Mode.COMBINE)
+print(f"Max flow: {flow}")  # {('^A$', '^C$'): 10.0}
+
+# Efficient repeated analysis with bound context
+ctx = analyze(network, source="^A$", sink="^C$", mode=Mode.COMBINE)
+baseline = ctx.max_flow()
+degraded = ctx.max_flow(excluded_nodes={"B"})  # Test failure scenario
+```
+
+## Example Scenario
+
+NetGraph scenarios define topology, configuration, and analysis steps in a unified YAML file. This example demonstrates **blueprints** for modular topology definition:
+
+```yaml
+seed: 42
+
+# Define reusable topology templates
+blueprints:
+  Clos_Fabric:
+    groups:
+      spine: {node_count: 2, name_template: "spine{node_num}"}
+      leaf:  {node_count: 4, name_template: "leaf{node_num}"}
+    adjacency:
+    - source: /leaf
+      target: /spine
+      pattern: mesh
+      link_params: {capacity: 100, cost: 1}
+    - source: /spine
+      target: /leaf
+      pattern: mesh
+      link_params: {capacity: 100, cost: 1}
+
+# Instantiate network from templates
+network:
+  groups:
+    site1: {use_blueprint: Clos_Fabric}
+    site2: {use_blueprint: Clos_Fabric}
+  adjacency:
+  - source: {path: site1/spine}
+    target: {path: site2/spine}
+    pattern: one_to_one
+    link_params: {capacity: 50, cost: 10}
+
+# Define traffic matrix
+traffic_matrix_set:
+  global_traffic:
+    - source_path: ^site1/leaf/
+      sink_path: ^site2/leaf/
+      demand: 100.0
+      mode: combine
+      flow_policy_config: SHORTEST_PATHS_ECMP
+
+# Define analysis workflow
+workflow:
+- step_type: NetworkStats
+  name: stats
+- step_type: MaxFlow
+  name: site_capacity
+  source_path: ^site1/leaf/
+  sink_path: ^site2/leaf/
+  mode: combine
+  shortest_path: false
+- step_type: MaximumSupportedDemand
+  name: max_demand
+  matrix_name: global_traffic
+```
+
+## Repository Structure
+
+```text
+ngraph/             # Python package source
+  dsl/              # Scenario parsing and blueprint expansion
+  model/            # Network and flow domain models
+  solver/           # Algorithms and Core wrappers
+  workflow/         # Analysis steps and orchestration
+scenarios/          # Example scenario definitions
+tests/              # Pytest suite (unit and integration)
+docs/               # Documentation source (MkDocs)
+dev/                # Development tools and scripts
+```
+
+## Development
+
+```bash
+make dev        # Setup environment
+make check      # Run tests and linting
+make lint       # Run linting only
+make test       # Run tests only
+make docs-serve # Preview documentation
+```
+
+## Requirements
+
+- **Python**: 3.9+
+- **NetGraph-Core**: Compatible C++ backend version
+
+## Documentation
+
+- **Site**: [networmix.github.io/NetGraph](https://networmix.github.io/NetGraph/)
+- **Tutorial**: [Getting Started](https://networmix.github.io/NetGraph/getting-started/tutorial/)
+- **Reference**: [API](https://networmix.github.io/NetGraph/reference/api/) | [CLI](https://networmix.github.io/NetGraph/reference/cli/) | [DSL](https://networmix.github.io/NetGraph/reference/dsl/)
+
+## License
+
+[GNU Affero General Public License v3.0 or later](LICENSE)

ngraph-0.12.2/ngraph/__init__.py

@@ -0,0 +1,80 @@
+"""NetGraph: Network modeling and analysis library.
+
+NetGraph provides interfaces for network topology modeling, traffic analysis, and
+capacity planning using a hybrid Python+C++ architecture.
+
+Primary API:
+    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
+
+    # Build network
+    net = Network()
+    net.add_node(Node(name="A"))
+    net.add_node(Node(name="B"))
+    net.add_link(Link(source="A", target="B", capacity=100.0))
+
+    # One-off analysis
+    flow = analyze(net).max_flow("^A$", "^B$")
+
+    # Efficient repeated analysis
+    ctx = analyze(net, source="^A$", sink="^B$")
+    baseline = ctx.max_flow()
+    degraded = ctx.max_flow(excluded_links=failed_links)
+"""
+
+from __future__ import annotations
+
+from ngraph import cli, logging
+from ngraph._version import __version__
+from ngraph.analysis import AnalysisContext, analyze
+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
+from ngraph.model.network import Link, Network, Node, RiskGroup
+from ngraph.model.path import Path
+from ngraph.results.artifacts import CapacityEnvelope
+from ngraph.results.flow import FlowEntry, FlowIterationResult, FlowSummary
+from ngraph.types.base import EdgeSelect, FlowPlacement, Mode
+from ngraph.types.dto import EdgeRef, MaxFlowResult
+
+__all__ = [
+    # Version
+    "__version__",
+    # Model
+    "Network",
+    "Node",
+    "Link",
+    "RiskGroup",
+    "Path",
+    "TrafficMatrixSet",
+    # Analysis (primary API)
+    "analyze",
+    "AnalysisContext",
+    # Types
+    "FlowPlacement",
+    "EdgeSelect",
+    "Mode",
+    "EdgeRef",
+    "MaxFlowResult",
+    # Results
+    "FlowEntry",
+    "FlowIterationResult",
+    "FlowSummary",
+    "CapacityEnvelope",
+    # Execution
+    "FailureManager",
+    # Library integrations (NetworkX)
+    "EdgeMap",
+    "NodeMap",
+    "from_networkx",
+    "to_networkx",
+    # Utilities
+    "cli",
+    "logging",
+]

ngraph-0.12.2/ngraph/__main__.py

@@ -0,0 +1,8 @@
+"""Entry point for running NetGraph as a module."""
+
+from __future__ import annotations
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

ngraph-0.12.2/ngraph/_version.py

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