Merge pull request #59 from StevenBtw/dev

Dev

Author: StevenBtw

docs/algorithms/graph/shortest-paths.md

@@ -4,7 +4,7 @@ Algorithms for finding shortest paths in weighted graphs. For unweighted graphs,
 
 ## dijkstra
 
-[Dijkstra's algorithm](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm) for non-negative edge weights. Greedily expands the closest unvisited node.
+[Dijkstra's algorithm](https://en.wikipedia.org/wiki/Dijkstra%27s_algorithm) for non-negative edge weights. The classic greedy shortest path algorithm.
 
 ```python
 from solvor import dijkstra
@@ -21,7 +21,11 @@ print(result.solution)  # ['A', 'B', 'C', 'D']
 print(result.objective)  # 4
 ```
 
-**Complexity:** O((V + E) log V)
+**How it works:** Maintain a priority queue of nodes by tentative distance. Always expand the closest unvisited node—with non-negative weights, this node's distance is final. Update neighbors and repeat until you reach the goal.
+
+The key insight: if all edges are non-negative, the shortest path to the closest unexplored node can't possibly go through unexplored territory (that would only add distance). So we can "lock in" each node's distance as we visit it.
+
+**Complexity:** O((V + E) log V) with a binary heap, where V = nodes, E = edges
 **Guarantees:** Optimal for non-negative weights
 
 ## astar
@@ -72,7 +76,13 @@ result = bellman_ford(n_nodes=4, edges=edges, start=0)
 print(result.solution)  # Distances from node 0
 ```
 
-**Complexity:** O(VE)
+**How it works:** Relax all edges V−1 times (where V is the number of nodes). "Relaxing" an edge means: if going through this edge gives a shorter path, update the distance.
+
+Each pass guarantees we've found shortest paths using at most k edges. After V−1 passes, we've found all shortest paths—because a simple path visits each node at most once, so it uses at most V−1 edges.
+
+To detect negative cycles: do one more pass. If any distance still improves, there's a negative cycle—you can keep going around it forever, reducing the distance infinitely.
+
+**Complexity:** O(V × E) where V = nodes, E = edges
 **Guarantees:** Optimal, detects negative cycles
 
 ## floyd_warshall

docs/algorithms/linear-programming/solve-lp-interior.md

@@ -47,14 +47,34 @@ print(result.objective)  # 12.0 approximately
 
 ## How It Works
 
-Interior point methods maintain a point strictly inside the feasible region and move toward optimality while staying interior. This implementation uses:
+While simplex hops between vertices, interior point methods stay strictly inside the feasible region and approach optimality along a curved path called the *central path*.
 
-1. **Primal-dual formulation** — Solves primal and dual problems simultaneously
-2. **Mehrotra predictor-corrector** — Two-step Newton method for faster convergence
-3. **Normal equations** — Reduces the KKT system to a smaller symmetric system
-4. **Cholesky decomposition** — Efficiently solves the symmetric linear system
+**The barrier idea:** Add a logarithmic penalty for approaching boundaries:
 
-Each iteration requires O(n³) work for the linear solve, but converges in O(√n) iterations.
+```text
+minimize c·x - μ Σ log(xᵢ)
+```
+
+As μ→0, the solution approaches the true optimum. But we don't solve this directly.
+
+**Primal-dual formulation:** Instead of just the primal problem, we solve primal and dual simultaneously. The optimality conditions (KKT) are:
+
+```text
+Ax = b           (primal feasibility)
+A'y + z = c      (dual feasibility)
+xᵢzᵢ = 0         (complementarity)
+x, z ≥ 0
+```
+
+We relax complementarity to xᵢzᵢ = μ and drive μ→0.
+
+**Newton's method:** Each iteration solves a linear system (the KKT system) to find a direction, then takes a step while staying positive. The magic is that convergence is polynomial—typically 20-50 iterations regardless of problem size.
+
+**Mehrotra predictor-corrector:** Two Newton steps per iteration. First a "predictor" step toward the boundary, then a "corrector" step that recenters. Nearly doubles the practical speed.
+
+**Normal equations:** The 3×3 block KKT system reduces to a smaller m×m system (A D A'), solved via Cholesky decomposition.
+
+For the theory, see [Interior Point Methods on Wikipedia](https://en.wikipedia.org/wiki/Interior-point_method) or Nocedal & Wright's *Numerical Optimization*.
 
 ## Simplex vs Interior Point
 

docs/algorithms/linear-programming/solve-lp.md

@@ -60,10 +60,39 @@ result = solve_lp(c, [[-1, -1]], [-4])
 result = solve_lp(c, [[1, 1], [-1, -1]], [4, -4])
 ```
 
+## How It Works
+
+The simplex algorithm exploits a key insight: the optimal solution to a linear program always occurs at a vertex (corner) of the feasible region. Instead of searching the entire space, we hop from vertex to vertex, always improving the objective.
+
+**The geometry:** Your constraints define a convex polytope in n-dimensional space. Each vertex is where n constraints meet. The objective function defines a direction—we're looking for the vertex furthest in that direction.
+
+**The algebra:** We convert to standard form with slack variables:
+
+```text
+minimize c·x
+subject to Ax + s = b, x ≥ 0, s ≥ 0
+```
+
+Each vertex corresponds to a *basic feasible solution*—setting n variables to zero and solving for the rest. The algorithm:
+
+1. Start at a vertex (basic feasible solution)
+2. Look at adjacent vertices (one pivot away)
+3. Move to a neighbor with better objective value
+4. Repeat until no improvement possible → optimal
+
+**The pivot:** Each iteration picks an entering variable (improves objective) and leaving variable (maintains feasibility), then updates the tableau. This is the "walking along edges" part.
+
+**Two-phase method:** If the origin isn't feasible (some constraints violated), Phase I finds a feasible starting vertex using artificial variables. Phase II then optimizes.
+
+**Bland's rule:** Prevents cycling (revisiting the same vertex) by always picking the smallest index when ties occur.
+
+For the full algorithm, see [Linear Programming on Wikipedia](https://en.wikipedia.org/wiki/Simplex_algorithm) or the classic textbook by Chvátal.
+
 ## Complexity
 
-- **Time:** O(exponential worst case, polynomial average case)
-- **Guarantees:** Finds the exact optimum for LP problems
+- **Time:** O(2^n) worst case, but O(n²m) average on random instances
+- **Space:** O(nm) for the tableau
+- **Guarantees:** Finds the exact global optimum (not approximate)
 
 ## Tips
 

docs/algorithms/metaheuristics/anneal.md

@@ -76,12 +76,25 @@ result = anneal(initial, obj, neighbors, cooling=logarithmic_cooling(c=1.0))
 
 ## How It Works
 
-1. Start with initial solution at high temperature
-2. Generate random neighbor
-3. If neighbor is better, accept it
-4. If neighbor is worse, accept with probability exp(-delta/T)
-5. Reduce temperature according to cooling schedule
-6. Stop when temperature drops below `min_temp` or `max_iter` reached
+**The metallurgy analogy:** In real annealing, you heat metal until atoms move freely, then cool slowly so atoms settle into a low-energy crystal structure. Cool too fast and you get brittle metal with defects (stuck in local minimum). The algorithm mimics this.
+
+**The math:** Accept worse solutions with probability:
+
+```text
+P(accept) = exp(-Δcost / temperature)
+```
+
+At high temperature, this is near 1—accept almost anything. At low temperature, this approaches 0—only accept improvements. The exponential form comes from statistical mechanics (Boltzmann distribution).
+
+**Why it works:** Early on, high temperature lets you escape local optima by accepting worse moves. As you cool, you become more selective, converging toward a good solution. The probability of accepting a bad move depends on *how bad*—small backward steps are more likely than large ones.
+
+**The algorithm:**
+
+1. Start at high temperature with initial solution
+2. Pick a random neighbor
+3. If better, accept. If worse, accept with probability exp(-Δ/T)
+4. Cool down: T ← T × cooling_rate
+5. Repeat until cold or max iterations
 
 ## Reproducibility
 

solvor/dijkstra.py

@@ -16,7 +16,7 @@
 
 For negative edges use bellman_ford, Dijkstra's negativity was legendary,
 just not in his algorithm. For unweighted graphs use bfs (simpler).
-With a good distance estimate, use astar.
+With a good distance estimate, use a_star.
 """
 
 from collections.abc import Callable, Iterable