Upload 107 files

.gitattributes

@@ -33,3 +33,5 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+graph-theory/source/examples/images/2500pxLondon_Underground_Overground.png filter=lfs diff=lfs merge=lfs -text
+graph-theory/source/examples/images/traffic_bi_directional.gif filter=lfs diff=lfs merge=lfs -text

Dockerfile

@@ -0,0 +1,18 @@
+FROM python:3.10
+
+RUN useradd -m -u 1000 user && python -m pip install --upgrade pip
+USER user
+ENV PATH="/home/user/.local/bin:$PATH"
+
+WORKDIR /app
+
+COPY --chown=user ./requirements.txt requirements.txt
+RUN pip install --no-cache-dir --upgrade -r requirements.txt
+
+COPY --chown=user . /app
+ENV MCP_TRANSPORT=http
+ENV MCP_PORT=7860
+
+EXPOSE 7860
+
+CMD ["python", "graph-theory/mcp_output/start_mcp.py"]

README.md

@@ -1,10 +1,32 @@
 ---
-title: Graph Theory
-emoji: 📈
-colorFrom: pink
-colorTo: blue
+title: Graph-Theory MCP
+emoji: 🤖
+colorFrom: blue
+colorTo: purple
 sdk: docker
+sdk_version: "4.26.0"
+app_file: app.py
 pinned: false
 ---
 
-Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference
+# Graph-Theory MCP Service
+
+Auto-generated MCP service for graph-theory.
+
+## Usage
+
+```
+https://None-graph-theory-mcp.hf.space/mcp
+```
+
+## Connect with Cursor
+
+```json
+{
+  "mcpServers": {
+    "graph-theory": {
+      "url": "https://None-graph-theory-mcp.hf.space/mcp"
+    }
+  }
+}
+```

app.py

@@ -0,0 +1,45 @@
+from fastapi import FastAPI
+import os
+import sys
+
+mcp_plugin_path = os.path.join(os.path.dirname(__file__), "graph-theory", "mcp_output", "mcp_plugin")
+sys.path.insert(0, mcp_plugin_path)
+
+app = FastAPI(
+    title="Graph-Theory MCP Service",
+    description="Auto-generated MCP service for graph-theory",
+    version="1.0.0"
+)
+
+@app.get("/")
+def root():
+    return {
+        "service": "Graph-Theory MCP Service",
+        "version": "1.0.0",
+        "status": "running",
+        "transport": os.environ.get("MCP_TRANSPORT", "http")
+    }
+
+@app.get("/health")
+def health_check():
+    return {"status": "healthy", "service": "graph-theory MCP"}
+
+@app.get("/tools")
+def list_tools():
+    try:
+        from mcp_service import create_app
+        mcp_app = create_app()
+        tools = []
+        for tool_name, tool_func in mcp_app.tools.items():
+            tools.append({
+                "name": tool_name,
+                "description": tool_func.__doc__ or "No description available"
+            })
+        return {"tools": tools}
+    except Exception as e:
+        return {"error": f"Failed to load tools: {str(e)}"}
+
+if __name__ == "__main__":
+    import uvicorn
+    port = int(os.environ.get("PORT", 7860))
+    uvicorn.run(app, host="0.0.0.0", port=port)

graph-theory/mcp_output/README_MCP.md

@@ -0,0 +1,61 @@
+# Graph Theory MCP (Model Context Protocol) Service
+
+## Project Introduction
+
+The Graph Theory MCP service is a comprehensive library designed to facilitate graph-related computations and analyses. It provides a wide range of functionalities, including graph traversal, shortest path calculations, flow problems, and visualization tools. This service is ideal for developers working on projects that require complex graph operations and optimizations.
+
+## Installation Method
+
+To install the Graph Theory MCP service, ensure you have Python installed and then use the following pip command to install the necessary dependencies:
+
+- Required: numpy, scipy
+- Optional: matplotlib (for visualization)
+
+```shell
+pip install numpy scipy
+pip install matplotlib  # Optional for visualization
+```
+
+## Quick Start
+
+Here's a quick example to get you started with the Graph Theory MCP service:
+
+```python
+from graph.adjacency_matrix import adjacency_matrix
+from graph.shortest_path import shortest_path
+
+# Example graph represented as an adjacency list
+graph = {
+    'A': {'B': 1, 'C': 4},
+    'B': {'C': 2, 'D': 5},
+    'C': {'D': 1},
+    'D': {}
+}
+
+# Convert to adjacency matrix
+matrix = adjacency_matrix(graph)
+
+# Find the shortest path from A to D
+path = shortest_path(graph, 'A', 'D')
+print("Shortest path from A to D:", path)
+```
+
+## Available Tools and Endpoints List
+
+- **Graph Construction and Manipulation**: Functions like `adjacency_matrix`, `all_pairs_shortest_paths`, and `all_simple_paths` help in constructing and analyzing graphs.
+- **Path and Flow Analysis**: Use `shortest_path`, `maximum_flow`, and `minimum_cost_flow_using_successive_shortest_path` for pathfinding and flow optimization.
+- **Graph Algorithms**: Implement algorithms such as `breadth_first_search`, `depth_first_search`, and `topological_sort`.
+- **Specialized Problems**: Solve complex problems with `assignment_problem`, `traffic_scheduling_problem`, and `transshipment_problem`.
+- **Visualization**: Visualize graphs using `plot_2d`, `plot_3d`, and `visualise`.
+
+## Common Issues and Notes
+
+- Ensure all required dependencies are installed to avoid import errors.
+- For performance optimization, consider the complexity of the graph algorithms being used, especially for large graphs.
+- Optional dependencies like `matplotlib` are necessary for visualization features.
+
+## Reference Links or Documentation
+
+For more detailed documentation and examples, visit the [Graph Theory GitHub Repository](https://github.com/root-11/graph-theory).
+
+For further assistance, you can explore the code structure and documentation once the repository is indexed, which typically takes 2-10 minutes.

graph-theory/mcp_output/analysis.json

@@ -0,0 +1,915 @@
+{
+  "summary": {
+    "repository_url": "https://github.com/root-11/graph-theory",
+    "summary": "Imported via zip fallback, file count: 62",
+    "file_tree": {
+      ".github/workflows/codecov.yml": {
+        "size": 758
+      },
+      ".github/workflows/publish.yml": {
+        "size": 533
+      },
+      ".github/workflows/python-test.yml": {
+        "size": 971
+      },
+      "README.md": {
+        "size": 21562
+      },
+      "datasets/readme.md": {
+        "size": 123
+      },
+      "examples/__init__.py": {
+        "size": 0
+      },
+      "examples/graphs.py": {
+        "size": 27277
+      },
+      "examples/readme.md": {
+        "size": 2079
+      },
+      "graph/__init__.py": {
+        "size": 61
+      },
+      "graph/adjacency_matrix.py": {
+        "size": 1109
+      },
+      "graph/all_pairs_shortest_path.py": {
+        "size": 1346
+      },
+      "graph/all_paths.py": {
+        "size": 2031
+      },
+      "graph/all_simple_paths.py": {
+        "size": 1026
+      },
+      "graph/assignment_problem.py": {
+        "size": 8343
+      },
+      "graph/base.py": {
+        "size": 17623
+      },
+      "graph/bfs.py": {
+        "size": 2255
+      },
+      "graph/core.py": {
+        "size": 14015
+      },
+      "graph/critical_path.py": {
+        "size": 7014
+      },
+      "graph/cycle.py": {
+        "size": 1500
+      },
+      "graph/dag.py": {
+        "size": 3984
+      },
+      "graph/degree_of_separation.py": {
+        "size": 529
+      },
+      "graph/dfs.py": {
+        "size": 3120
+      },
+      "graph/distance_map.py": {
+        "size": 2862
+      },
+      "graph/finite_state_machine.py": {
+        "size": 2187
+      },
+      "graph/hash_methods.py": {
+        "size": 4476
+      },
+      "graph/max_flow.py": {
+        "size": 3739
+      },
+      "graph/max_flow_min_cut.py": {
+        "size": 1155
+      },
+      "graph/maximum_flow_min_cut.py": {
+        "size": 1159
+      },
+      "graph/min_cost_flow.py": {
+        "size": 4099
+      },
+      "graph/minmax.py": {
+        "size": 453
+      },
+      "graph/minsum.py": {
+        "size": 469
+      },
+      "graph/partite.py": {
+        "size": 1511
+      },
+      "graph/random.py": {
+        "size": 2580
+      },
+      "graph/shortest_path.py": {
+        "size": 13708
+      },
+      "graph/shortest_tree_all_pairs.py": {
+        "size": 1347
+      },
+      "graph/topological_sort.py": {
+        "size": 1096
+      },
+      "graph/traffic_scheduling_problem.py": {
+        "size": 21370
+      },
+      "graph/transshipment_problem.py": {
+        "size": 9102
+      },
+      "graph/tsp.py": {
+        "size": 11203
+      },
+      "graph/version.py": {
+        "size": 131
+      },
+      "graph/visuals.py": {
+        "size": 5430
+      },
+      "requirements.txt": {
+        "size": 0
+      },
+      "setup.py": {
+        "size": 3104
+      },
+      "test-requirements.txt": {
+        "size": 29
+      },
+      "tests/__init__.py": {
+        "size": 673
+      },
+      "tests/test_assignment_problem.py": {
+        "size": 2876
+      },
+      "tests/test_basics.py": {
+        "size": 8869
+      },
+      "tests/test_facility_location_problem.py": {
+        "size": 1231
+      },
+      "tests/test_finite_state_machine.py": {
+        "size": 2614
+      },
+      "tests/test_flow_problem.py": {
+        "size": 7058
+      },
+      "tests/test_graph.py": {
+        "size": 354779
+      },
+      "tests/test_hashgraph.py": {
+        "size": 2681
+      },
+      "tests/test_random.py": {
+        "size": 1665
+      },
+      "tests/test_search.py": {
+        "size": 19202
+      },
+      "tests/test_spatial_graph.py": {
+        "size": 6926
+      },
+      "tests/test_topology.py": {
+        "size": 9945
+      },
+      "tests/test_traffic_scheduling_problem.py": {
+        "size": 30238
+      },
+      "tests/test_transform.py": {
+        "size": 677
+      },
+      "tests/test_transshipment_problem.py": {
+        "size": 4056
+      },
+      "tests/test_tsp.py": {
+        "size": 14852
+      },
+      "tests/test_visuals.py": {
+        "size": 861
+      },
+      "tests/test_wtap.py": {
+        "size": 8086
+      }
+    },
+    "processed_by": "zip_fallback",
+    "success": true
+  },
+  "structure": {
+    "packages": [
+      "source.examples",
+      "source.graph",
+      "source.tests"
+    ]
+  },
+  "dependencies": {
+    "has_environment_yml": false,
+    "has_requirements_txt": true,
+    "pyproject": false,
+    "setup_cfg": false,
+    "setup_py": true
+  },
+  "entry_points": {
+    "imports": [],
+    "cli": [],
+    "modules": []
+  },
+  "llm_analysis": {
+    "core_modules": [
+      {
+        "package": "examples",
+        "module": "graphs",
+        "functions": [
+          "grid",
+          "london_underground"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "grid": [
+            "x",
+            "y",
+            "bidirectional"
+          ],
+          "london_underground": []
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "adjacency_matrix",
+        "functions": [
+          "adjacency_matrix"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "adjacency_matrix": [
+            "graph"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "all_pairs_shortest_path",
+        "functions": [
+          "all_pairs_shortest_paths"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "all_pairs_shortest_paths": [
+            "graph"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "all_paths",
+        "functions": [
+          "all_paths"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "all_paths": [
+            "graph",
+            "start",
+            "end"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "all_simple_paths",
+        "functions": [
+          "all_simple_paths"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "all_simple_paths": [
+            "graph",
+            "start",
+            "end"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "assignment_problem",
+        "functions": [
+          "ap_solver",
+          "wtap_solver"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "ap_solver": [
+            "graph"
+          ],
+          "wtap_solver": [
+            "probabilities",
+            "weapons",
+            "target_values"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "base",
+        "functions": [
+          "components",
+          "has_path",
+          "is_subgraph",
+          "network_size",
+          "same_path",
+          "subgraph"
+        ],
+        "classes": [
+          "BasicGraph"
+        ],
+        "function_signatures": {
+          "subgraph": [
+            "graph",
+            "nodes"
+          ],
+          "is_subgraph": [
+            "graph1",
+            "graph2"
+          ],
+          "same_path": [
+            "path1",
+            "path2"
+          ],
+          "has_path": [
+            "graph",
+            "path"
+          ],
+          "network_size": [
+            "graph",
+            "n1",
+            "degrees_of_separation"
+          ],
+          "components": [
+            "graph"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "bfs",
+        "functions": [
+          "breadth_first_search",
+          "breadth_first_walk"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "breadth_first_search": [
+            "graph",
+            "start",
+            "end"
+          ],
+          "breadth_first_walk": [
+            "graph",
+            "start",
+            "end",
+            "reversed_walk"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "core",
+        "functions": [],
+        "classes": [
+          "Graph",
+          "Graph3D"
+        ],
+        "function_signatures": {},
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "critical_path",
+        "functions": [
+          "critical_path",
+          "critical_path_minimize_for_slack"
+        ],
+        "classes": [
+          "Task"
+        ],
+        "function_signatures": {
+          "critical_path": [
+            "graph"
+          ],
+          "critical_path_minimize_for_slack": [
+            "graph"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "cycle",
+        "functions": [
+          "cycle",
+          "has_cycles"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "cycle": [
+            "graph",
+            "start",
+            "mid",
+            "end"
+          ],
+          "has_cycles": [
+            "graph"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "dag",
+        "functions": [
+          "phase_lines",
+          "sources"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "phase_lines": [
+            "graph"
+          ],
+          "sources": [
+            "graph",
+            "n"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "degree_of_separation",
+        "functions": [
+          "degree_of_separation"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "degree_of_separation": [
+            "graph",
+            "n1",
+            "n2"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "dfs",
+        "functions": [
+          "depth_first_search",
+          "depth_scan"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "depth_first_search": [
+            "graph",
+            "start",
+            "end"
+          ],
+          "depth_scan": [
+            "graph",
+            "start",
+            "criteria"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "distance_map",
+        "functions": [
+          "distance_map"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "distance_map": [
+            "graph",
+            "starts",
+            "ends",
+            "reverse"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "finite_state_machine",
+        "functions": [],
+        "classes": [
+          "FiniteStateMachine"
+        ],
+        "function_signatures": {},
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "hash_methods",
+        "functions": [
+          "flow_graph_hash",
+          "graph_hash",
+          "merkle_tree"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "graph_hash": [
+            "graph"
+          ],
+          "flow_graph_hash": [
+            "graph"
+          ],
+          "merkle_tree": [
+            "data_blocks"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "max_flow",
+        "functions": [
+          "maximum_flow"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "maximum_flow": [
+            "graph",
+            "start",
+            "end"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "max_flow_min_cut",
+        "functions": [
+          "maximum_flow_min_cut"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "maximum_flow_min_cut": [
+            "graph",
+            "start",
+            "end"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "maximum_flow_min_cut",
+        "functions": [
+          "maximum_flow_min_cut"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "maximum_flow_min_cut": [
+            "graph",
+            "start",
+            "end"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "min_cost_flow",
+        "functions": [
+          "minimum_cost_flow_using_successive_shortest_path"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "minimum_cost_flow_using_successive_shortest_path": [
+            "costs",
+            "inventory",
+            "capacity"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "minmax",
+        "functions": [
+          "minmax"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "minmax": [
+            "graph"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "minsum",
+        "functions": [
+          "minsum"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "minsum": [
+            "graph"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "partite",
+        "functions": [
+          "is_partite"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "is_partite": [
+            "graph",
+            "n"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "random",
+        "functions": [
+          "random_xy_graph",
+          "xy_distance"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "xy_distance": [
+            "n1",
+            "n2"
+          ],
+          "random_xy_graph": [
+            "nodes",
+            "x_max",
+            "y_max",
+            "edges",
+            "seed"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "shortest_path",
+        "functions": [
+          "distance_from_path",
+          "shortest_path",
+          "shortest_path_bidirectional"
+        ],
+        "classes": [
+          "BiDirectionalSearch",
+          "SPLength",
+          "ScanThread",
+          "ShortestPathCache"
+        ],
+        "function_signatures": {
+          "shortest_path": [
+            "graph",
+            "start",
+            "end",
+            "avoids"
+          ],
+          "shortest_path_bidirectional": [
+            "graph",
+            "start",
+            "end",
+            "avoids"
+          ],
+          "distance_from_path": [
+            "graph",
+            "path"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "shortest_tree_all_pairs",
+        "functions": [
+          "shortest_tree_all_pairs"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "shortest_tree_all_pairs": [
+            "graph"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "topological_sort",
+        "functions": [
+          "topological_sort"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "topological_sort": [
+            "graph",
+            "key"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "traffic_scheduling_problem",
+        "functions": [
+          "check_user_input",
+          "is_ap_solvable",
+          "jam_solver",
+          "moves_to_synchronous_moves",
+          "path_to_moves"
+        ],
+        "classes": [
+          "JamSolver",
+          "Load",
+          "NoSolution",
+          "State",
+          "StopCondition",
+          "Timer",
+          "UnSolvable"
+        ],
+        "function_signatures": {
+          "check_user_input": [
+            "graph",
+            "loads"
+          ],
+          "is_ap_solvable": [
+            "assignments"
+          ],
+          "path_to_moves": [
+            "path"
+          ],
+          "moves_to_synchronous_moves": [
+            "moves",
+            "loads"
+          ],
+          "jam_solver": [
+            "graph",
+            "loads",
+            "timeout",
+            "synchronous_moves",
+            "return_on_first"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "transshipment_problem",
+        "functions": [
+          "clondike_transshipment_problem",
+          "find",
+          "find_perfect_circuit",
+          "jobs_from_path",
+          "path_from_schedule",
+          "schedule",
+          "schedule_rail_system"
+        ],
+        "classes": [
+          "Train"
+        ],
+        "function_signatures": {
+          "clondike_transshipment_problem": [],
+          "schedule_rail_system": [
+            "rail_network",
+            "trains",
+            "jobs"
+          ],
+          "find": [
+            "rail_network",
+            "stops",
+            "jobs"
+          ],
+          "schedule": [
+            "graph",
+            "start",
+            "jobs"
+          ],
+          "jobs_from_path": [
+            "path"
+          ],
+          "path_from_schedule": [
+            "jobs",
+            "start"
+          ],
+          "find_perfect_circuit": [
+            "graph",
+            "start",
+            "jobs"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "tsp",
+        "functions": [
+          "brute_force",
+          "tsp_2023",
+          "tsp_branch_and_bound",
+          "tsp_greedy"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "tsp_branch_and_bound": [
+            "graph"
+          ],
+          "tsp_greedy": [
+            "graph"
+          ],
+          "brute_force": [
+            "graph"
+          ],
+          "tsp_2023": [
+            "graph"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      },
+      {
+        "package": "graph",
+        "module": "visuals",
+        "functions": [
+          "plot_2d",
+          "plot_3d",
+          "visualise"
+        ],
+        "classes": [],
+        "function_signatures": {
+          "visualise": [
+            "func"
+          ],
+          "plot_2d": [
+            "graph",
+            "nodes",
+            "edges"
+          ],
+          "plot_3d": [
+            "graph",
+            "nodes",
+            "edges",
+            "rotation",
+            "maintain_aspect_ratio"
+          ]
+        },
+        "description": "Discovered via AST scan"
+      }
+    ],
+    "cli_commands": [],
+    "import_strategy": {
+      "primary": "import",
+      "fallback": "blackbox",
+      "confidence": 0.9
+    },
+    "dependencies": {
+      "required": [
+        "numpy",
+        "scipy"
+      ],
+      "optional": [
+        "matplotlib"
+      ]
+    },
+    "risk_assessment": {
+      "import_feasibility": 0.8,
+      "intrusiveness_risk": "low",
+      "complexity": "medium"
+    }
+  },
+  "deepwiki_analysis": {
+    "repo_url": "https://github.com/root-11/graph-theory",
+    "repo_name": "graph-theory",
+    "content": "root-11/graph-theory\ngraph-theory\nA simple graph library\nRepository Not Indexed\nThis repository hasn't been indexed yet. Indexing allows you to explore code structure, find documentation, and understand dependencies.\nIndexing typically takes 2-10 minutes to complete after it starts indexing\nOnce indexed, you'll have full access to code exploration and search functionality",
+    "model": "gpt-4o-2024-08-06",
+    "source": "selenium",
+    "success": true
+  },
+  "deepwiki_options": {
+    "enabled": true,
+    "model": "gpt-4o-2024-08-06"
+  },
+  "risk": {
+    "import_feasibility": 0.8,
+    "intrusiveness_risk": "low",
+    "complexity": "medium"
+  }
+}

graph-theory/mcp_output/diff_report.md

@@ -0,0 +1,61 @@
+# Graph-Theory Project Difference Report
+
+**Repository:** graph-theory  
+**Project Type:** Python Library  
+**Date:** February 7, 2026  
+**Time:** 17:01:26  
+**Intrusiveness:** None  
+**Workflow Status:** Success  
+**Test Status:** Failed  
+
+## Project Overview
+
+The graph-theory project is a Python library designed to provide basic functionalities for graph-related computations and analyses. The library aims to serve as a foundational tool for developers and researchers working with graph data structures and algorithms.
+
+## Difference Analysis
+
+### New Files Added
+
+In this update, a total of 8 new files have been introduced to the repository. These files are expected to enhance the library's capabilities by adding new features or improving existing ones. However, no existing files were modified in this update.
+
+### Modified Files
+
+There were no modifications made to existing files in this update. This suggests that the new features or functionalities were implemented without altering the current codebase, maintaining backward compatibility.
+
+## Technical Analysis
+
+### New Features
+
+The addition of 8 new files indicates the introduction of new features or modules. However, without specific details on the content of these files, it is challenging to provide a comprehensive technical analysis. It is recommended to review the commit messages or documentation associated with these files for further insights.
+
+### Test Status
+
+The test status for this update is marked as "Failed." This indicates that the new additions or changes have introduced issues that need to be addressed. The failure in tests suggests potential bugs or incompatibilities in the new code.
+
+## Recommendations and Improvements
+
+1. **Review New Files:** Conduct a thorough review of the newly added files to understand their purpose and functionality. Ensure that they align with the project's goals and coding standards.
+
+2. **Debugging and Testing:** Investigate the cause of the test failures. This may involve debugging the new code, identifying the root cause of the issues, and implementing necessary fixes.
+
+3. **Enhance Test Coverage:** Consider expanding the test suite to cover the new functionalities introduced by the new files. This will help in identifying potential issues early and ensure the reliability of the library.
+
+4. **Documentation:** Update the project documentation to include information about the new features and how they can be utilized. This will aid users in understanding and effectively using the new functionalities.
+
+## Deployment Information
+
+Given the current test failures, it is not recommended to deploy this version of the library. Addressing the test issues should be prioritized before considering deployment to ensure a stable and reliable release.
+
+## Future Planning
+
+1. **Stability and Reliability:** Focus on resolving the current test failures to ensure the library's stability and reliability.
+
+2. **Feature Expansion:** Once the current issues are resolved, consider planning for future feature expansions based on user feedback and project goals.
+
+3. **Community Engagement:** Engage with the user community to gather feedback and suggestions for future improvements and features.
+
+4. **Versioning:** Upon successful resolution of the current issues, consider incrementing the library's version to reflect the new additions and improvements.
+
+## Conclusion
+
+The recent update to the graph-theory project introduces new functionalities through the addition of 8 new files. However, the current test failures highlight the need for further debugging and testing. By addressing these issues and enhancing documentation and test coverage, the project can continue to evolve and provide valuable tools for graph-related computations.

graph-theory/mcp_output/mcp_plugin/adapter.py

@@ -0,0 +1,102 @@
+import os
+import sys
+
+# Path settings
+source_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), "source")
+sys.path.insert(0, source_path)
+
+# Import statements
+try:
+    from examples.graphs import Graph
+    from graph.adjacency_matrix import AdjacencyMatrix
+    from graph.all_pairs_shortest_path import AllPairsShortestPath
+    from graph.assignment_problem import AssignmentProblem
+    from graph.base import BaseGraph
+    from graph.bfs import BFS
+    from graph.core import CoreGraph
+    from graph.critical_path import CriticalPath
+    from graph.cycle import CycleDetection
+    from graph.dag import DAG
+    from graph.degree_of_separation import DegreeOfSeparation
+    from graph.dfs import DFS
+    from graph.distance_map import DistanceMap
+    from graph.finite_state_machine import FiniteStateMachine
+    from graph.hash_methods import HashMethods
+    from graph.max_flow import MaxFlow
+    from graph.max_flow_min_cut import MaxFlowMinCut
+    from graph.maximum_flow_min_cut import MaximumFlowMinCut
+    from graph.min_cost_flow import MinCostFlow
+    from graph.minmax import MinMax
+    from graph.minsum import MinSum
+    from graph.partite import PartiteGraph
+    from graph.random import RandomGraph
+    from graph.shortest_path import ShortestPath
+    from graph.shortest_tree_all_pairs import ShortestTreeAllPairs
+    from graph.topological_sort import TopologicalSort
+    from graph.traffic_scheduling_problem import TrafficSchedulingProblem
+    from graph.transshipment_problem import TransshipmentProblem
+    from graph.tsp import TSP
+    from graph.visuals import GraphVisuals
+except ImportError as e:
+    print(f"Import failed: {e}. Ensure all modules are available in the source directory.")
+
+# Adapter class
+class Adapter:
+    """
+    Adapter class for the MCP plugin, providing access to various graph-related functionalities.
+    """
+
+    def __init__(self):
+        self.mode = "import"
+
+    # Example method for a class
+    def create_graph_instance(self):
+        """
+        Create an instance of the Graph class.
+
+        Returns:
+            dict: A dictionary containing the status and the Graph instance.
+        """
+        try:
+            graph_instance = Graph()
+            return {"status": "success", "instance": graph_instance}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+
+    # Example method for a function
+    def call_adjacency_matrix(self, *args, **kwargs):
+        """
+        Call the AdjacencyMatrix function with provided arguments.
+
+        Args:
+            *args: Positional arguments for the function.
+            **kwargs: Keyword arguments for the function.
+
+        Returns:
+            dict: A dictionary containing the status and the result of the function call.
+        """
+        try:
+            result = AdjacencyMatrix(*args, **kwargs)
+            return {"status": "success", "result": result}
+        except Exception as e:
+            return {"status": "error", "message": str(e)}
+
+    # Additional methods for other classes and functions can be added here following the same pattern
+
+    # Error handling and fallback
+    def handle_import_failure(self):
+        """
+        Handle import failures gracefully.
+
+        Returns:
+            dict: A dictionary containing the status and a fallback message.
+        """
+        return {"status": "error", "message": "Module import failed. Please check the source path and module availability."}
+
+# Example usage
+if __name__ == "__main__":
+    adapter = Adapter()
+    graph_result = adapter.create_graph_instance()
+    print(graph_result)
+    adjacency_result = adapter.call_adjacency_matrix()
+    print(adjacency_result)

graph-theory/mcp_output/mcp_plugin/main.py

@@ -0,0 +1,13 @@
+"""
+MCP Service Auto-Wrapper - Auto-generated
+"""
+from mcp_service import create_app
+
+def main():
+    """Main entry point"""
+    app = create_app()
+    return app
+
+if __name__ == "__main__":
+    app = main()
+    app.run()

graph-theory/mcp_output/mcp_plugin/mcp_service.py

@@ -0,0 +1,26 @@
+import os
+import sys
+
+source_path = os.path.join(os.path.dirname(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))), "source")
+if source_path not in sys.path:
+    sys.path.insert(0, source_path)
+
+from fastmcp import FastMCP
+
+# No imports available
+
+mcp = FastMCP("unknown_service")
+
+
+    @mcp.tool(name="core", description="Default core function")
+    def core(*args, **kwargs):
+        return {"success": False, "result": None, "error": "no_import_available"}
+
+
+
+def create_app():
+    """Create and return FastMCP application instance"""
+    return mcp
+
+if __name__ == "__main__":
+    mcp.run(transport="http", host="0.0.0.0", port=8000)

graph-theory/mcp_output/requirements.txt

@@ -0,0 +1,6 @@
+fastmcp
+fastapi
+uvicorn[standard]
+pydantic>=2.0.0
+numpy
+scipy

graph-theory/mcp_output/start_mcp.py

@@ -0,0 +1,30 @@
+
+"""
+MCP Service Startup Entry
+"""
+import sys
+import os
+
+project_root = os.path.dirname(os.path.abspath(__file__))
+mcp_plugin_dir = os.path.join(project_root, "mcp_plugin")
+if mcp_plugin_dir not in sys.path:
+    sys.path.insert(0, mcp_plugin_dir)
+
+from mcp_service import create_app
+
+def main():
+    """Start FastMCP service"""
+    app = create_app()
+    # Use environment variable to configure port, default 8000
+    port = int(os.environ.get("MCP_PORT", "8000"))
+    
+    # Choose transport mode based on environment variable
+    transport = os.environ.get("MCP_TRANSPORT", "stdio")
+    if transport == "http":
+        app.run(transport="http", host="0.0.0.0", port=port)
+    else:
+        # Default to STDIO mode
+        app.run()
+
+if __name__ == "__main__":
+    main()

graph-theory/mcp_output/workflow_summary.json

@@ -0,0 +1,196 @@
+{
+  "repository": {
+    "name": "graph-theory",
+    "url": "https://github.com/root-11/graph-theory",
+    "local_path": "/export/zxcpu1/shiweijie/code/ghh/Code2MCP/workspace/graph-theory",
+    "description": "Python library",
+    "features": "Basic functionality",
+    "tech_stack": "Python",
+    "stars": 0,
+    "forks": 0,
+    "language": "Python",
+    "last_updated": "",
+    "complexity": "medium",
+    "intrusiveness_risk": "low"
+  },
+  "execution": {
+    "start_time": 1770454771.3532846,
+    "end_time": 1770454831.8100812,
+    "duration": 60.4567985534668,
+    "status": "success",
+    "workflow_status": "success",
+    "nodes_executed": [
+      "download",
+      "analysis",
+      "env",
+      "generate",
+      "run",
+      "review",
+      "finalize"
+    ],
+    "total_files_processed": 3,
+    "environment_type": "unknown",
+    "llm_calls": 0,
+    "deepwiki_calls": 0
+  },
+  "tests": {
+    "original_project": {
+      "passed": false,
+      "details": {},
+      "test_coverage": "100%",
+      "execution_time": 0,
+      "test_files": []
+    },
+    "mcp_plugin": {
+      "passed": true,
+      "details": {},
+      "service_health": "healthy",
+      "startup_time": 0,
+      "transport_mode": "stdio",
+      "fastmcp_version": "unknown",
+      "mcp_version": "unknown"
+    }
+  },
+  "analysis": {
+    "structure": {
+      "packages": [
+        "source.examples",
+        "source.graph",
+        "source.tests"
+      ]
+    },
+    "dependencies": {
+      "has_environment_yml": false,
+      "has_requirements_txt": true,
+      "pyproject": false,
+      "setup_cfg": false,
+      "setup_py": true
+    },
+    "entry_points": {
+      "imports": [],
+      "cli": [],
+      "modules": []
+    },
+    "risk_assessment": {
+      "import_feasibility": 0.8,
+      "intrusiveness_risk": "low",
+      "complexity": "medium"
+    },
+    "deepwiki_analysis": {
+      "repo_url": "https://github.com/root-11/graph-theory",
+      "repo_name": "graph-theory",
+      "content": "root-11/graph-theory\ngraph-theory\nA simple graph library\nRepository Not Indexed\nThis repository hasn't been indexed yet. Indexing allows you to explore code structure, find documentation, and understand dependencies.\nIndexing typically takes 2-10 minutes to complete after it starts indexing\nOnce indexed, you'll have full access to code exploration and search functionality",
+      "model": "gpt-4o-2024-08-06",
+      "source": "selenium",
+      "success": true
+    },
+    "code_complexity": {
+      "cyclomatic_complexity": "medium",
+      "cognitive_complexity": "medium",
+      "maintainability_index": 75
+    },
+    "security_analysis": {
+      "vulnerabilities_found": 0,
+      "security_score": 85,
+      "recommendations": []
+    }
+  },
+  "plugin_generation": {
+    "files_created": [
+      "mcp_output/start_mcp.py",
+      "mcp_output/mcp_plugin/__init__.py",
+      "mcp_output/mcp_plugin/mcp_service.py",
+      "mcp_output/mcp_plugin/adapter.py",
+      "mcp_output/mcp_plugin/main.py",
+      "mcp_output/requirements.txt",
+      "mcp_output/README_MCP.md"
+    ],
+    "main_entry": "start_mcp.py",
+    "requirements": [
+      "fastmcp>=0.1.0",
+      "pydantic>=2.0.0"
+    ],
+    "readme_path": "/export/zxcpu1/shiweijie/code/ghh/Code2MCP/workspace/graph-theory/mcp_output/README_MCP.md",
+    "adapter_mode": "import",
+    "total_lines_of_code": 0,
+    "generated_files_size": 0,
+    "tool_endpoints": 0,
+    "supported_features": [
+      "Basic functionality"
+    ],
+    "generated_tools": [
+      "Basic tools",
+      "Health check tools",
+      "Version info tools"
+    ]
+  },
+  "code_review": {},
+  "errors": [],
+  "warnings": [],
+  "recommendations": [
+    "Improve test coverage by adding more unit tests for uncovered modules",
+    "optimize large test files like `tests/test_graph.py` to improve maintainability",
+    "ensure all dependencies are up-to-date and consider adding a `pyproject.toml` for better dependency management",
+    "enhance documentation in `README.md` to include detailed usage examples and API references",
+    "refactor large modules such as `graph/base.py` and `graph/traffic_scheduling_problem.py` for better readability and performance",
+    "implement continuous integration to automate testing and deployment processes",
+    "consider indexing the repository for better code exploration and search functionality",
+    "review and optimize the performance of critical functions identified in the analysis",
+    "ensure consistent coding standards across the project by using linters and formatters",
+    "evaluate the risk assessment and address any potential issues related to import feasibility and complexity."
+  ],
+  "performance_metrics": {
+    "memory_usage_mb": 0,
+    "cpu_usage_percent": 0,
+    "response_time_ms": 0,
+    "throughput_requests_per_second": 0
+  },
+  "deployment_info": {
+    "supported_platforms": [
+      "Linux",
+      "Windows",
+      "macOS"
+    ],
+    "python_versions": [
+      "3.8",
+      "3.9",
+      "3.10",
+      "3.11",
+      "3.12"
+    ],
+    "deployment_methods": [
+      "Docker",
+      "pip",
+      "conda"
+    ],
+    "monitoring_support": true,
+    "logging_configuration": "structured"
+  },
+  "execution_analysis": {
+    "success_factors": [
+      "Successful execution of all workflow nodes",
+      "No errors or warnings during execution"
+    ],
+    "failure_reasons": [],
+    "overall_assessment": "excellent",
+    "node_performance": {
+      "download_time": "Efficient, completed without delay",
+      "analysis_time": "Completed successfully, no issues reported",
+      "generation_time": "Efficient, all necessary files generated",
+      "test_time": "Original project tests failed, but MCP plugin tests passed"
+    },
+    "resource_usage": {
+      "memory_efficiency": "Memory usage not reported, assumed efficient due to lack of issues",
+      "cpu_efficiency": "CPU usage not reported, assumed efficient due to lack of issues",
+      "disk_usage": "Disk usage efficient, no excessive file sizes or unnecessary files"
+    }
+  },
+  "technical_quality": {
+    "code_quality_score": 85,
+    "architecture_score": 80,
+    "performance_score": 75,
+    "maintainability_score": 70,
+    "security_score": 85,
+    "scalability_score": 80
+  }
+}

graph-theory/source/.coveragerc

@@ -0,0 +1,4 @@
+[run]
+branch = True
+concurrency = multiprocessing
+omit = setup.py, package.py, examples.py

graph-theory/source/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2019 root-11
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

graph-theory/source/README.md

@@ -0,0 +1,144 @@
+# graph-theory
+![Build status](https://github.com/root-11/graph-theory/actions/workflows/python-test.yml/badge.svg)
+[![codecov](https://codecov.io/gh/root-11/graph-theory/branch/master/graph/badge.svg?token=hWbKhIXskp)](https://codecov.io/gh/root-11/graph-theory)
+[![Downloads](https://pepy.tech/badge/graph-theory)](https://pepy.tech/project/graph-theory)
+[![Downloads](https://pepy.tech/badge/graph-theory/month)](https://pepy.tech/project/graph-theory/month)
+[![PyPI version](https://badge.fury.io/py/graph-theory.svg)](https://badge.fury.io/py/graph-theory)
+
+
+A simple graph library...<br>
+*... A bit like networkx, just without the overhead...*<br> 
+*... similar to graph-tool, without the Python 2.7 legacy...*<br>
+*... with code that you can explain to your boss...*<br>
+
+Detailed tutorial evolving in the [examples section](https://github.com/root-11/graph-theory/blob/master/examples/readme.md).
+
+---------------------------
+Install:
+
+    pip install graph-theory
+
+Upgrade:
+
+    pip install graph-theory --upgrade --no-cache
+
+Testing:
+
+    pytest tests
+
+---------------------------
+Import:
+
+    import Graph
+    g = Graph()  
+
+    import Graph3d
+    g3d = Graph3D()
+
+---------------------------
+
+Modules:
+
+| module | description |
+|:---|:---|
+| `from graph import Graph, Graph3D` | Elementary methods (see basic methods below) for Graph and Graph3D.|
+| `from graph import ...` | All methods available on Graph (see table below) |
+| `from graph.assignment_problem import ...` | solvers for assignment problem, the Weapons-Target Assignment Problem, ... |
+| `from graph.hash import ...` | graph hash functions: graph hash, merkle tree, flow graph hash | 
+| `from graph.random import ...` | graph generators for random, 2D and 3D graphs. |
+| `from graph.transshipment_problem import ...` | solvers for the transshipment problem |
+| `from graph.traffic_scheduling_problem import ...` | solvers for the traffic jams (and slide puzzle) |
+| `from graph.visuals import ...` | methods for creating matplotlib plots |
+| `from graph.finite_state_machine import ...` | finite state machine |
+
+
+All module functions are available from Graph and Graph3D (where applicable).
+
+| Graph | Graph3D | methods                                          | returns                                                                                                                                                                                                               | example |
+|:---:|:---:|:-------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---|
+| + | + | `a in g`                                         | assert if g contains node a                                                                                                                                                                                           | |
+| + | + | `g.add_node(n, [obj])`                           | adds a node (with a pointer to object `obj` if given)                                                                                                                                                                 ||
+| + | + | `g.copy()`                                       | returns a shallow copy of `g`                                                                                                                                                                                         ||
+| + | + | `g.node(node1)`                                  | returns object attached to node 1                                                                                                                                                                                     ||
+| + | + | `g.del_node(node1)`                              | deletes node1 and all it's edges                                                                                                                                                                                      ||
+| + | + | `g.nodes()`                                      | returns a list of nodes                                                                                                                                                                                               ||
+| + | + | `len(g.nodes())`                                 | returns the number of nodes                                                                                                                                                                                           ||
+| + | + | `g.nodes(from_node=1)`                           | returns nodes with edges from node 1                                                                                                                                                                                  ||
+| + | + | `g.nodes(to_node=2)`                             | returns nodes with edges to node 2                                                                                                                                                                                    ||
+| + | + | `g.nodes(in_degree=2)`                           | returns nodes with 2 incoming edges                                                                                                                                                                                   ||
+| + | + | `g.nodes(out_degree=2)`                          | returns nodes with 2 outgoing edges                                                                                                                                                                                   ||
+| + | + | `g.add_edge(1,2,3)`                              | adds edge to g for vector `(1,2)` with value `3`                                                                                                                                                                      ||
+| + | + | `g.edge(1,2)`                                    | returns value of edge between nodes 1 and 2                                                                                                                                                                           ||
+| + | + | `g.edge(1,2,default=3)`                          | returns `default=3` if `edge(1,2)` doesn't exist. <br>similar to `d.get(key, 3)`                                                                                                                                      ||
+| + | + | `g.del_edge(1,2)`                                | removes edge between nodes 1 and 2                                                                                                                                                                                    ||
+| + | + | `g.edges()`                                      | returns a list of edges                                                                                                                                                                                               ||
+| + | + | `len(g.edges())`                                 | returns the number of edges                                                                                                                                                                                           ||
+| + | + | `g.edges(path=[path])`                           | returns a list of edges (along a path if given).                                                                                                                                                                      ||
+| + | + | `same_path(p1,p2)`                               | compares two paths to determine if they contain same sequences <br>ex.: `[1,2,3] == [2,3,1]`                                                                                                                          ||
+| + | + | `g.edges(from_node=1)`                           | returns edges outgoing from node 1                                                                                                                                                                                    ||
+| + | + | `g.edges(to_node=2)`                             | returns edges incoming to node 2                                                                                                                                                                                      ||
+| + | + | `g.from_dict(d)`                                 | updates the graph from a dictionary                                                                                                                                                                                   ||
+| + | + | `g.to_dict()`                                    | returns the graph as a dictionary                                                                                                                                                                                     ||
+| + | + | `g.from_list(L)`                                 | updates the graph from a list                                                                                                                                                                                         ||
+| + | + | `g.to_list()`                                    | return the graph as a list of edges                                                                                                                                                                                   ||
+| + | + | `g.shortest_path(start,end [, memoize, avoids])` | returns the distance and path for path with smallest edge sum <br> If `memoize=True`, sub results are cached for faster access if repeated calls.<br> If `avoids=set()`, then these nodes are not a part of the path. ||
+| + | + | `g.shortest_path_bidirectional(start,end)`       | returns distance and path for the path with smallest edge sum using bidrectional search.                                                                                                                              ||
+| + | + | `g.is_connected(start,end)`                      | determines if there is a path from start to end                                                                                                                                                                       ||
+| + | + | `g.breadth_first_search(start,end)`              | returns the number of edges and path with fewest edges                                                                                                                                                                ||
+| + | + | `g.breadth_first_walk(start,end)`                | returns a generator for a BFS walk                                                                                                                                                                                    ||
+| + | + | `g.degree_of_separation(n1,n2)`                  | returns the distance between two nodes using BFS                                                                                                                                                                      ||
+| + | + | `g.distance_map(starts,ends, reverse)`           | returns a dictionary with the distance from any start to any end (or reverse)                                                                                                                                         ||
+| + | + | `g.network_size(n1, degree_of_separation)`       | returns the nodes within the range given by `degree_of_separation`                                                                                                                                                    ||
+| + | + | `g.topological_sort(key)`                        | returns a generator that yields node in order from a non-cyclic graph.                                                                                                                                                ||
+| + | + | `g.critical_path()`                              | returns the distance of the critical path and a list of Tasks.                                                                                                                                                        | [Example](examples/solving%20search%20problems.ipynb) |
+| + | + | `g.critical_path_minimize_for_slack()`           | returns graph with artificial dependencies that minimises slack.                                                                                                                                                      | [Example](examples/solving%20search%20problems.ipynb)|
+| + | + | `g.phase_lines()`                                | returns a dictionary with the phase_lines for a non-cyclic graph.                                                                                                                                                     ||
+| + | + | `g.sources(n)`                                   | returns the source_tree of node `n`                                                                                                                                                                                   ||
+| + | + | `g.depth_first_search(start,end)`                | returns path using DFS and backtracking                                                                                                                                                                               ||
+| + | + | `g.depth_scan(start, criteria)`                  | returns set of nodes where criteria is True                                                                                                                                                                           ||
+| + | + | `g.distance_from_path(path)`                     | returns the distance for path.                                                                                                                                                                                        ||
+| + | + | `g.maximum_flow(source,sink)`                    | finds the maximum flow between a source and a sink                                                                                                                                                                    ||
+| + | + | `g.maximum_flow_min_cut(source,sink)`            | finds the maximum flow minimum cut between a source and a sink                                                                                                                                                        ||
+| + | + | `g.minimum_cost_flow(inventory, capacity)`       | finds the total cost and flows of the capacitated minimum cost flow.                                                                                                                                                  ||
+| + | + | `g.solve_tsp()`                                  | solves the traveling salesman problem for the graph.<br>Available methods: 'greedy' (default) and 'bnb                                                                                                                ||
+| + | + | `g.subgraph_from_nodes(nodes)`                   | returns the subgraph of `g` involving `nodes`                                                                                                                                                                         ||
+| + | + | `g.is_subgraph(g2)`                              | determines if graph `g2` is a subgraph in g                                                                                                                                                                           ||
+| + | + | `g.is_partite(n)`                                | determines if graph is n-partite                                                                                                                                                                                      ||
+| + | + | `g.has_cycles()`                                 | determines if there are any cycles in the graph                                                                                                                                                                       ||
+| + | + | `g.components()`                                 | returns set of nodes in each component in `g`                                                                                                                                                                         ||
+| + | + | `g.same_path(p1,p2)`                             | compares two paths, returns True if they're the same                                                                                                                                                                  ||
+| + | + | `g.adjacency_matrix()`                           | returns the adjacency matrix for the graph                                                                                                                                                                            ||
+| + | + | `g.all_pairs_shortest_paths()`                   | finds the shortest path between all nodes                                                                                                                                                                             ||
+| + | + | `g.minsum()`                                     | finds the node(s) with shortest total distance to all other nodes                                                                                                                                                     ||
+| + | + | `g.minmax()`                                     | finds the node(s) with shortest maximum distance to all other nodes                                                                                                                                                   ||
+| + | + | `g.shortest_tree_all_pairs()`                    | finds the shortest tree for all pairs                                                                                                                                                                                 ||
+| + | + | `g.has_path(p)`                                  | asserts whether a path `p` exists in g                                                                                                                                                                                ||
+| + | + | `g.all_simple_paths(start,end)`                  | finds all simple paths between 2 nodes                                                                                                                                                                                ||
+| + | + | `g.all_paths(start,end)`                         | finds all combinations of paths between 2 nodes                                                                                                                                                                       ||
+| - | + | `g3d.distance(n1,n2)`                            | returns the spatial distance between `n1` and `n2`                                                                                                                                                                    ||
+| - | + | `g3d.n_nearest_neighbour(n1, [n])`               | returns the `n` nearest neighbours to node `n1`                                                                                                                                                                       ||
+| - | + | `g3d.plot()`                                     | returns matplotlib plot of the graph.                                                                                                                                                                                 ||
+
+
+## FAQ
+
+| want to... | doesn't work... | do instead... | ...but why? |
+|:---|:---|:---|:---|
+| have multiple edges between two nodes | `Graph(from_list=[(1,2,3), (1,2,4)]` | Add dummy nodes<br>`[(1,a,3), (a,2,0),`<br>` (1,b,4),(b,2,0)]` | Explicit is better than implicit. |
+| multiple values on an edge | `g.add_edge(1,2,{'a':3, 'b':4})` | Have two graphs<br>`g_a.add_edge(1,2,3)`<br>`g_b.add_edge(1,2,4)` | Most graph algorithms don't work with multiple values |
+|do repeated calls to shortest path|`g.shortest_path(a,b)` is slow|Use `g.shortest_path(a,b,memoize=True)` instead|memoize uses bidirectional search and caches sub-results along the shortest path for future retrievals|
+
+## Credits:
+
+- Arturo Soucase for packaging and testing. 
+- Peter Norvig for inspiration on TSP from [pytudes](https://github.com/norvig/pytudes/blob/master/ipynb/TSP.ipynb).
+- Harry Darby for the mountain river map.
+- Kyle Downey for depth_scan algorithm.
+- Ross Blandford for munich firebrigade centre -, traffic jam - and slide puzzle - test cases.
+- Avi Kelman for type-tolerant search, and a number of micro optimizations.
+- Joshua Crestone for all simple paths test.
+- CodeMartyLikeYou for detecting a bug in `@memoize` 
+- Tom Carroll for detecting the bug in del_edge and inspiration for topological sort.
+- Sappique for discovering bugs in `__eq__`, `copy` and `has_cycles`.
+- joshinils for discovering bug where `graph.edges(from_node=0)` was interpreted as `False`.
+

graph-theory/source/__init__.py

@@ -0,0 +1,4 @@
+# -*- coding: utf-8 -*-
+"""
+graph-theory Project Package Initialization File
+"""

graph-theory/source/datasets/readme.md

@@ -0,0 +1,3 @@
+# README
+This folder is listed in .gitignore so that developers can have confidential datasets withouth checking them in.
+

graph-theory/source/examples/basic graph theory.ipynb

@@ -0,0 +1,941 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "pycharm": {
+     "name": "#%% md\n"
+    }
+   },
+   "source": [
+    "# Introduction to Graph-theory\n",
+    "\n",
+    "[Graph-theory](https://en.wikipedia.org/wiki/Graph_theory) is the study of graphs,\n",
+    "which are mathematical structures used to model pairwise relations between objects.\n",
+    "\n",
+    "Graphs are among the most ubiquitous models of both natural and human-made structures.\n",
+    "They can model many types of relations and process dynamics in physical, biological\n",
+    "and social systems. In computer science, they can represent networks of communication,\n",
+    "data organization, computational devices, the flow of computation, etc.\n",
+    "Graphs are one of the principal objects of study in\n",
+    "[discrete mathematics](https://en.wikipedia.org/wiki/Discrete_mathematics).\n",
+    "\n",
+    "![6 nodes](images/6nodes.png)\n",
+    "\n",
+    "| alias | name used in<br>Graph-theory | description | syntax |\n",
+    "|---|:---:|---|---|\n",
+    "|node, vertice, point| **node** | an intersection of edges |  `g.add_node('x')` |\n",
+    "| edge, line, link| **edge** | the line that connects intersections  | `g.add_edge('a','b')`|\n",
+    "| the weight, cost or value of an edge | **value** | numeric value of an edge  | `g.add_edge('a','b',value=4)`|\n",
+    "|in-degree | **in_degree**| the number of incoming edges | `g.in_degree('a')` |\n",
+    "|out-degree| **out_degree**| the number of outgoing edges| `g.out_degree('b')` |\n",
+    "|path| **path**| an ordered collection of nodes | (a list of nodes) |\n",
+    "|distance, length, costs| **---**  | the sum of values of a set of edges | (number) |\n",
+    "| subgraph | **subgraph**| the nodes and edges of *g'* exists in *g* ||\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To add nodes the syntax is simple"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Graph(1 nodes, 0 edges)\n"
+     ]
+    }
+   ],
+   "source": [
+    "from graph import Graph\n",
+    "g = Graph()\n",
+    "g.add_node('C')\n",
+    "print(g)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To associate the node with an object, you can use the `obj` keyword like this:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "g.add_node('C', obj={'monty':'python'})"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This save you from managing the objects externally and permits algorithms to use the object directly.\n",
+    "\n",
+    "To retrieve the object use:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'monty': 'python'}"
+      ]
+     },
+     "execution_count": 3,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "g.node('C')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And to delete the node use:\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "g.del_node('C')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To add edges the syntax is equally simple:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {
+    "jupyter": {
+     "outputs_hidden": false
+    },
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Graph(2 nodes, 1 edges)\n"
+     ]
+    }
+   ],
+   "source": [
+    "from graph import Graph\n",
+    "g = Graph()\n",
+    "g.add_edge('A', 'B', value=4)\n",
+    "print(g)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To get all edges use:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {
+    "jupyter": {
+     "outputs_hidden": false
+    },
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[('A', 'B', 4)]"
+      ]
+     },
+     "execution_count": 6,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "g.edges()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Or to view a specific edge `value`, use:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "4"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "g.edge('A', 'B')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "As you see, `g.edges()` returns a list of immutable tuples with `(from, to, value)`.  \n",
+    "\n",
+    "Note that it isn't necessary to add the nodes first. When you use `g.add_edge(...)` the library will detect that the nodes haven't been created and add them quietly."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "pycharm": {
+     "name": "#%% md\n"
+    }
+   },
+   "source": [
+    "If you need to update the value on the edge just use `g.add_edge('A','B', value=10)` again.\n",
+    "The edge works like a dictionary, where the pair of node `'A'` and `'B'` is the key where the `10` is the value.\n",
+    "\n",
+    "In some cases it is not required for the graph to be directed. Mathematicians call this undirected.\n",
+    "In Python a principal philosophy is that *explicit is better than implicit*, so in graph-theory *undirected* is interpreted as bidirectional. To make this explicit when adding edges, either add an edge for both directions, or use the keyword `bidirectional` which is a helper for doing these to step in one step:\n",
+    "\n",
+    "|this... | ...is the same as this|\n",
+    "|---|---|\n",
+    "|`g.add_edge('A','B')`<br>`g.add_edge('B','A')`|`g.add_edge('A','B', bidirectional=True)`|\n",
+    "\n",
+    "In other cases multiple edges between nodes are required. Graph-theory allows this using\n",
+    "dummy nodes. Here's an example:"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The graph will store the in- and -out-degree of every node when the edges are added and removed, so the in_degree and out_degree is available immediately e.g. ($O(1)$ [computational complexity](https://wiki.python.org/moin/TimeComplexity)). Here's an example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "0"
+      ]
+     },
+     "execution_count": 8,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "g.in_degree('A')"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "1"
+      ]
+     },
+     "execution_count": 9,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "g.out_degree('A')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Finally, to delete an edge, simply use:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "g.del_edge('A','B')"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To replicate the graph in the image in the begging of this section, we will use a helper from the graphs initialization methods `from_list`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "g = Graph(from_list=[(1,2),(2,3),(3,4),(4,5),(5,6),(5,1),(2,5)])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "As we can't create a bidirectional graph implicitly, we can do so explicitly:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "g.from_list([(end,start,value) for start,end,value in g.edges()])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "I chose this example deliberately as it illustrates the ability to update the graph from a list of nodes, even if that list comes from the graph itself. I also wanted to show the idiomatic use of list comprehensions for reading `start`, `end`, `value` from the method `g.edges()`.\n",
+    "\n",
+    "The reverse operation `to_list` also exists:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[(1, 2, 1),\n",
+       " (1, 5, 1),\n",
+       " (2, 3, 1),\n",
+       " (2, 5, 1),\n",
+       " (2, 1, 1),\n",
+       " (3, 4, 1),\n",
+       " (3, 2, 1),\n",
+       " (4, 5, 1),\n",
+       " (4, 3, 1),\n",
+       " (5, 6, 1),\n",
+       " (5, 1, 1),\n",
+       " (5, 2, 1),\n",
+       " (5, 4, 1),\n",
+       " (6, 5, 1),\n",
+       " (1,),\n",
+       " (2,),\n",
+       " (3,),\n",
+       " (4,),\n",
+       " (5,),\n",
+       " (6,)]"
+      ]
+     },
+     "execution_count": 13,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "g.to_list()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The method lists all edges first, followed by all nodes"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If, you have the need to lookup particular edges or values directly `to_dict` may be more convenient:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{1: {2: 1, 5: 1},\n",
+       " 2: {3: 1, 5: 1, 1: 1},\n",
+       " 3: {4: 1, 2: 1},\n",
+       " 4: {5: 1, 3: 1},\n",
+       " 5: {6: 1, 1: 1, 2: 1, 4: 1},\n",
+       " 6: {5: 1}}"
+      ]
+     },
+     "execution_count": 14,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "g.to_dict()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "`to_dict`s inverse operation is `from_dict`, which behaves in the exact same way as `to_list`/`from_list`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "g2 = Graph(from_dict=g.to_dict())"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here we created `g2` from `g`."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{1: {2: 1, 5: 1},\n",
+       " 2: {3: 1, 5: 1, 1: 1},\n",
+       " 5: {6: 1, 1: 1, 2: 1, 4: 1},\n",
+       " 3: {4: 1, 2: 1},\n",
+       " 4: {5: 1, 3: 1},\n",
+       " 6: {5: 1}}"
+      ]
+     },
+     "execution_count": 16,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "g2.to_dict()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This may seem as a long way to copy when the libray already has the method `g.copy()`. The difference between the two methods, though, is that `g2=Graph(from_list(g.to_list()))` does not copy the reference to objects that you may have set using `g.add_node('a', obj='!!!')`. `g.copy()` will copy there reference too."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "metadata": {
+    "jupyter": {
+     "outputs_hidden": false
+    },
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "from graph import Graph\n",
+    "\n",
+    "g = Graph()\n",
+    "g.add_edge('A', 'B', value=4)  # a direct edge\n",
+    "g.add_edge('A', 'ab', value=2)  # dummy edge from A to dummy node ab\n",
+    "g.add_edge('ab', 'B', value=2)   # dummy edge from dummy node ab to B"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "pycharm": {
+     "name": "#%% md\n"
+    }
+   },
+   "source": [
+    "Creating these dummy nodes by hand isn't very effective, so if you have a list of edges like in the example below it is good to know that nodes can be any hashable object, e.g. tuples, strings, numbers, ..."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 18,
+   "metadata": {
+    "jupyter": {
+     "outputs_hidden": false
+    },
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "('A', ('A', 'B', 4), 4)\n",
+      "('A', ('A', 'B', 3), 3)\n",
+      "('A', ('A', 'B', 2), 2)\n",
+      "(('A', 'B', 4), 'B', 0)\n",
+      "(('A', 'B', 3), 'B', 0)\n",
+      "(('A', 'B', 2), 'B', 0)\n"
+     ]
+    }
+   ],
+   "source": [
+    "L = [('A','B',4), ('A','B',3), ('A','B',2)]\n",
+    "g = Graph()\n",
+    "for edge in L:\n",
+    "        start,end,value = edge  # using the edge tuple as dummy node.\n",
+    "        g.add_edge(start, edge, value) # adding the value on the way to the dummy node.\n",
+    "        g.add_edge(edge, end, 0)  # adding zero as the value has already been added.\n",
+    "\n",
+    "for edge in g.edges():\n",
+    "    print(edge)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "pycharm": {
+     "name": "#%% md\n"
+    }
+   },
+   "source": [
+    "The benefit of doing this is that most algorithms are simpler to implement (and understand!) when dummy nodes are explicit. As an outset you will always know your list of \"real\" nodes and can hence exclude dummy nodes when reading through the list of nodes. It would for example be silly to search for a dummy node when looking for the shortest path between two \"real\" nodes, as it is a pragmatic assumption that the algorithm will only have to search for the shortest path between two meaningful points."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "pycharm": {
+     "name": "#%% md\n"
+    }
+   },
+   "source": [
+    "### Inspecting the source code\n",
+    "\n",
+    "Since we are at this, you can count on all algorithms being available directly on the `Graph` class,\n",
+    "so that, for example the shortest path algorithm is available as:\n",
+    "\n",
+    "```\n",
+    "g.shortest_path('A','B')\n",
+    "```\n",
+    "\n",
+    "All the documentation is also available using the built-in help menu:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 19,
+   "metadata": {
+    "jupyter": {
+     "outputs_hidden": false
+    },
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Help on function shortest_path in module graph:\n",
+      "\n",
+      "shortest_path(self, start, end, memoize=False, avoids=None)\n",
+      "    :param start: start node\n",
+      "    :param end: end node\n",
+      "    :param memoize: boolean (stores paths in a cache for faster repeated lookup)\n",
+      "    :param avoids: optional. A frozen set of nodes that cannot be on the path.\n",
+      "    :return: distance, path as list\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "help(Graph.shortest_path)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "If you want a more detail description of what is going on, it is often helpful to directly to the specific function."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "import inspect"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 21,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "    def shortest_path(self, start, end, memoize=False, avoids=None):\n",
+      "        \"\"\"\n",
+      "        :param start: start node\n",
+      "        :param end: end node\n",
+      "        :param memoize: boolean (stores paths in a cache for faster repeated lookup)\n",
+      "        :param avoids: optional. A frozen set of nodes that cannot be on the path.\n",
+      "        :return: distance, path as list\n",
+      "        \"\"\"\n",
+      "        if not memoize:\n",
+      "            return shortest_path(graph=self, start=start, end=end, avoids=avoids)\n",
+      "\n",
+      "        if self._cache is None:\n",
+      "            self._cache = ShortestPathCache(graph=self)\n",
+      "        return self._cache.shortest_path(start, end, avoids=avoids)\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(inspect.getsource(Graph.shortest_path))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Here you see that Graph wraps the function `shortest_path` and, should you choose to use the keyword `memoize=True` that it uses the class `ShortestPathCache`.\n",
+    "\n",
+    "These can be inspected again in the same way:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 22,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "def shortest_path(graph, start, end, avoids=None):\n",
+      "    \"\"\" single source shortest path algorithm.\n",
+      "    :param graph: class Graph\n",
+      "    :param start: start node\n",
+      "    :param end: end node\n",
+      "    :param avoids: optional set,frozenset or list of nodes that cannot be a part of the path.\n",
+      "    :return distance, path (as list),\n",
+      "            returns float('inf'), [] if no path exists.\n",
+      "    \"\"\"\n",
+      "    if not isinstance(graph, (BasicGraph, Graph, Graph3D)):\n",
+      "        raise TypeError(f\"Expected BasicGraph, Graph or Graph3D, not {type(graph)}\")\n",
+      "    if start not in graph:\n",
+      "        raise ValueError(f\"{start} not in graph\")\n",
+      "    if end not in graph:\n",
+      "        raise ValueError(f\"{end} not in graph\")\n",
+      "    if avoids is None:\n",
+      "        visited = set()\n",
+      "    elif not isinstance(avoids, (frozenset, set, list)):\n",
+      "        raise TypeError(f\"Expect obstacles as set or frozenset, not {type(avoids)}\")\n",
+      "    else:\n",
+      "        visited = set(avoids)\n",
+      "\n",
+      "    q, minimums = [(0, 0, start, ())], {start: 0}\n",
+      "    i = 1\n",
+      "    while q:\n",
+      "        (cost, _, v1, path) = heappop(q)\n",
+      "        if v1 not in visited:\n",
+      "            visited.add(v1)\n",
+      "            path = (v1, path)\n",
+      "\n",
+      "            if v1 == end:  # exit criteria.\n",
+      "                L = []\n",
+      "                while path:\n",
+      "                    v, path = path[0], path[1]\n",
+      "                    L.append(v)\n",
+      "                L.reverse()\n",
+      "                return cost, L\n",
+      "\n",
+      "            for _, v2, dist in graph.edges(from_node=v1):\n",
+      "                if v2 in visited:\n",
+      "                    continue\n",
+      "                prev = minimums.get(v2, None)\n",
+      "                next_node = cost + dist\n",
+      "                if prev is None or next_node < prev:\n",
+      "                    minimums[v2] = next_node\n",
+      "                    heappush(q, (next_node, i, v2, path))\n",
+      "                    i += 1\n",
+      "    return float(\"inf\"), []\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "from graph import shortest_path  # getting the function behind Graph.shortest_path\n",
+    "print(inspect.getsource(shortest_path))  # viewing the code"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The code is very well annotated, so if the code doesn't explain itself, feel free to ask for a more elaborate example on the [github repo](https://github.com/root-11/graph-theory/issues).\n",
+    "\n",
+    "Graph-theory tries to be transparent about everything it does. As the readme on the frontpage says: \n",
+    "\n",
+    "> with code you can explain to your boss"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Graphs ready for usage"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To ease the learning curve, I've added a collection of graphs that are ready for import.\n",
+    "Here's one that should be familiar to most Europeans:\n",
+    "\n",
+    "![london underground from https://upload.wikimedia.org/wikipedia/commons/thumb/e/e1/London_Underground_Overground_DLR_Crossrail_map_zone.svg/2500px-London_Underground_Overground_DLR_Crossrail_map_zone.svg.png](images/2500pxLondon_Underground_Overground.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 23,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from graphs import london_underground"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 24,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Graph(302 nodes, 698 edges)\n"
+     ]
+    }
+   ],
+   "source": [
+    "g = london_underground()\n",
+    "print(g)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Each node in the graph is the latitude, longitude and station name"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 25,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "(51.5226, -0.1571, 'Baker Street')"
+      ]
+     },
+     "execution_count": 25,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "g.node(11)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 26,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "(51.5225, -0.1631, 'Marylebone')\n",
+      "(51.5234, -0.1466, \"Regent's Park\")\n",
+      "(51.5203, -0.17, 'Edgware Road (C)')\n",
+      "(51.5238, -0.1439, 'Great Portland Street')\n",
+      "(51.5142, -0.1494, 'Bond Street')\n",
+      "(51.5347, -0.174, \"St. John's Wood\")\n",
+      "(51.5472, -0.1803, 'Finchley Road')\n"
+     ]
+    }
+   ],
+   "source": [
+    "for station_nr in g.nodes(to_node=11):\n",
+    "    print(g.node(station_nr))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Let's make a map"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 27,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[(-0.1571, 51.5226), (-0.1631, 51.5225), (-0.1466, 51.5234)]"
+      ]
+     },
+     "execution_count": 27,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "stations = {station: g.node(station) for station in g.nodes()}\n",
+    "london_map = Graph()\n",
+    "for start,end,distance in g.edges():\n",
+    "    lat1,lon1,name1 = stations[start]\n",
+    "    lat2,lon2,name2 = stations[end]\n",
+    "    london_map.add_edge((lon1,lat1), (lon2,lat2))\n",
+    "\n",
+    "london_map.nodes()[:3]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 28,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from graph.visuals import plot_2d"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 29,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "image/png": "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",
+      "text/plain": [
+       "<Figure size 640x480 with 1 Axes>"
+      ]
+     },
+     "metadata": {},
+     "output_type": "display_data"
+    }
+   ],
+   "source": [
+    "plot = plot_2d(london_map)\n",
+    "plot.show()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Not exactly what you expected? Well there's a reason why the London overground map is famous for its readability in comparison to raw latitudes and longitudes."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

graph-theory/source/examples/comparing graphs.ipynb

@@ -0,0 +1,32 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {},
+   "outputs": [],
+   "source": []
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.8.5"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

graph-theory/source/examples/graphs as finite state machines.ipynb

@@ -0,0 +1,848 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "collapsed": true
+   },
+   "source": [
+    "# Finite State Machines \n",
+    "\n",
+    "Overview\n",
+    "\n",
+    "1. Fundamentals\n",
+    "2. Turnstile\n",
+    "3. Traffic Jam\n",
+    "4. Sudoku\n",
+    "\n",
+    "But first we must be ready:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "Note: you may need to restart the kernel to use updated packages.\n"
+     ]
+    },
+    {
+     "name": "stderr",
+     "output_type": "stream",
+     "text": [
+      "\n",
+      "[notice] A new release of pip available: 22.2.2 -> 23.1.2\n",
+      "[notice] To update, run: python.exe -m pip install --upgrade pip\n"
+     ]
+    }
+   ],
+   "source": [
+    "import sys\n",
+    "assert (sys.version_info.major, sys.version_info.minor) >= (3,7)\n",
+    "%pip install graph-theory --upgrade --no-cache -q\n",
+    "from graph import Graph"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Fundamentals\n",
+    "\n",
+    "Nomenclature\n",
+    "\n",
+    "- A finite state machine is a mathematical model of computation. \n",
+    "- The model is in exactly one state at any time.\n",
+    "- The model can change from one state to another using predetermined paths.\n",
+    "- All possible states is called the \"solution landscape\"\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Turnstile\n",
+    "\n",
+    " ![turnstile machine](images/Torniqueterevolution.jpg) ![turnstile](images/turnstile.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from graph.finite_state_machine import FiniteStateMachine\n",
+    "\n",
+    "locked, unlocked = 'locked', 'unlocked'  # states\n",
+    "push, coin = 'push', 'coin'  # actions\n",
+    "\n",
+    "fsm = FiniteStateMachine()\n",
+    "fsm.add_transition(locked, coin, unlocked)  # turnstile is locked. Put in coin to unlock.\n",
+    "fsm.add_transition(unlocked, push, locked)  # turnstile is unlocked. Push the rotor to lock.\n",
+    "fsm.add_transition(locked, push, locked)  # turnstile is locked. Pushing does not unlock.\n",
+    "fsm.add_transition(unlocked, coin, unlocked)  # turnstile is unlocked. Adding more coins does not change state.\n",
+    "\n",
+    "fsm.set_initial_state(locked)  # set initial state."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'coin', 'push'}"
+      ]
+     },
+     "execution_count": 4,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# check options: pay and go\n",
+    "set(fsm.options())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 5,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "fsm.current_state == locked"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# now insert coin:\n",
+    "fsm.next(action=coin)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{'coin', 'push'}"
+      ]
+     },
+     "execution_count": 7,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# check options:\n",
+    "set(fsm.options())"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 8,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "fsm.current_state == unlocked"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "True"
+      ]
+     },
+     "execution_count": 9,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "# ok it's unlocked - so we push:\n",
+    "fsm.next(action=push)\n",
+    "# and check if it locks behind us:\n",
+    "fsm.current_state == locked"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Traffic Jam\n",
+    "\n",
+    "As finite state machines can be view as a model of *a valid state*, we can use to verify solutions to optimization problems.\n",
+    "\n",
+    "In the example below we have a small intersection like, where all the `red`s need to pass all the `blue`s. \n",
+    "\n",
+    "The order could matter, but we ignore that for now.\n",
+    "\n",
+    "![3-3 traffic jam](images/3-3-cart-traffic-jam_initial.png)\n",
+    "\n",
+    "(initial state)\n",
+    "\n",
+    "The solution we would like to see looks like this:\n",
+    "\n",
+    "![3-3 traffic jan final](images/3-3-cart-traffic-jam.png)\n",
+    "\n",
+    "(final state)\n",
+    "\n",
+    "And here's the solution that swaps all the blue and red tiles in fewest moves:\n",
+    "\n",
+    "![3-3 traffic jam solution](images/traffic_bi_directional.gif)\n",
+    "\n",
+    "Q: How did I get to that?\n",
+    "\n",
+    "A: 3 steps:\n",
+    "\n",
+    "1. Define the system as a FSM using a \"map\" of options.\n",
+    "2. Set the `initial state`\n",
+    "3. Search through the solution landscape until the `active state` resembles the `final state`.\n",
+    "\n",
+    "\n",
+    "We will now solve the same problem using a just a tiny subset.\n",
+    "\n",
+    "Let's start with the map:\n",
+    "\n",
+    "![tjs-map](images/tjs-map.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "g = Graph()\n",
+    "edges = [(1,2),(2,3),(2,4)]\n",
+    "for edge in edges:\n",
+    "    g.add_edge(*edge, bidirectional=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Next I add the tiles to represent the initial state and the final state:\n",
+    "\n",
+    "![tjs with pug](images/tjs-map-loads.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "loads = [\n",
+    "    {'id':'red', 'start': 1, 'ends': 3}, \n",
+    "    {'id': 'blue', 'start': 3, 'ends': 1}\n",
+    "]"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from graph.traffic_scheduling_problem import jam_solver"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "queue exhausted\n"
+     ]
+    }
+   ],
+   "source": [
+    "solution = jam_solver(g,loads)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[{'red': (1, 2)},\n",
+       " {'red': (2, 4), 'blue': (3, 2)},\n",
+       " {'blue': (2, 1), 'red': (4, 2)},\n",
+       " {'red': (2, 3)}]"
+      ]
+     },
+     "execution_count": 14,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "solution"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "red moves from 1 to 2\n",
+      "red moves from 2 to 4\n",
+      "blue moves from 3 to 2\n",
+      "blue moves from 2 to 1\n",
+      "red moves from 4 to 2\n",
+      "red moves from 2 to 3\n"
+     ]
+    }
+   ],
+   "source": [
+    "# in plain english:\n",
+    "for move in solution:\n",
+    "    for color,(start,end) in move.items():\n",
+    "        print(f\"{color} moves from {start} to {end}\")"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "So what kind of `finite state machine` is the traffic jam solver using?\n",
+    "\n",
+    "Each state is captured on a graph which represents a `tree of options`. As there are a finite number of options to for changing the finite state machine from it's current state to the next state, we can capture the change as branches our `tree of options`. Every time our \"search\" generates a novel branch, we add that to the tree. The unexplored options then become our \"frontier\" from which we search further.\n",
+    "\n",
+    "![tjs](images/3-3-tree-of-states.png)\n",
+    "\n",
+    "We can make a deep-copy of our state machine, as the tree above illustrates, but will quickly consume a terrible amount of memory, \n",
+    "\n",
+    "To capture each `state` of the `finite state machine` we only need to look at the position of loads. Here is an example:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 16,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "state_0 = ((1, 'red'), (2, None), (3, 'blue'), (4, None))\n",
+    "state_1 = ((1, None), (2, 'red'), (3, 'blue'), (4, None))\n",
+    "state_2 = ((1, 'red'), (2, 'blue'), (3, None), (4, None))\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can now put these states into our `tree of options` as a graph:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 17,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "\n",
+    "fsm_graph = Graph()\n",
+    "fsm_graph.add_edge(state_0, state_1)  # there is a path from state_0 to state_1\n",
+    "fsm_graph.add_edge(state_0, state_2)  # there is a path from state_0 to state_2"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The search now becomes:\n",
+    "\n",
+    "1. \"make a change\", \n",
+    "2. check if it exists in the graph (and add it to the graph if it is novel). \n",
+    "\n",
+    "However the state definition contains a lot of `None`s that don't really add much.\n",
+    "\n",
+    "Suggestion: Let's just drop all the `None`s that information.\n",
+    "\n",
+    "New graph:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 18,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "state_0 = ((1, 'red'), (3, 'blue'))\n",
+    "state_1 = ((2, 'red'), (3, 'blue'))\n",
+    "state_2 = ((1, 'red'), (2, 'blue'))\n",
+    "\n",
+    "fsm_graph = Graph()\n",
+    "fsm_graph.add_edge(state_0, state_1)\n",
+    "fsm_graph.add_edge(state_0, state_2)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "That's nicer to read.\n",
+    "\n",
+    "We can now make a solver that identifies a path from the `initial state` to the `final state`, simply by searching along the frontier from the `initial state`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 19,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "# we need the \"map\" from earlier:\n",
+    "the_map = Graph()\n",
+    "edges = [(1,2),(2,3),(2,4)]\n",
+    "for edge in edges:\n",
+    "    the_map.add_edge(*edge, bidirectional=True)\n",
+    "\n",
+    "# we need the \"frontier\"\n",
+    "job_queue = [state_0, state_1, state_2]  # (you really only need state_0)\n",
+    "\n",
+    "# we need a \"final state\"\n",
+    "final_state = tuple(sorted([(3,'red'), (1,'blue')]))\n",
+    "\n",
+    "# we need a search\n",
+    "while job_queue:\n",
+    "    state = job_queue.pop()\n",
+    "    occupied = {position for position,item in state}\n",
+    "    for position, item in state:  # 'red' on position 2.\n",
+    "        for option in the_map.nodes(from_node=position):  # positions {1,4}\n",
+    "            if option in occupied:\n",
+    "                continue  # skip it.\n",
+    "            \n",
+    "            new_state = tuple(sorted([(option, item)] + [(o,i) for o,i in state if i != item]))\n",
+    "            \n",
+    "            if new_state in fsm_graph:\n",
+    "                continue  # we've already seen it.\n",
+    "            \n",
+    "            # we add the new state to be explored.\n",
+    "            fsm_graph.add_edge(state, new_state)\n",
+    "            job_queue.append(new_state)\n",
+    "\n",
+    "            if new_state == final_state:\n",
+    "                break"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "As the solver has made the tree of options of the finite state diagram we can have a quick look:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 20,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "[((1, 'red'), (3, 'blue')),\n",
+       " ((2, 'red'), (3, 'blue')),\n",
+       " ((1, 'red'), (2, 'blue')),\n",
+       " ((1, 'red'), (4, 'blue')),\n",
+       " ((2, 'red'), (4, 'blue')),\n",
+       " ((3, 'red'), (4, 'blue')),\n",
+       " ((2, 'blue'), (3, 'red')),\n",
+       " ((1, 'blue'), (3, 'red')),\n",
+       " ((1, 'blue'), (2, 'red')),\n",
+       " ((1, 'blue'), (4, 'red')),\n",
+       " ((2, 'blue'), (4, 'red')),\n",
+       " ((3, 'blue'), (4, 'red'))]"
+      ]
+     },
+     "execution_count": 20,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "fsm_graph.nodes()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To find the fewest moves to resolve the traffic jam, we can just ask the finite state diagram for the shortest path from the `initial state` to the `final state`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 21,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "(6,\n",
+       " [((1, 'red'), (3, 'blue')),\n",
+       "  ((1, 'red'), (2, 'blue')),\n",
+       "  ((1, 'red'), (4, 'blue')),\n",
+       "  ((2, 'red'), (4, 'blue')),\n",
+       "  ((3, 'red'), (4, 'blue')),\n",
+       "  ((2, 'blue'), (3, 'red')),\n",
+       "  ((1, 'blue'), (3, 'red'))])"
+      ]
+     },
+     "execution_count": 21,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "fsm_graph.shortest_path(state_0, final_state)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And there you have it! The solution from earlier:\n",
+    "\n",
+    "```\n",
+    "red moves from 1 to 2\n",
+    "red moves from 2 to 4\n",
+    "blue moves from 3 to 2\n",
+    "blue moves from 2 to 1\n",
+    "red moves from 4 to 2\n",
+    "red moves from 2 to 3\n",
+    "```\n",
+    "\n",
+    "and the solution above shows, state by state what has changed. \n",
+    "\n",
+    "Note that the two valid solutions interchangeable. "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Sudoku\n",
+    "\n",
+    "Solving a sudoku is no different can be done in a similar way, but our search can become a lot more efficient if we introduce the ideas of a wave collapse function.\n",
+    "\n",
+    "Q: A what-collapse?\n",
+    "\n",
+    "A: A wave collapse function. \n",
+    "\n",
+    "Q: ???\n",
+    "\n",
+    "A: Imagine you're surfing on a wave from an `initial state` over undefined state (US) space. As the wave rolls over the undefined space (US), it imposes the most probably outcome onto the undefined space. Each insertion causes the options of the neighbouring spaces to collapse from all possible options to very few plausible options. [More about wave collapse functions](https://github.com/mxgmn/WaveFunctionCollapse)\n",
+    "\n",
+    "![sudoku](images/sudoku-wave-collapse-1.png)\n",
+    "\n",
+    "Inserting for example `2` in the red box would immediately make `2` unavailable in all other boxes in top right corner. That is an example of a collapse of options.\n",
+    "\n",
+    "We can describe the \"options\" for each cell as: numbers - (box + row + column), e.g. the  `red` cell as:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 22,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{2, 7, 9}"
+      ]
+     },
+     "execution_count": 22,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "{1,2,3,4,5,6,7,8,9} - ({1,3,4,5,6,8} | {3,5} | {3,4,6}) "
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can also describe a whole sudoku's state as a list numbers, with zero as the uncollapsed space:.\n",
+    "\n",
+    "The box above hence becomes: \n",
+    "```\n",
+    "[8,4,1,\n",
+    " 0,0,6,\n",
+    " 5,0,3]\n",
+    "```\n",
+    "\n",
+    "Doing the same for a whole sudoku like this: \n",
+    "\n",
+    "![?](images/easy_sudoku.png)\n",
+    "\n",
+    "can then be:\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 23,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "sudoku = [\n",
+    "    # cell value        # cell number\n",
+    "    0,0,4,0,5,0,0,0,0,  #  0, 1, 2, 3, 4, 5, 6, 7, 8,\n",
+    "    9,0,0,7,3,4,6,0,0,  #  9,10,11,12,13,14,15,16,17,\n",
+    "    0,0,3,0,2,1,0,4,9,  # 18,19,20,21,22,23,24,25,26,  \n",
+    "    0,3,5,0,9,0,4,8,0,  # 27,28,29,30,31,32,33,34,35,\n",
+    "    0,9,0,0,0,0,0,3,0,  # 36,37,38,39,40,41,42,43,44,\n",
+    "    0,7,6,0,1,0,9,2,0,  # 45,46,47,48,49,50,51,52,53,\n",
+    "    3,1,0,9,7,0,2,0,0,  # 54,55,56,57,58,59,60,61,62,\n",
+    "    0,0,9,1,8,2,0,0,3,  # 63,64,65,66,67,68,69,70,71,\n",
+    "    0,0,0,0,6,0,1,0,0,  # 72,73,74,75,76,77,78,79,80\n",
+    "    # zero = blank.\n",
+    "]"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "To describe the options for a particular cell, we now need some basic math:\n",
+    "\n",
+    "We find the set of number that have not been used - just like a minute ago - but we use the \"cell\" based address system."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "![field_53 options](images/easy_sudoku3.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 24,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from math import floor\n",
+    "numbers = {1,2,3,4,5,6,7,8,9}\n",
+    "\n",
+    "def options(cell,sudoku):    \n",
+    "    column = {v for ix, v in enumerate(sudoku) if ix % 9 == cell % 9}\n",
+    "    row = {v for ix, v in enumerate(sudoku) if ix // 9 == cell // 9}\n",
+    "    box = {v for ix, v in enumerate(sudoku) if (ix // (9 * 3) == cell // (9 * 3)) and ((ix % 9) // 3 == (cell % 9) // 3)}\n",
+    "    return numbers - (box | row | column)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 25,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{5}"
+      ]
+     },
+     "execution_count": 25,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "options(53, sudoku)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "So there's one option for cell number 53, meaning that the solution landscape *must* eventually collapse around this single option. We can now guide our \"search\" by picking the cell's that have least options.\n",
+    "\n",
+    "Let's find them:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 26,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[5, 3, 0, 2, 0, 3, 3, 2, 4]\n",
+      "[0, 3, 3, 0, 0, 0, 0, 2, 4]\n",
+      "[4, 3, 0, 2, 0, 0, 3, 0, 0]\n",
+      "[2, 0, 0, 2, 0, 2, 0, 0, 3]\n",
+      "[4, 0, 3, 5, 1, 4, 2, 0, 4]\n",
+      "[2, 0, 0, 4, 0, 3, 0, 0, 1]\n",
+      "[0, 0, 1, 0, 0, 1, 0, 2, 4]\n",
+      "[4, 3, 0, 0, 0, 0, 2, 3, 0]\n",
+      "[5, 4, 3, 3, 0, 2, 0, 3, 4]\n"
+     ]
+    }
+   ],
+   "source": [
+    "degrees_of_freedom = [0 if v!=0 else len(options(ix,sudoku)) for ix,v in enumerate(sudoku)]\n",
+    "\n",
+    "for i in range(9):\n",
+    "    print(degrees_of_freedom[i*9:i*9+9])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Each of the numbers are the number of options available for each cell.\n",
+    "\n",
+    "We can then design our solver to inspect the sudoku as a finite state machine, where the \"current state\" is our partial solution, e.g. a list with 81 integers.\n",
+    "\n",
+    "![](images/sudoku_solver1.png)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 27,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "[2, 6, 4, 8, 5, 9, 3, 1, 7]\n",
+      "[9, 8, 1, 7, 3, 4, 6, 5, 2]\n",
+      "[7, 5, 3, 6, 2, 1, 8, 4, 9]\n",
+      "[1, 3, 5, 2, 9, 7, 4, 8, 6]\n",
+      "[8, 9, 2, 5, 4, 6, 7, 3, 1]\n",
+      "[4, 7, 6, 3, 1, 8, 9, 2, 5]\n",
+      "[3, 1, 8, 9, 7, 5, 2, 6, 4]\n",
+      "[6, 4, 9, 1, 8, 2, 5, 7, 3]\n",
+      "[5, 2, 7, 4, 6, 3, 1, 9, 8]\n"
+     ]
+    }
+   ],
+   "source": [
+    "# the sudoku is our initial state.\n",
+    "initial_state = sudoku[:]\n",
+    "\n",
+    "job_queue = [initial_state]  # we need the jobqueue in case of ambiguity of choice.\n",
+    "\n",
+    "while job_queue:\n",
+    "    state = job_queue.pop(0)\n",
+    "    if not any(i==0 for i in state):  # no missing values means that the sudoku is solved.\n",
+    "        break\n",
+    "\n",
+    "    degrees_of_freedom = [0 if v!=0 else len(options(ix,state)) for ix,v in enumerate(state)]\n",
+    "    least_freedom = min(v for v in degrees_of_freedom if v > 0)\n",
+    "    cell = degrees_of_freedom.index(least_freedom)\n",
+    "\n",
+    "    for option in options(cell, state):  # for each option we add the new state to the queue.\n",
+    "        new_state = state[:]\n",
+    "        new_state[cell] = option\n",
+    "        job_queue.append(new_state)\n",
+    "\n",
+    "# we print out the solution\n",
+    "for i in range(9):\n",
+    "    print(state[i*9:i*9+9])"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Conclusions\n",
+    "\n",
+    "What did we learn?\n",
+    "\n",
+    "Finite State Machines ...\n",
+    "\n",
+    "- are mathematical models of states and transitions.\n",
+    "- can be used as generators for mapping of a solution landscape.\n",
+    "- can be used to solve any discrete problem."
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3.10.5 ('graph310')",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.11"
+  },
+  "vscode": {
+   "interpreter": {
+    "hash": "26e418a870e8218a0038cc410eecceadac9265fed4dd23580d1f865f336a3180"
+   }
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

graph-theory/source/examples/graphs.py

@@ -0,0 +1,766 @@
+from graph import Graph
+from itertools import product
+
+
+def grid(x, y, bidirectional=False):
+    """
+    :param x: number of columns
+    :param y: number of rows
+    :param bidirectional: boolean
+    :return: Graph with grid.
+    """
+    g = Graph()
+    for i, j in product(range(x), range(y)):
+        if i % x > 0:  # connect west
+            n1 = i - 1, j
+            n2 = i, j
+            g.add_edge(n1, n2, bidirectional=bidirectional)
+
+        if j % y > 0:  # connect north
+            n1 = i, j - 1
+            n2 = i, j
+            g.add_edge(n1, n2, bidirectional=bidirectional)
+    return g
+
+
+def london_underground():
+    """the london underground network"""
+    london_underground_stations = {  # id:(latitude,longitude,station name),
+        1: (51.5028, -0.2801, "Acton Town"),
+        2: (51.5143, -0.0755, "Aldgate"),
+        3: (51.5154, -0.0726, "Aldgate East"),
+        4: (51.5107, -0.013, "All Saints"),
+        5: (51.5407, -0.2997, "Alperton"),
+        7: (51.5322, -0.1058, "Angel"),
+        8: (51.5653, -0.1353, "Archway"),
+        9: (51.6164, -0.1331, "Arnos Grove"),
+        10: (51.5586, -0.1059, "Arsenal"),
+        11: (51.5226, -0.1571, "Baker Street"),
+        12: (51.4431, -0.1525, "Balham"),
+        13: (51.5133, -0.0886, "Bank"),
+        14: (51.5204, -0.0979, "Barbican"),
+        15: (51.5396, 0.081, "Barking"),
+        16: (51.5856, 0.0887, "Barkingside"),
+        17: (51.4905, -0.2139, "Barons Court"),
+        18: (51.5121, -0.1879, "Bayswater"),
+        19: (51.5148, 0.0613, "Beckton"),
+        20: (51.5087, 0.055, "Beckton Park"),
+        21: (51.5403, 0.127, "Becontree"),
+        22: (51.5504, -0.1642, "Belsize Park"),
+        24: (51.527, -0.0549, "Bethnal Green"),
+        25: (51.512, -0.1031, "Blackfriars"),
+        26: (51.5867, -0.0417, "Blackhorse Road"),
+        27: (51.5079, -0.0066, "Blackwall"),
+        28: (51.5142, -0.1494, "Bond Street"),
+        29: (51.5011, -0.0943, "Borough"),
+        30: (51.4956, -0.325, "Boston Manor"),
+        31: (51.6071, -0.1243, "Bounds Green"),
+        32: (51.5273, -0.0208, "Bow Church"),
+        33: (51.5269, -0.0247, "Bow Road"),
+        34: (51.5766, -0.2136, "Brent Cross"),
+        36: (51.5248, -0.0119, "Bromley-By-Bow"),
+        38: (51.6028, -0.2641, "Burnt Oak"),
+        39: (51.5481, -0.1188, "Caledonian Road"),
+        40: (51.5392, -0.1426, "Camden Town"),
+        42: (51.5051, -0.0209, "Canary Wharf"),
+        44: (51.5113, -0.0904, "Cannon Street"),
+        45: (51.6078, -0.2947, "Canons Park"),
+        47: (51.5441, -0.1538, "Chalk Farm"),
+        48: (51.5185, -0.1111, "Chancery Lane"),
+        49: (51.508, -0.1247, "Charing Cross"),
+        51: (51.6177, 0.0755, "Chigwell"),
+        52: (51.4946, -0.2678, "Chiswick Park"),
+        54: (51.4618, -0.1384, "Clapham Common"),
+        55: (51.4649, -0.1299, "Clapham North"),
+        56: (51.4527, -0.148, "Clapham South"),
+        58: (51.5955, -0.2502, "Colindale"),
+        59: (51.418, -0.1778, "Colliers Wood"),
+        60: (51.5129, -0.1243, "Covent Garden"),
+        61: (51.4957, -0.0144, "Crossharbour & London Arena"),
+        63: (51.5095, 0.0276, "Custom House"),
+        65: (51.5085, 0.064, "Cyprus"),
+        66: (51.5443, 0.1655, "Dagenham East"),
+        67: (51.5417, 0.1469, "Dagenham Heathway"),
+        70: (51.5223, -0.0173, "Devons Road"),
+        71: (51.552, -0.2387, "Dollis Hill"),
+        72: (51.5152, -0.3017, "Ealing Broadway"),
+        73: (51.5101, -0.2882, "Ealing Common"),
+        74: (51.492, -0.1973, "Earl's Court"),
+        75: (51.5765, -0.397, "Eastcote"),
+        76: (51.5168, -0.2474, "East Acton"),
+        77: (51.5874, -0.165, "East Finchley"),
+        78: (51.5394, 0.0518, "East Ham"),
+        79: (51.5093, -0.0021, "East India"),
+        80: (51.4586, -0.2112, "East Putney"),
+        81: (51.6137, -0.275, "Edgware"),
+        82: (51.5199, -0.1679, "Edgware Road (B)"),
+        83: (51.5203, -0.17, "Edgware Road (C)"),
+        84: (51.4943, -0.1001, "Elephant & Castle"),
+        85: (51.5496, 0.1977, "Elm Park"),
+        87: (51.5074, -0.1223, "Embankment"),
+        89: (51.5282, -0.1337, "Euston"),
+        90: (51.526, -0.1359, "Euston Square"),
+        91: (51.596, 0.0912, "Fairlop"),
+        92: (51.5203, -0.1053, "Farringdon"),
+        93: (51.6012, -0.1932, "Finchley Central"),
+        94: (51.5472, -0.1803, "Finchley Road"),
+        95: (51.5642, -0.1065, "Finsbury Park"),
+        96: (51.4804, -0.195, "Fulham Broadway"),
+        97: (51.5096, 0.0716, "Gallions Reach"),
+        98: (51.5765, 0.0663, "Gants Hill"),
+        99: (51.4945, -0.1829, "Gloucester Road"),
+        100: (51.5724, -0.1941, "Golders Green"),
+        101: (51.5018, -0.2267, "Goldhawk Road"),
+        102: (51.5205, -0.1347, "Goodge Street"),
+        103: (51.6132, 0.0923, "Grange Hill"),
+        104: (51.5238, -0.1439, "Great Portland Street"),
+        105: (51.5423, -0.3456, "Greenford"),
+        107: (51.5067, -0.1428, "Green Park"),
+        108: (51.4915, -0.2754, "Gunnersbury"),
+        109: (51.603, 0.0933, "Hainault"),
+        110: (51.4936, -0.2251, "Hammersmith"),
+        111: (51.5568, -0.178, "Hampstead"),
+        112: (51.5302, -0.2933, "Hanger Lane"),
+        113: (51.5362, -0.2575, "Harlesden"),
+        114: (51.5925, -0.3351, "Harrow & Wealdston"),
+        115: (51.5793, -0.3366, "Harrow-on-the-Hill"),
+        116: (51.4669, -0.4227, "Hatton Cross"),
+        117: (51.4713, -0.4524, "Heathrow Terminals 1, 2 & 3"),
+        118: (51.4598, -0.4476, "Heathrow Terminal 4"),
+        119: (51.5829, -0.2259, "Hendon Central"),
+        120: (51.5033, -0.0215, "Heron Quays"),
+        122: (51.5009, -0.1925, "High Street Kensington"),
+        123: (51.546, -0.104, "Highbury & Islington"),
+        124: (51.5777, -0.1458, "Highgate"),
+        125: (51.5538, -0.4499, "Hillingdon"),
+        126: (51.5174, -0.12, "Holborn"),
+        127: (51.5075, -0.206, "Holland Park"),
+        128: (51.5526, -0.1132, "Holloway Road"),
+        129: (51.5539, 0.2184, "Hornchurch"),
+        130: (51.4713, -0.3665, "Hounslow Central"),
+        131: (51.4733, -0.3564, "Hounslow East"),
+        132: (51.4734, -0.3855, "Hounslow West"),
+        133: (51.5027, -0.1527, "Hyde Park Corner"),
+        134: (51.5619, -0.4421, "Ickenham"),
+        135: (51.4871, -0.0101, "Island Gardens"),
+        136: (51.4884, -0.1053, "Kennington"),
+        137: (51.5304, -0.225, "Kensal Green"),
+        138: (51.4983, -0.2106, "Kensington (Olympia)"),
+        139: (51.5507, -0.1402, "Kentish Town"),
+        140: (51.5816, -0.3162, "Kenton"),
+        141: (51.477, -0.285, "Kew Gardens"),
+        142: (51.5471, -0.2047, "Kilburn"),
+        143: (51.5351, -0.1939, "Kilburn Park"),
+        144: (51.5846, -0.2786, "Kingsbury"),
+        145: (51.5308, -0.1238, "King's Cross St. Pancras"),
+        146: (51.5015, -0.1607, "Knightsbridge"),
+        147: (51.5172, -0.2107, "Ladbroke Grove"),
+        148: (51.4991, -0.1115, "Lambeth North"),
+        149: (51.5119, -0.1756, "Lancaster Gate"),
+        150: (51.5139, -0.2172, "Latimer Road"),
+        151: (51.5113, -0.1281, "Leicester Square"),
+        153: (51.5566, -0.0053, "Leyton"),
+        154: (51.5683, 0.0083, "Leytonstone"),
+        155: (51.5123, -0.0396, "Limehouse"),
+        156: (51.5178, -0.0823, "Liverpool Street"),
+        157: (51.5052, -0.0864, "London Bridge"),
+        159: (51.53, -0.1854, "Maida Vale"),
+        160: (51.5712, -0.0958, "Manor House"),
+        161: (51.5122, -0.094, "Mansion House"),
+        162: (51.5136, -0.1586, "Marble Arch"),
+        163: (51.5225, -0.1631, "Marylebone"),
+        164: (51.5249, -0.0332, "Mile End"),
+        165: (51.6082, -0.2103, "Mill Hill East"),
+        166: (51.5108, -0.0863, "Monument"),
+        167: (51.5186, -0.0886, "Moorgate"),
+        168: (51.6294, -0.432, "Moor Park"),
+        169: (51.4022, -0.1948, "Morden"),
+        170: (51.5342, -0.1387, "Mornington Crescent"),
+        171: (51.4902, -0.0145, "Mudchute"),
+        172: (51.5542, -0.2503, "Neasden"),
+        173: (51.5756, 0.0899, "Newbury Park"),
+        176: (51.4995, -0.3142, "Northfields"),
+        177: (51.5483, -0.3687, "Northolt"),
+        178: (51.5784, -0.3184, "Northwick Park"),
+        179: (51.6111, -0.424, "Northwood"),
+        180: (51.6004, -0.4092, "Northwood Hills"),
+        181: (51.5237, -0.2597, "North Acton"),
+        182: (51.5175, -0.2887, "North Ealing"),
+        184: (51.5846, -0.3626, "North Harrow"),
+        185: (51.5621, -0.3034, "North Wembley"),
+        186: (51.5094, -0.1967, "Notting Hill Gate"),
+        188: (51.5263, -0.0873, "Old Street"),
+        190: (51.4813, -0.3522, "Osterley"),
+        191: (51.4819, -0.113, "Oval"),
+        192: (51.515, -0.1415, "Oxford Circus"),
+        193: (51.5154, -0.1755, "Paddington"),
+        194: (51.527, -0.2841, "Park Royal"),
+        195: (51.4753, -0.2011, "Parsons Green"),
+        196: (51.5366, -0.3232, "Perivale"),
+        197: (51.5098, -0.1342, "Picadilly Circus"),
+        198: (51.4893, -0.1334, "Pimlico"),
+        199: (51.5926, -0.3805, "Pinner"),
+        200: (51.5313, 0.0172, "Plaistow"),
+        201: (51.5077, -0.0173, "Poplar"),
+        202: (51.572, -0.2954, "Preston Road"),
+        203: (51.5093, 0.0336, "Prince Regent"),
+        205: (51.4682, -0.2089, "Putney Bridge"),
+        206: (51.5341, -0.2047, "Queen's Park"),
+        207: (51.5942, -0.2861, "Queensbury"),
+        208: (51.5107, -0.1877, "Queensway"),
+        209: (51.4942, -0.2359, "Ravenscourt Park"),
+        210: (51.5753, -0.3714, "Rayners Lane"),
+        211: (51.5763, 0.0454, "Redbridge"),
+        212: (51.5234, -0.1466, "Regent's Park"),
+        213: (51.4633, -0.3013, "Richmond"),
+        215: (51.6171, 0.0439, "Roding Valley"),
+        216: (51.501, -0.0525, "Rotherhithe"),
+        217: (51.5084, 0.0465, "Royal Albert"),
+        218: (51.519, -0.188, "Royal Oak"),
+        219: (51.5091, 0.0181, "Royal Victoria"),
+        220: (51.5715, -0.4213, "Ruislip"),
+        222: (51.5732, -0.4125, "Ruislip Manor"),
+        223: (51.523, -0.1244, "Russell Square"),
+        224: (51.5822, -0.0749, "Seven Sisters"),
+        225: (51.5117, -0.056, "Shadwell"),
+        226: (51.5046, -0.2187, "Shepherd's Bush (C)"),
+        227: (51.5058, -0.2265, "Shepherd's Bush (H)"),
+        228: (51.5227, -0.0708, "Shoreditch"),
+        229: (51.4924, -0.1565, "Sloane Square"),
+        230: (51.5808, 0.0216, "Snaresbrook"),
+        231: (51.4454, -0.2066, "Southfields"),
+        234: (51.5011, -0.3072, "South Ealing"),
+        235: (51.5646, -0.3521, "South Harrow"),
+        236: (51.4941, -0.1738, "South Kensington"),
+        237: (51.5701, -0.3081, "South Kenton"),
+        238: (51.5007, -0.0191, "South Quay"),
+        239: (51.5569, -0.3988, "South Ruislip"),
+        240: (51.4154, -0.1919, "South Wimbledon"),
+        241: (51.5917, 0.0275, "South Woodford"),
+        242: (51.495, -0.2459, "Stamford Brook"),
+        243: (51.6194, -0.3028, "Stanmore"),
+        244: (51.5221, -0.047, "Stepney Green"),
+        245: (51.4723, -0.123, "Stockwell"),
+        246: (51.5439, -0.2759, "Stonebridge Park"),
+        247: (51.5416, -0.0042, "Stratford"),
+        248: (51.4994, -0.1335, "St. James's Park"),
+        249: (51.5347, -0.174, "St. John's Wood"),
+        250: (51.5146, -0.0973, "St. Paul's"),
+        251: (51.5569, -0.3366, "Sudbury Hill"),
+        252: (51.5507, -0.3156, "Sudbury Town"),
+        253: (51.4933, -0.0478, "Surrey Quays"),
+        254: (51.5432, -0.1738, "Swiss Cottage"),
+        255: (51.5111, -0.1141, "Temple"),
+        257: (51.4361, -0.1598, "Tooting Bec"),
+        258: (51.4275, -0.168, "Tooting Broadway"),
+        259: (51.5165, -0.131, "Tottenham Court Road"),
+        260: (51.5882, -0.0594, "Tottenham Hale"),
+        262: (51.5106, -0.0743, "Tower Gateway"),
+        263: (51.5098, -0.0766, "Tower Hill"),
+        264: (51.5567, -0.1374, "Tufnell Park"),
+        265: (51.4951, -0.2547, "Turnham Green"),
+        266: (51.5904, -0.1028, "Turnpike Lane"),
+        267: (51.559, 0.251, "Upminster"),
+        268: (51.5582, 0.2343, "Upminster Bridge"),
+        269: (51.5385, 0.1014, "Upney"),
+        270: (51.5352, 0.0343, "Upton Park"),
+        271: (51.5463, -0.4786, "Uxbridge"),
+        272: (51.4861, -0.1253, "Vauxhall"),
+        273: (51.4965, -0.1447, "Victoria"),
+        274: (51.583, -0.0195, "Walthamstow Central"),
+        275: (51.5775, 0.0288, "Wanstead"),
+        276: (51.5043, -0.0558, "Wapping"),
+        277: (51.5247, -0.1384, "Warren Street"),
+        278: (51.5235, -0.1835, "Warwick Avenue"),
+        279: (51.5036, -0.1143, "Waterloo"),
+        281: (51.5519, -0.2963, "Wembley Central"),
+        282: (51.5635, -0.2795, "Wembley Park"),
+        283: (51.521, -0.2011, "Westbourne Park"),
+        284: (51.5097, -0.0265, "Westferry"),
+        285: (51.501, -0.1254, "Westminster"),
+        286: (51.518, -0.2809, "West Acton"),
+        287: (51.4872, -0.1953, "West Brompton"),
+        288: (51.6095, -0.1883, "West Finchley"),
+        289: (51.5287, 0.0056, "West Ham"),
+        290: (51.5469, -0.1906, "West Hampstead"),
+        291: (51.5795, -0.3533, "West Harrow"),
+        292: (51.507, -0.0203, "West India Quay"),
+        293: (51.4907, -0.2065, "West Kensington"),
+        294: (51.5696, -0.4376, "West Ruislip"),
+        295: (51.5194, -0.0612, "Whitechapel"),
+        296: (51.512, -0.2239, "White City"),
+        297: (51.5492, -0.2215, "Willesden Green"),
+        298: (51.5326, -0.2478, "Willesden Junction"),
+        299: (51.4214, -0.2064, "Wimbledon"),
+        300: (51.4343, -0.1992, "Wimbledon Park"),
+        301: (51.607, 0.0341, "Woodford"),
+        302: (51.6179, -0.1856, "Woodside Park"),
+        303: (51.5975, -0.1097, "Wood Green"),
+        35: (51.4627, -0.1145, "Brixton"),
+        6: (51.6736, -0.607, "Amersham"),
+        23: (51.4979, -0.0637, "Bermondsey"),
+        50: (51.7052, -0.611, "Chesham"),
+        46: (51.6679, -0.561, "Chalfont & Latimer"),
+        53: (51.6543, -0.5183, "Chorleywood"),
+        214: (51.6404, -0.4733, "Rickmansworth"),
+        62: (51.647, -0.4412, "Croxley"),
+        280: (51.6573, -0.4177, "Watford"),
+        221: (51.5606, -0.4103, "Ruislip Gardens"),
+        121: (51.6503, -0.1943, "High Barnet"),
+        261: (51.6302, -0.1791, "Totteridge & Whetstone"),
+        57: (51.6517, -0.1496, "Cockfosters"),
+        187: (51.6476, -0.1318, "Oakwood"),
+        232: (51.6322, -0.128, "Southgate"),
+        88: (51.6937, 0.1139, "Epping"),
+        256: (51.6717, 0.1033, "Theydon Bois"),
+        68: (51.6455, 0.0838, "Debden"),
+        158: (51.6412, 0.0558, "Loughton"),
+        37: (51.6266, 0.0471, "Buckhurst Hill"),
+        204: (51.5343, -0.0139, "Pudding Mill Lane"),
+        233: (51.501, -0.1052, "Southwark"),
+        41: (51.4982, -0.0502, "Canada Water"),
+        43: (51.5147, 0.0082, "Canning Town"),
+        183: (51.5005, 0.0039, "North Greenwich"),
+        64: (51.4827, -0.0096, "Cutty Sark"),
+        106: (51.4781, -0.0149, "Greenwich"),
+        69: (51.474, -0.0216, "Deptford Bridge"),
+        86: (51.4693, -0.0174, "Elverson Road"),
+        152: (51.4657, -0.0142, "Lewisham"),
+        174: (51.4767, -0.0327, "New Cross"),
+        175: (51.4757, -0.0402, "New Cross Gate"),
+    }
+
+    london_underground_lines = {  # line: "name"
+        1: "Bakerloo Line",
+        3: "Circle Line",
+        6: "Hammersmith & City Line",
+        7: "Jubilee Line",
+        11: "Victoria Line",
+        2: "Central Line",
+        4: "District Line",
+        5: "East London Line",
+        8: "Metropolitan Line",
+        9: "Northern Line",
+        10: "Piccadilly Line",
+        12: "Waterloo & City Line",
+        13: "Docklands Light Railway",
+    }
+
+    london_underground_connections = [  # (station1,station2), (line, time)
+        (11, 163), (1, 1),
+        (11, 212), (1, 2),
+        (49, 87), (1, 1),
+        (49, 197), (1, 2),
+        (82, 163), (1, 2),
+        (82, 193), (1, 3),
+        (84, 148), (1, 3),
+        (87, 279), (1, 2),
+        (113, 246), (1, 2),
+        (113, 298), (1, 2),
+        (114, 140), (1, 2),
+        (137, 206), (1, 3),
+        (137, 298), (1, 3),
+        (140, 237), (1, 2),
+        (143, 159), (1, 2),
+        (143, 206), (1, 2),
+        (148, 279), (1, 1),
+        (159, 278), (1, 1),
+        (185, 237), (1, 2),
+        (185, 281), (1, 2),
+        (192, 197), (1, 2),
+        (192, 212), (1, 2),
+        (193, 278), (1, 2),
+        (246, 281), (1, 3),
+        (13, 156), (2, 2),
+        (13, 250), (2, 2),
+        (16, 91), (2, 2),
+        (16, 173), (2, 2),
+        (24, 156), (2, 3),
+        (24, 164), (2, 2),
+        (28, 162), (2, 1),
+        (28, 192), (2, 1),
+        (37, 158), (2, 3),
+        (37, 301), (2, 3),
+        (48, 126), (2, 1),
+        (48, 250), (2, 2),
+        (51, 103), (2, 2),
+        (51, 215), (2, 2),
+        (68, 158), (2, 2),
+        (68, 256), (2, 3),
+        (72, 286), (2, 3),
+        (76, 181), (2, 2),
+        (76, 296), (2, 3),
+        (88, 256), (2, 2),
+        (91, 109), (2, 2),
+        (98, 173), (2, 3),
+        (98, 211), (2, 2),
+        (103, 109), (2, 3),
+        (105, 177), (2, 2),
+        (105, 196), (2, 2),
+        (112, 181), (2, 3),
+        (112, 196), (2, 2),
+        (126, 259), (2, 2),
+        (127, 186), (2, 2),
+        (127, 226), (2, 1),
+        (149, 162), (2, 3),
+        (149, 208), (2, 1),
+        (153, 154), (2, 3),
+        (153, 247), (2, 2),
+        (154, 230), (2, 2),
+        (154, 275), (2, 2),
+        (164, 247), (2, 4),
+        (177, 239), (2, 3),
+        (181, 286), (2, 2),
+        (186, 208), (2, 2),
+        (192, 259), (2, 2),
+        (211, 275), (2, 2),
+        (215, 301), (2, 3),
+        (221, 239), (2, 1),
+        (221, 294), (2, 3),
+        (226, 296), (2, 3),
+        (230, 241), (2, 2),
+        (241, 301), (2, 2),
+        (2, 156), (3, 2),
+        (2, 263), (3, 4),
+        (11, 83), (3, 3),
+        (11, 104), (3, 3),
+        (14, 92), (3, 1),
+        (14, 167), (3, 2),
+        (18, 186), (3, 2),
+        (18, 193), (3, 2),
+        (25, 161), (3, 1),
+        (25, 255), (3, 2),
+        (44, 161), (3, 1),
+        (44, 166), (3, 2),
+        (83, 193), (3, 3),
+        (87, 255), (3, 2),
+        (87, 285), (3, 2),
+        (90, 104), (3, 2),
+        (90, 145), (3, 2),
+        (92, 145), (3, 4),
+        (99, 122), (3, 4),
+        (99, 236), (3, 1),
+        (122, 186), (3, 3),
+        (156, 167), (3, 2),
+        (166, 263), (3, 2),
+        (229, 236), (3, 2),
+        (229, 273), (3, 2),
+        (248, 273), (3, 2),
+        (248, 285), (3, 2),
+        (3, 263), (4, 2),
+        (3, 295), (4, 2),
+        (15, 78), (4, 4),
+        (15, 269), (4, 2),
+        (17, 110), (4, 1),
+        (17, 293), (4, 2),
+        (18, 186), (4, 2),
+        (18, 193), (4, 2),
+        (21, 67), (4, 3),
+        (21, 269), (4, 2),
+        (25, 161), (4, 1),
+        (25, 255), (4, 2),
+        (33, 36), (4, 2),
+        (33, 164), (4, 1),
+        (36, 289), (4, 2),
+        (44, 161), (4, 1),
+        (44, 166), (4, 2),
+        (52, 1), (4, 2),
+        (52, 265), (4, 2),
+        (66, 67), (4, 4),
+        (66, 85), (4, 3),
+        (72, 73), (4, 4),
+        (73, 1), (4, 2),
+        (74, 99), (4, 3),
+        (74, 122), (4, 3),
+        (74, 138), (4, 2),
+        (74, 287), (4, 2),
+        (74, 293), (4, 1),
+        (78, 270), (4, 2),
+        (80, 205), (4, 2),
+        (80, 231), (4, 2),
+        (83, 193), (4, 3),
+        (85, 129), (4, 2),
+        (87, 255), (4, 2),
+        (87, 285), (4, 2),
+        (96, 195), (4, 2),
+        (96, 287), (4, 1),
+        (99, 236), (4, 1),
+        (108, 141), (4, 3),
+        (108, 265), (4, 3),
+        (110, 209), (4, 2),
+        (122, 186), (4, 3),
+        (129, 268), (4, 2),
+        (141, 213), (4, 3),
+        (164, 244), (4, 2),
+        (166, 263), (4, 2),
+        (195, 205), (4, 3),
+        (200, 270), (4, 2),
+        (200, 289), (4, 2),
+        (209, 242), (4, 2),
+        (229, 236), (4, 2),
+        (229, 273), (4, 2),
+        (231, 300), (4, 3),
+        (242, 265), (4, 1),
+        (244, 295), (4, 3),
+        (248, 273), (4, 2),
+        (248, 285), (4, 2),
+        (267, 268), (4, 3),
+        (299, 300), (4, 3),
+        (4, 70), (13, 2),
+        (4, 201), (13, 2),
+        (13, 225), (13, 2),
+        (19, 97), (13, 2),
+        (20, 65), (13, 2),
+        (20, 217), (13, 2),
+        (27, 79), (13, 2),
+        (27, 201), (13, 2),
+        (32, 70), (13, 2),
+        (32, 204), (13, 2),
+        (42, 120), (13, 2),
+        (42, 292), (13, 2),
+        (43, 79), (13, 2),
+        (43, 219), (13, 2),
+        (61, 171), (13, 2),
+        (61, 238), (13, 2),
+        (63, 203), (13, 2),
+        (63, 219), (13, 2),
+        (64, 106), (13, 2),
+        (64, 135), (13, 2),
+        (65, 97), (13, 2),
+        (69, 86), (13, 2),
+        (69, 106), (13, 2),
+        (86, 152), (13, 2),
+        (120, 238), (13, 2),
+        (135, 171), (13, 2),
+        (155, 225), (13, 2),
+        (155, 284), (13, 2),
+        (201, 284), (13, 2),
+        (201, 292), (13, 2),
+        (203, 217), (13, 2),
+        (204, 247), (13, 2),
+        (225, 262), (13, 2),
+        (284, 292), (13, 2),
+        (41, 216), (5, 1),
+        (41, 253), (5, 2),
+        (174, 253), (5, 4),
+        (175, 253), (5, 4),
+        (216, 276), (5, 1),
+        (225, 276), (5, 1),
+        (225, 295), (5, 2),
+        (228, 295), (5, 2),
+        (3, 156), (6, 4),
+        (3, 295), (6, 2),
+        (11, 83), (6, 3),
+        (11, 104), (6, 3),
+        (14, 92), (6, 1),
+        (14, 167), (6, 2),
+        (15, 78), (6, 4),
+        (33, 36), (6, 2),
+        (33, 164), (6, 1),
+        (36, 289), (6, 2),
+        (78, 270), (6, 2),
+        (83, 193), (6, 4),
+        (90, 104), (6, 2),
+        (90, 145), (6, 2),
+        (92, 145), (6, 4),
+        (101, 110), (6, 2),
+        (101, 227), (6, 1),
+        (147, 150), (6, 1),
+        (147, 283), (6, 2),
+        (150, 227), (6, 2),
+        (156, 167), (6, 2),
+        (164, 244), (6, 2),
+        (193, 218), (6, 1),
+        (200, 270), (6, 2),
+        (200, 289), (6, 2),
+        (218, 283), (6, 2),
+        (244, 295), (6, 3),
+        (11, 28), (7, 2),
+        (11, 249), (7, 4),
+        (23, 41), (7, 2),
+        (23, 157), (7, 3),
+        (28, 107), (7, 2),
+        (41, 42), (7, 3),
+        (42, 183), (7, 3),
+        (43, 183), (7, 3),
+        (43, 289), (7, 3),
+        (45, 207), (7, 2),
+        (45, 243), (7, 2),
+        (71, 172), (7, 2),
+        (71, 297), (7, 2),
+        (94, 254), (7, 2),
+        (94, 290), (7, 1),
+        (107, 285), (7, 3),
+        (142, 290), (7, 2),
+        (142, 297), (7, 2),
+        (144, 207), (7, 2),
+        (144, 282), (7, 4),
+        (157, 233), (7, 2),
+        (172, 282), (7, 4),
+        (233, 279), (7, 1),
+        (247, 289), (7, 3),
+        (249, 254), (7, 1),
+        (279, 285), (7, 2),
+        (2, 156), (8, 2),
+        (6, 46), (8, 4),
+        (11, 94), (8, 6),
+        (11, 104), (8, 3),
+        (14, 92), (8, 1),
+        (14, 167), (8, 2),
+        (46, 50), (8, 8),
+        (46, 53), (8, 4),
+        (53, 214), (8, 4),
+        (62, 168), (8, 4),
+        (62, 280), (8, 3),
+        (75, 210), (8, 2),
+        (75, 222), (8, 2),
+        (90, 104), (8, 2),
+        (90, 145), (8, 2),
+        (92, 145), (8, 4),
+        (94, 282), (8, 7),
+        (115, 178), (8, 2),
+        (115, 184), (8, 3),
+        (115, 291), (8, 2),
+        (125, 134), (8, 2),
+        (125, 271), (8, 3),
+        (134, 220), (8, 3),
+        (156, 167), (8, 2),
+        (168, 179), (8, 3),
+        (168, 214), (8, 4),
+        (178, 202), (8, 2),
+        (179, 180), (8, 2),
+        (180, 199), (8, 2),
+        (184, 199), (8, 3),
+        (202, 282), (8, 3),
+        (210, 291), (8, 3),
+        (220, 222), (8, 2),
+        (7, 145), (9, 2),
+        (7, 188), (9, 3),
+        (8, 124), (9, 3),
+        (8, 264), (9, 2),
+        (12, 56), (9, 2),
+        (12, 257), (9, 1),
+        (13, 157), (9, 2),
+        (13, 167), (9, 3),
+        (22, 47), (9, 2),
+        (22, 111), (9, 2),
+        (29, 84), (9, 1),
+        (29, 157), (9, 2),
+        (34, 100), (9, 3),
+        (34, 119), (9, 2),
+        (38, 58), (9, 2),
+        (38, 81), (9, 3),
+        (40, 47), (9, 2),
+        (40, 89), (9, 3),
+        (40, 139), (9, 2),
+        (40, 170), (9, 1),
+        (49, 87), (9, 1),
+        (49, 151), (9, 2),
+        (54, 55), (9, 2),
+        (54, 56), (9, 2),
+        (55, 245), (9, 1),
+        (58, 119), (9, 3),
+        (59, 240), (9, 2),
+        (59, 258), (9, 2),
+        (77, 93), (9, 4),
+        (77, 124), (9, 2),
+        (84, 136), (9, 2),
+        (87, 279), (9, 2),
+        (89, 145), (9, 2),
+        (89, 170), (9, 2),
+        (89, 277), (9, 1),
+        (93, 165), (9, 3),
+        (93, 288), (9, 2),
+        (100, 111), (9, 4),
+        (102, 259), (9, 1),
+        (102, 277), (9, 2),
+        (121, 261), (9, 3),
+        (136, 191), (9, 2),
+        (136, 279), (9, 3),
+        (139, 264), (9, 2),
+        (151, 259), (9, 1),
+        (167, 188), (9, 1),
+        (169, 240), (9, 4),
+        (191, 245), (9, 3),
+        (257, 258), (9, 2),
+        (261, 302), (9, 3),
+        (288, 302), (9, 1),
+        (1, 73), (10, 2),
+        (1, 234), (10, 4),
+        (1, 265), (10, 3),
+        (5, 194), (10, 3),
+        (5, 252), (10, 2),
+        (9, 31), (10, 3),
+        (9, 232), (10, 3),
+        (10, 95), (10, 2),
+        (10, 128), (10, 1),
+        (17, 74), (10, 3),
+        (17, 110), (10, 2),
+        (30, 176), (10, 2),
+        (30, 190), (10, 3),
+        (31, 303), (10, 2),
+        (39, 128), (10, 2),
+        (39, 145), (10, 5),
+        (57, 187), (10, 4),
+        (60, 126), (10, 1),
+        (60, 151), (10, 1),
+        (73, 182), (10, 3),
+        (74, 99), (10, 2),
+        (75, 210), (10, 2),
+        (75, 222), (10, 2),
+        (95, 160), (10, 2),
+        (99, 236), (10, 1),
+        (107, 133), (10, 2),
+        (107, 197), (10, 1),
+        (110, 265), (10, 2),
+        (116, 117), (10, 3),
+        (116, 118), (10, 3),
+        (116, 132), (10, 4),
+        (117, 118), (10, 5),
+        (125, 134), (10, 2),
+        (125, 271), (10, 3),
+        (126, 223), (10, 2),
+        (130, 131), (10, 2),
+        (130, 132), (10, 2),
+        (131, 190), (10, 2),
+        (133, 146), (10, 2),
+        (134, 220), (10, 3),
+        (145, 223), (10, 2),
+        (146, 236), (10, 3),
+        (151, 197), (10, 2),
+        (160, 266), (10, 3),
+        (176, 234), (10, 1),
+        (182, 194), (10, 2),
+        (187, 232), (10, 3),
+        (210, 235), (10, 3),
+        (220, 222), (10, 2),
+        (235, 251), (10, 2),
+        (251, 252), (10, 3),
+        (266, 303), (10, 2),
+        (26, 260), (11, 2),
+        (26, 274), (11, 2),
+        (35, 245), (11, 2),
+        (89, 145), (11, 2),
+        (89, 277), (11, 1),
+        (95, 123), (11, 2),
+        (95, 224), (11, 4),
+        (107, 192), (11, 2),
+        (107, 273), (11, 2),
+        (123, 145), (11, 4),
+        (192, 277), (11, 2),
+        (198, 272), (11, 1),
+        (198, 273), (11, 3),
+        (224, 260), (11, 3),
+        (245, 272), (11, 3),
+        (13, 279), (12, 4),
+    ]
+
+    g = Graph()
+    
+    for sid, station in london_underground_stations.items():
+        g.add_node(sid, obj=station)
+    for i in range(0,len(london_underground_connections),2):
+        n1,n2 = london_underground_connections[i]
+        _,time = london_underground_connections[i+1]
+        g.add_edge(n1, n2, time, bidirectional=True)
+    return g

graph-theory/source/examples/readme.md

@@ -0,0 +1,89 @@
+# Graph-theory examples
+
+This folder contains jupyter notebooks, with examples from
+graph-theory.
+
+If you're new to the field I would recommend to study (loosely)
+in the order below:
+
+***[basic graph theory](basic%20graph%20theory.ipynb)***: An introduction to the fundamental 
+terminology of graph-theory. Topics are:
+
+	nodes
+	edges
+	indegree
+	outdegree
+	has_path
+	distance path
+	is a subgraph
+	examples of existing graphs available for testing.
+
+***[generating and visualising graphs](generating%20and%20visualising%20graphs.ipynb)***: An introduction
+to making random xy graphs, grids and visualise them.
+
+***[comparing graphs](comparing%20graphs.ipynb)***: An overview of methods for comparing 
+graphs, such as:
+
+    topological sort
+	phase lines
+	graph-hash
+	flow_graph_hash
+	merkle-tree
+
+
+***[solving search problems](solving%20search%20problems.ipynb)***: An introduction to different
+methods for findings paths, including:
+
+	adjacency matrix
+	BFS
+	DFS
+      DFScan
+	bidi-BFS
+	TSP
+	[critical path method]
+	find loops
+
+***[calculating statistics about graphs](statistics%20on%20graphs.ipynb)*** provides an overview
+of common analysis of graphs, such as:
+
+	components
+	has cycles
+	network size
+	is partite
+	degree of separation
+
+
+***[solving transport problems](solving%20search%20problems.ipynb)*** provides tools for a wide range 
+of problems where discrete transport is essential.
+
+	minmax
+	minsum
+	shortest_tree all pairs.
+	scheduling problem
+	traffic scheduling problem
+		jam solver
+	trans shipment problem (needs rewrite)
+
+
+***[solving flow problems](solving%20flow%20problems.ipynb)*** provides tools for solving a 
+wide range of problems where continuous flow are central.
+
+	max flow
+	max flow min cut
+	min cost flow
+	all_simple_paths
+	all_paths
+	
+
+***[solving assignment problems](solving%20assignment%20problems.ipynb)*** provides tools for solving
+any kind of assignment problem.
+
+	assignment problem
+	wtap 
+
+
+***[representing systems as graphs](graphs%20as%20finite%20state%20machines.ipynb)*** provides a use case
+for using `graph as finite state machine`.
+
+
+

graph-theory/source/examples/solving assignment problems.ipynb

@@ -0,0 +1,36 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    ""
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

graph-theory/source/examples/solving flow problems.ipynb

@@ -0,0 +1,36 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    ""
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}

graph-theory/source/examples/solving search problems.ipynb

@@ -0,0 +1,652 @@
+{
+ "cells": [
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "# Solving search problem.\n",
+    "\n",
+    "An introduction to different methods for findings paths, including:\n",
+    "\n",
+    "\tadjacency matrix\n",
+    "\tBFS\n",
+    "    find loops\n",
+    "\tDFS\n",
+    "      DFScan\n",
+    "\tbidi-BFS\n",
+    "\tTSP\n",
+    "\t[critical path method]\n",
+    "\t\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "First things first. Let's load the imports for this chapter"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 1,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from graph import Graph"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## The adjacency matrix\n",
+    "\n",
+    "an adjacency matrix is a square matrix used to represent a finite graph. The elements of the matrix indicate whether pairs of vertices are adjacent or not in the graph.\n",
+    "\n",
+    "   The distance from a node to itself is 0 and distance from a node to\n",
+    "    an unconnected node is defined to be infinite. This does not mean that there\n",
+    "    is no path from a node to another via other nodes.\n",
+    "\n",
+    "```\n",
+    "Example:\n",
+    "    g = Graph(from_dict=\n",
+    "        {1: {2: 3, 3: 8, 5: -4},\n",
+    "         2: {4: 1, 5: 7},\n",
+    "         3: {2: 4},\n",
+    "         4: {1: 2, 3: -5},\n",
+    "         5: {4: 6}})\n",
+    "\n",
+    "    adjacency_matrix(g)\n",
+    "    {1: {1: 0, 2: 3, 3: 8, 4: inf, 5: -4},\n",
+    "     2: {1: inf, 2: 0, 3: inf, 4: 1, 5: 7},\n",
+    "     3: {1: inf, 2: 4, 3: 0, 4: inf, 5: inf},\n",
+    "     4: {1: 2, 2: inf, 3: -5, 4: 0, 5: inf},\n",
+    "     5: {1: inf, 2: inf, 3: inf, 4: 6, 5: 0}}\n",
+    "```"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The adjacency matrix is very helpful when we want to compute the all pairs shortest path.\n",
+    "\n",
+    "Find the cost of the shortest path between every pair of vertices in a\n",
+    "    weighted graph. Uses the Floyd-Warshall algorithm.\n",
+    "\n",
+    "    Example:\n",
+    "        inf = float('inf')\n",
+    "        g = Graph(from_dict=(\n",
+    "            {0: {0: 0,   1: 1,   2: 4},\n",
+    "             1: {0: inf, 1: 0,   2: 2},\n",
+    "             2: {0: inf, 1: inf, 2: 0}})\n",
+    "\n",
+    "        fw(g)\n",
+    "        {0: {0: 0,   1: 1,   2: 3},\n",
+    "        1: {0: inf, 1: 0,   2: 2},\n",
+    "        2: {0: inf, 1: inf, 2: 0}}\n",
+    "\n",
+    "        h = {1: {2: 3, 3: 8, 5: -4},\n",
+    "             2: {4: 1, 5: 7},\n",
+    "             3: {2: 4},\n",
+    "             4: {1: 2, 3: -5},\n",
+    "             5: {4: 6}}\n",
+    "\n",
+    "        fw(adj(h)) #\n",
+    "            {1: {1: 0, 2:  1, 3: -3, 4: 2, 5: -4},\n",
+    "             2: {1: 3, 2:  0, 3: -4, 4: 1, 5: -1},\n",
+    "             3: {1: 7, 2:  4, 3:  0, 4: 5, 5:  3},\n",
+    "             4: {1: 2, 2: -1, 3: -5, 4: 0, 5: -2},\n",
+    "             5: {1: 8, 2:  5, 3:  1, 4: 6, 5:  0}}\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Distance maps\n",
+    "\n",
+    "As you can see the adjacency matrix computes the whole graph, but often this isn't necessary. So I invented the distance map as \"light weight\" version of the adjacency matrix. Here is how it works:\n",
+    "\n",
+    "We have a 4x4 graph like this:\n",
+    "\n",
+    "    1 -> 2 -> 3 -> 4\n",
+    "    |    |    |    |\n",
+    "    v    v    v    v\n",
+    "    5 -> 6 -> 7 -> 8\n",
+    "    |    |    |    |\n",
+    "    v    v    v    v\n",
+    "    9 -> 10-> 11-> 12\n",
+    "    |    |    |    |\n",
+    "    v    v    v    v\n",
+    "    13-> 14-> 15-> 16\n",
+    "\n",
+    "And we would like to go the shortest distance between _some_ points.\n",
+    "\n",
+    "Arbitrarily we pick 3 or 5 as starts and decide to go to either 12 or 14.\n",
+    "\n",
+    "The objective is to choose ANY shortest path."
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 2,
+   "metadata": {},
+   "outputs": [
+    {
+     "data": {
+      "text/plain": [
+       "{3: 0,\n",
+       " 5: 0,\n",
+       " 2: 1,\n",
+       " 4: 1,\n",
+       " 7: 1,\n",
+       " 1: 1,\n",
+       " 6: 1,\n",
+       " 9: 1,\n",
+       " 8: 2,\n",
+       " 11: 2,\n",
+       " 10: 2,\n",
+       " 13: 2,\n",
+       " 12: 3,\n",
+       " 15: 3,\n",
+       " 14: 3,\n",
+       " 16: 4}"
+      ]
+     },
+     "execution_count": 2,
+     "metadata": {},
+     "output_type": "execute_result"
+    }
+   ],
+   "source": [
+    "edges = [\n",
+    "      (1, 2, 1),   (2, 3, 1),   (3, 4, 1),   (1, 5, 1),\n",
+    "      (5, 6, 1),   (6, 7, 1),   (7, 8, 1),   (2, 6, 1),\n",
+    "      (3, 7, 1),   (4, 8, 1),   (5, 9, 1),  (9, 10, 1),\n",
+    "    (10, 11, 1), (11, 12, 1),  (6, 10, 1),  (7, 11, 1),\n",
+    "     (8, 12, 1),  (9, 13, 1), (13, 14, 1), (14, 15, 1),\n",
+    "    (15, 16, 1), (10, 14, 1), (11, 15, 1), (12, 16, 1)\n",
+    "]\n",
+    "g = Graph()\n",
+    "for s, e, d in edges:\n",
+    "    g.add_edge(s, e, d, bidirectional=True)\n",
+    "    \n",
+    "g.distance_map(starts=[3, 5], ends=[12, 14])\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The distance map returns a dictionary with the distance from 3 and 5 traveling towards 12 and 14. \n",
+    "\n",
+    "Think of this map as a landscape, where the `starts` are at the bottom and then you want to \"walk\" towards either 12 or 14 following the path of least resistance."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "In my experience a lot of people are initially confused about the all-pairs shortest path, and it's usage.\n",
+    "\n",
+    "Let's compare it with two other methods:\n",
+    "\n",
+    "minsum: finds the mode(s) that have the smallest sum of distance to all other nodes\n",
+    "\n",
+    "minmax: finds the node(s) with shortest distance to all other nodes. \n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Breadth First Search (BFS)\n",
+    "\n",
+    "Breadth-first search (BFS) is an algorithm for searching a tree data structure for a node that satisfies a given property. It starts at the tree root and explores all nodes at the present depth prior to moving on to the nodes at the next depth level. Extra memory, usually a queue, is needed to keep track of the child nodes that were encountered but not yet explored.\n",
+    "\n",
+    "A simple example is where you are searching for the nearest gas station on a map: You start with your current position and follow the roads in all directions until you meet an intersection. You repeat this \"extension\" until you find a gas station.\n",
+    "\n",
+    "BFS on a map is very easy to understand. But what if you don't have a map? What if you only know where you can go?\n",
+    "\n",
+    "For example, in a chess endgame a chess engine may build the game tree from the current position by applying all possible moves, and use breadth-first search to find a win position for white. Implicit trees (such as game trees or other problem-solving trees) may be of infinite size; breadth-first search is guaranteed to find a solution node if one exists.\n",
+    "\n",
+    "A slightly simpler case is the search for a solution of the tile-slide puzzle.\n",
+    "\n",
+    "We can describe the state of a system by it's options as a graph:\n",
+    "\n",
+    "```\n",
+    " A       B\n",
+    "[1] --- [2]\n",
+    " |       |\n",
+    " |       |\n",
+    "[4] --- [3]\n",
+    "```\n",
+    "With tiles on position `[1]` and `[2]` where A is in 1 and B is in 2.\n",
+    "Let's find a way for A to move to 3 and B to move to 4.\n",
+    "\n",
+    "First we create the graph:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 3,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "g = Graph()\n",
+    "for s,e in zip([1,2,3,4], [2,3,4,1]):\n",
+    "    g.add_edge(s,e,1,bidirectional=True)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Then we define the `initial state` and `end state`:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 4,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "s1 = (('A',1), ('B',2))"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 5,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "end = (('A',3),('B',4))"
+   ]
+  },
+  {
+   "attachments": {},
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "Now `A` can't move from 1 via 2 to 3, as `B` blocks the way.\n",
+    "Similarly `B` can't move from 2 via 1 to 3, as `A` blocks the way.\n",
+    "So we need generate a tree using BFS as foundation for our search.\n",
+    "\n",
+    "the search will look like this:\n",
+    "\n",
+    "![search tree](images/search_tree.png)\n",
+    "\n",
+    "but as you see there is some redunancy in the search tree, it is better to create a graph of movements:\n",
+    "\n",
+    "![movements](images/movement_graph.png)\n",
+    "\n",
+    "We can now search for the shortest path from the `initial state` to the `end state` in the movements graph:\n",
+    "\n",
+    "This is the code from graph-theory"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 6,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "from graph.bfs import breadth_first_search\n",
+    "import inspect"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 7,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "def breadth_first_search(graph, start, end):\n",
+      "    \"\"\"Determines the path from start to end with fewest nodes.\n",
+      "    :param graph: class Graph\n",
+      "    :param start: start node\n",
+      "    :param end: end node\n",
+      "    :return: path\n",
+      "    \"\"\"\n",
+      "    if not isinstance(graph, BasicGraph):\n",
+      "        raise TypeError(f\"Expected BasicGraph, Graph or Graph3D, not {type(graph)}\")\n",
+      "    if start not in graph:\n",
+      "        raise ValueError(f\"{start} not in graph\")\n",
+      "    if end not in graph:\n",
+      "        raise ValueError(f\"{end} not in graph\")\n",
+      "\n",
+      "    visited = {start: None}\n",
+      "    q = deque([start])\n",
+      "    while q:\n",
+      "        node = q.popleft()\n",
+      "        if node == end:\n",
+      "            path = deque()\n",
+      "            while node is not None:\n",
+      "                path.appendleft(node)\n",
+      "                node = visited[node]\n",
+      "            return list(path)\n",
+      "        for next_node in graph.nodes(from_node=node):\n",
+      "            if next_node not in visited:\n",
+      "                visited[next_node] = node\n",
+      "                q.append(next_node)\n",
+      "    return []\n",
+      "\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(inspect.getsource(breadth_first_search))"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "**Explanation of the code**\n",
+    "\n",
+    "`breadth_first_search` starts with the `start` (our `initial state`) and `end` (our `end state`) and puts `start` into a `deque`.\n",
+    "\n",
+    "```\n",
+    "def breadth_first_search(graph, start, end):\n",
+    "    visited = {start: None}\n",
+    "    q = deque([start])\n",
+    "```\n",
+    "Then it enters the `while` loop and runs as long as there's node in the queue.\n",
+    "```\n",
+    "    while q:\n",
+    "        node = q.popleft()\n",
+    "        if node == end:\n",
+    "```\n",
+    "The algorithm then removes the first item from the queue using `popleft`, and checks whether it's the `end`. If it isn't, the search continues:\n",
+    "\n",
+    "We take each node that the popped `node` is connected to and check if we have seen it before. If we have seen it before we just continue to the next node. If we haven't seen it before we add it to the queue.\n",
+    "```\n",
+    "        for next_node in graph.nodes(from_node=node):\n",
+    "            if next_node not in visited:\n",
+    "                visited[next_node] = node\n",
+    "                q.append(next_node)\n",
+    "```\n",
+    "Finally when the `end` is the node we are looking for we can terminate the search."
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### finding loops"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Depth First Search (DFS)\n",
+    "\n"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "## Bidirectional breadth first search (BidiBFS)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {
+    "jupyter": {
+     "outputs_hidden": true
+    }
+   },
+   "source": [
+    "## Critical path method\n",
+    "\n",
+    "The [critical path method](https://en.wikipedia.org/wiki/Critical_path_method) (CPM), or critical path analysis (CPA), is an algorithm for scheduling a set of project activities.\n",
+    "\n",
+    "A critical path is determined by identifying the longest stretch of dependent activities and, commonly, measuring the time required to complete them from start to finish.\n",
+    "\n",
+    "An example is shown below where the critical path constitutes the path ABCDE:\n",
+    "\n",
+    "![w](images/cpm_wo_artificial_dependency.png)\n",
+    "\n",
+    "We can load these values into a Graph as follows:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 8,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "tasks = {'A': 10, 'B': 20, 'C': 5, 'D': 10, 'E': 20, 'F': 15, 'G': 5, 'H': 15}\n",
+    "dependencies = [\n",
+    "    ('A', 'B'),\n",
+    "    ('B', 'C'),\n",
+    "    ('C', 'D'),\n",
+    "    ('D', 'E'),\n",
+    "    ('A', 'F'),\n",
+    "    ('F', 'G'),\n",
+    "    ('G', 'E'),\n",
+    "    ('A', 'H'),\n",
+    "    ('H', 'E'),\n",
+    "]\n",
+    "\n",
+    "g = Graph()\n",
+    "for n, d in tasks.items():\n",
+    "    g.add_node(n, obj=d)\n",
+    "for n1, n2 in dependencies:\n",
+    "    g.add_edge(n1, n2, 0)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "And we can calculate the schedule and the length of the critical path as:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 9,
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "critical_path_length, schedule = g.critical_path()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 10,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The critical path has duration 65\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"The critical path has duration\", critical_path_length)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 11,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The tasks are:\n",
+      "A Task('A', 10, 0, 0, 10, 10)\n",
+      "B Task('B', 20, 10, 10, 30, 30)\n",
+      "C Task('C', 5, 30, 30, 35, 35)\n",
+      "D Task('D', 10, 35, 35, 45, 45)\n",
+      "E Task('E', 20, 45, 45, 65, 65)\n",
+      "F Task('F', 15, 10, 25, 25, 40)\n",
+      "G Task('G', 5, 25, 40, 30, 45)\n",
+      "H Task('H', 15, 10, 30, 25, 45)\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"The tasks are:\")\n",
+    "from graph.critical_path import Task\n",
+    "for task_id, task in sorted(schedule.items()):\n",
+    "    print(task_id, task)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "The properties of each `Task` are:\n",
+    "\n",
+    "- task id\n",
+    "- duration \n",
+    "- earliest start time\n",
+    "- latest start time\n",
+    "- earliest finish time\n",
+    "- latest finish time.\n",
+    "\n",
+    "and the slack in the schedule can be calculated as:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 12,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The total slack in the schedule is 50\n"
+     ]
+    }
+   ],
+   "source": [
+    "slack = sum(t.slack for t in schedule.values())\n",
+    "\n",
+    "print(\"The total slack in the schedule is\", slack)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### Minimising slack\n",
+    "\n",
+    "In cases where the tasks are commodities, such as CPU time, it can be convenient to minimise the number of concurrently active resources.\n",
+    "\n",
+    "As you may have noticed above in the diagram, the dependencies indicate that the graph has 3 paths at it's widest, whereby it would be logical to assign 3 CPUs to compute the tasks. However a little search can illustrate that it is possible to solve the tasks with 2 CPUs without extending the critical path.\n",
+    "\n",
+    "This can be done by inserting artificial dependencies. Here is an example:\n",
+    "\n",
+    "![wo](images/cpm_w_artificial_dependency.png)\n",
+    "\n",
+    "The method to minimise the slack, is conveniently called `critical_path_minimize_for_slack` and this is how it is used:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 13,
+   "metadata": {
+    "jupyter": {
+     "outputs_hidden": false
+    },
+    "pycharm": {
+     "name": "#%%\n"
+    }
+   },
+   "outputs": [],
+   "source": [
+    "g2 = g.critical_path_minimize_for_slack()"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "We can verify that the critical path length is the same, and we can verify that this schedule does indeed have less slack:"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 14,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The total slack in the schedule was 50 and is now 0\n"
+     ]
+    }
+   ],
+   "source": [
+    "critical_path_length2, schedule2 = g2.critical_path()\n",
+    "\n",
+    "slack2 = sum(t.slack for t in schedule2.values())\n",
+    "\n",
+    "print(\"The total slack in the schedule was\", slack, \"and is now\", slack2)"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": 15,
+   "metadata": {},
+   "outputs": [
+    {
+     "name": "stdout",
+     "output_type": "stream",
+     "text": [
+      "The tasks remain the same, though with changed timings::\n",
+      "A Task('A', 10, 0, 0, 10, 10)\n",
+      "B Task('B', 20, 10, 10, 30, 30)\n",
+      "C Task('C', 5, 30, 30, 35, 35)\n",
+      "D Task('D', 10, 35, 35, 45, 45)\n",
+      "E Task('E', 20, 45, 45, 65, 65)\n",
+      "F Task('F', 15, 25, 25, 40, 40)\n",
+      "G Task('G', 5, 40, 40, 45, 45)\n",
+      "H Task('H', 15, 10, 10, 25, 25)\n"
+     ]
+    }
+   ],
+   "source": [
+    "print(\"The tasks remain the same, though with changed timings::\")\n",
+    "from graph.critical_path import Task\n",
+    "for task_id, task in sorted(schedule2.items()):\n",
+    "    print(task_id, task)"
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3 (ipykernel)",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 3
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython3",
+   "version": "3.10.11"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 4
+}

graph-theory/source/examples/solving transport problems.ipynb

@@ -0,0 +1,36 @@
+{
+ "cells": [
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "metadata": {
+    "collapsed": true
+   },
+   "outputs": [],
+   "source": [
+    ""
+   ]
+  }
+ ],
+ "metadata": {
+  "kernelspec": {
+   "display_name": "Python 3",
+   "language": "python",
+   "name": "python3"
+  },
+  "language_info": {
+   "codemirror_mode": {
+    "name": "ipython",
+    "version": 2
+   },
+   "file_extension": ".py",
+   "mimetype": "text/x-python",
+   "name": "python",
+   "nbconvert_exporter": "python",
+   "pygments_lexer": "ipython2",
+   "version": "2.7.6"
+  }
+ },
+ "nbformat": 4,
+ "nbformat_minor": 0
+}