Update documentation for clarity and consistency

Author: networmix

README.md

@@ -4,18 +4,20 @@
 
 [![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)
 
-NetGraph is a scenario-based network modeling and analysis framework written in Python. Design, simulate, and evaluate complex network topologies from small test cases to massive Data Center fabrics and WAN networks.
+NetGraph is a scenario-based network modeling and analysis framework written in Python. It allows you to design, simulate, and evaluate complex network topologies - ranging from small test cases to massive Data Center fabrics and WAN networks.
 
 ## Key Features
 
-- **Scenario-Based Modeling** [DONE]: Define complete network scenarios in YAML with topology, failures, traffic, and workflows
-- **Hierarchical Blueprints** [DONE]: Reusable network templates with nested structures and bracket expansion
-- **Flow Analysis** [DONE]: Calculate capacity with different flow placement strategies (e.g., shortest path only, ECMP/UCMP, etc.)
+- **Scenario-Based Modeling** [DONE]: Define complete network scenarios in YAML with topology, failures, traffic, and workflow
+- **Hierarchical Blueprints** [DONE]: Reusable network templates with nested structures and parameterization
+- **Demand Placement** [DONE]: Place traffic demands on the network with various flow placement strategies (e.g., shortest path only, ECMP/UCMP, etc.)
+- **Capacity Calculation** [DONE]: Calculate capacity with different flow placement strategies 
 - **Failure Simulation** [DONE]: Model component and risk groups failures for availability analysis
+- **Network Analysis** [IN PROGRESS]: Analyze capacity, failure tolerance, and efficiency
 
 ## Quick Start
 
-### Docker (Recommended)
+### Docker with JupyterLab (Recommended)
 
 ```bash
 git clone https://github.com/networmix/NetGraph
@@ -39,7 +41,7 @@ pip install -e '.[dev]'
 from ngraph.scenario import Scenario
 from ngraph.lib.flow_policy import FlowPlacement
 
-# Define a 3-tier Clos network with inter-fabric connectivity
+# Define two 3-tier Clos networks with inter-fabric connectivity
 clos_scenario_yaml = """
 blueprints:
   brick_2tier:
@@ -108,7 +110,7 @@ max_flow = network.max_flow(
     flow_placement=FlowPlacement.EQUAL_BALANCED
 )
 print(f"Maximum flow: {max_flow}")
-# Result: {('b1|b2', 'b1|b2'): 256.0}
+# Maximum flow: {('b1|b2', 'b1|b2'): 256.0}
 ```
 
 ## Documentation

docs/examples/basic.md

@@ -1,10 +1,6 @@
-# Basic Examples
+# Basic Example
 
-This guide demonstrates basic NetGraph functionality using a couple of simple examples. These fundamentals will help you understand the more complex scenarios in the [Clos Fabric Analysis](clos-fabric.md) example.
-
-## Calculating MaxFlow
-
-In this example, we'll create a simple network with parallel edges and alternative paths, then run max flow analysis with different flow placement policies.
+In this toy example, we'll create a simple graph with parallel edges and alternative paths, then run max flow analysis with different flow placement policies. 
 
 ### Creating a Simple Network
 
@@ -82,6 +78,8 @@ scenario = Scenario.from_yaml(scenario_yaml)
 network = scenario.network
 ```
 
+Note that here we used a simple `nodes` and `links` structure to directly define the network topology. In more complex scenarios, you would typically use `groups` and `adjacency` to define groups of nodes and their connections, or even leverage the `blueprints` to create reusable components. This advanced functionality is explained in the [DSL Reference](../reference/dsl.md) and used in the [Clos Fabric Analysis](clos-fabric.md) example.
+
 ### Flow Analysis Variants
 
 Now let's run MaxFlow using the high-level Network API:
@@ -112,17 +110,17 @@ print(f"Equal-balanced flow: {max_flow_shortest_balanced}")
 # Result: 2.0 (splits flow equally across parallel edges in A→B and B→C)
 ```
 
-### Key Concepts
+### Results Interpretation
 
 - **"True" MaxFlow**: Uses all available paths regardless of their cost
-- **Shortest Path**: Only uses paths with minimum cost
-- **EQUAL_BALANCED Flow Placement**: Distributes equally across parallel paths. Flow can be limited by the smallest capacity path.
+- **Shortest Path**: Only uses paths with the minimum cost
+- **EQUAL_BALANCED Flow Placement**: Distributes flows equally across all parallel paths. The toal flow can be limited by the smallest capacity path.
 
 Note that `EQUAL_BALANCED` flow placement is only applicable when calculating MaxFlow on shortest paths.
 
 ## Next Steps
 
-- **[Clos Fabric Analysis](clos-fabric.md)** - More complex example
 - **[Tutorial](../getting-started/tutorial.md)** - Build complete network scenarios
+- **[Clos Fabric Analysis](clos-fabric.md)** - More complex example
 - **[DSL Reference](../reference/dsl.md)** - Learn the full YAML syntax for scenarios
 - **[API Reference](../reference/api.md)** - Explore the Python API for advanced usage

docs/examples/clos-fabric.md

@@ -168,3 +168,8 @@ costs, pred = spf(network.to_strict_multidigraph(), src_node)
 paths = list(resolve_to_paths(src_node, dst_node, pred))
 print(f"Found {len(paths)} paths between segments")
 ```
+
+## Next Steps
+
+- **[DSL Reference](../reference/dsl.md)** - Learn the complete YAML syntax
+- **[API Reference](../reference/api.md)** - Explore the Python API in detail

docs/getting-started/installation.md

@@ -14,32 +14,32 @@ NetGraph can be used in two ways:
 
 1. Clone the repository:
 
-    ```bash
-    git clone https://github.com/networmix/NetGraph
-    ```
+   ```bash
+   git clone https://github.com/networmix/NetGraph
+   ```
 
 2. Build the Docker image:
 
-    ```bash
-    cd NetGraph
-    ./run.sh build
-    ```
+   ```bash
+   cd NetGraph
+   ./run.sh build
+   ```
 
 3. Start the container with JupyterLab server:
 
-    ```bash
-    ./run.sh run
-    ```
+   ```bash
+   ./run.sh run
+   ```
 
 4. Open the JupyterLab URL in your browser:
 
-    ```bash
-    http://127.0.0.1:8788/
-    ```
+   ```bash
+   http://127.0.0.1:8788/
+   ```
 
 5. Jupyter will show the content of `notebooks` directory and you can start using the provided notebooks (e.g., open scenario_dc.ipynb) or create your own.
 
-**Note**: Docker is instructed to mount the content of `NetGraph` directory into the `/root/env` directory inside container, so any changes made to any files in the `NetGraph` directory will be reflected in the container and vice versa. The `ngraph` package is installed in the container in editable mode, so you can make changes to the code and leverage them immediately in JupyterLab. But don't forget to restart the JupyterLab kernel to see the changes.
+**Note**: Docker is instructed to mount the content of `NetGraph` directory into the `/root/env` directory inside container, so any changes made to any files in the `NetGraph` directory will be reflected in the container and vice versa. The `ngraph` package is installed in the container in editable mode, so you can make changes to the code and leverage them immediately in JupyterLab. But **don't forget to restart the JupyterLab kernel** after making changes to the package code to see the effects in the running notebook.
 
 To exit the JupyterLab server, press `Ctrl+C` in the terminal where the server is running. To stop the remaining Docker container, run:
 
@@ -60,31 +60,41 @@ To exit the JupyterLab server, press `Ctrl+C` in the terminal where the server i
 
 1. Install the package using pip:
 
-    ```bash
-    pip install ngraph
-    ```
+   ```bash
+   pip install ngraph
+   ```
 
 2. Use the package in your Python code:
 
-    ```python
-    from ngraph.scenario import Scenario
-    from ngraph.explorer import NetworkExplorer
-    
-    scenario_yaml = """
-    network:
-      groups:
-        servers:
-          node_count: 2
-          name_template: "server-{node_num}"
-    """
-    
-    scenario = Scenario.from_yaml(scenario_yaml)
-    network = scenario.network
-    explorer = NetworkExplorer.explore_network(network)
-    explorer.print_tree(skip_leaves=True, detailed=False)
-    ```
+   ```python
+   from ngraph.scenario import Scenario
+
+   scenario_yaml = """
+   network:
+   name: "Two-Tier Clos Fabric"
+   groups:
+      leaf:
+         node_count: 4
+         name_template: "leaf-{node_num}"
+      spine:
+         node_count: 2  
+         name_template: "spine-{node_num}"
+   adjacency:
+      - source: /leaf
+         target: /spine
+         pattern: mesh
+         link_params:
+         capacity: 10
+         cost: 1
+   """
+
+   scenario = Scenario.from_yaml(scenario_yaml)
+   network = scenario.network
+   print(f"Created Clos fabric with {len(network.nodes)} nodes and {len(network.links)} links")
+   ```
 
 ## Next Steps
 
 - **[Quick Tutorial](tutorial.md)** - Build your first network scenario
-- **[DSL Reference](../reference/dsl.md)** - Learn the YAML syntax
+- **[DSL Reference](../reference/dsl.md)** - Learn the complete YAML syntax
+- **[API Reference](../reference/api.md)** - Explore the Python API in detail