Merge pull request #12 from Driolar/master

Revised chapters 1, 2 and 9.

Author: Ducasse

Chapters/Chapter1/chapter1.md

@@ -1,4 +1,59 @@
-## IntroductionGraphs are everywhere and there is well-known algorithms to get the best out of them.In this booklet the most common graph algorithms will be explained along with some case studieswhere these algorithms can be applied. These algorithms are available in the _Pharo AI_ _graph-algorithms_ library available at: [https://github.com/pharo-ai/graph-algorithms](https://github.com/pharo-ai/graph-algorithms)This booklet will describe and implement this algorithms.### Paris metro as graph exampleA typical example is a metro map as the one of Paris as shown in Figure *@paris@*.What we see is that metro lines are connected by some stations for example \(Gare du Nord connects line 5 and 4\) and some stations are real hub where multiple lines meet such as Chatelet.![Newly design paris metro maps.](figures/Paris_Metro_map_1024.pdf width=100&label=paris)When you visit Paris, you are often asking yourself:- what are the different possibilities to go to that place?- are they straight connections?- finding the fastest one?- finding the one with the least stops \(because RER is a fast kind of metro but stopping only in certain places\)- finding the one with the least changes?- what are all the places that I can reach in 5 stops?All such questions can be answered by modeling the metro of Paris as a graph and applying algorithms to it.Several graphs can be represented:- we can have graph with only the shared stations and eliminate the station in between \(this would not be really useful for users because you do not want to only used shared stations\).- we can have a graph with the time between two stations.### About testsTo ensure that the algorithms are working properly, we have implemented several tests for this library. We have a graph fixture in which we have implemented different types of graphs.Each graph is implemented on a class side method and the method has a link to a picture to see the graph visually.Then, in each of the tests for each of the algorithms, we construct a graph and check if the result after running the algorithm is the expected one.#### Outline of the documentIn this little book we will describe some algorithms that can be applied to graphs.We will start with some basic definitions, then in subsequent chapters we will describe the following algorithms:topological sort, shortest path, Kruskal, Tarjan, HITS, ...All the algorithms of the library have the same API to set the nodes and the edges.The edges can be both weighted or unweighted.A detailed explanation of how to use the API will be given on Chapter *@cha:repre@*.### How to installYou can install the library executing the following code snippet:```Metacello new
-	repository: 'github://pharo-ai/graph-algorithms/src';
-	baseline: 'AIGraphAlgorithms';
-	load```
+## Introduction
+
+Graphs are everywhere and there is well-known algorithms to get the best out of them.
+In this booklet the most common graph algorithms will be explained along with some case studies where these algorithms can be applied. These algorithms are available in the _Pharo AI_ _graph-algorithms_ library available at: [https://github.com/pharo-ai/graph-algorithms](https://github.com/pharo-ai/graph-algorithms).
+
+This booklet will describe and implement thess algorithms.
+
+### Paris metro as graph example
+
+A typical example is a metro map as the one of Paris as shown in Figure *@paris@*.
+What we see is that metro lines are connected by some stations for example \(Gare du Nord connects line 5 and 4\) and some (interchange) stations are a hub where multiple lines meet such as Chatelet.
+
+![Newly designed Paris metro maps.](figures/Paris_Metro_map_1024.pdf width=100&label=paris)
+
+When you visit Paris, you are often asking yourself:
+
+- what are the different possibilities to go to that place?
+- are they straight connections?
+- finding the fastest one?
+- finding the one with the least stops \(because RER is a fast kind of metro but stopping only in certain places\)
+- finding the one with the least changes?
+- what are all the places that I can reach in 5 stops?
+
+All such questions can be answered by modeling the metro of Paris as a graph and applying algorithms to it.
+
+Several graphs can be represented:
+
+- we can have graph with only the interchange stations and eliminate the stations in between \(this would not be really useful for users because you do not want to only use interchange stations\).
+- we can have a graph with the ride time between two stations.
+
+### About tests
+
+To ensure that the algorithms are working properly, we have implemented several tests for this library. We have a graph fixture in which we have implemented different types of graphs.
+Each graph is implemented on a class side method and the method has a link to a picture to see the graph visually.
+Then, in each of the tests for each of the algorithms, we construct a graph and check if the result after running the algorithm is the expected one.
+
+#### Outline of the document
+
+In this little book we will describe some algorithms that can be applied to graphs.
+We will start with some basic definitions, then in subsequent chapters we will describe algorithms for several graph problem categories like topological sorting, shortest path, minimum spanning tree, strongly connected components, link analysis, graph matching or maximum flow. The algorithms are often named for its inventor or inventors (Kruskal, Tarjan, Bellman-Ford, ...) or use acronyms (BFS, DAG, HITS, ...).
+
+All the algorithms of the library have the same API to set the nodes and the edges.
+The edges can be both weighted or unweighted. A detailed explanation of how to use the API will be given on Chapter *@cha:repre@*.
+
+### How to install
+
+You can install the library executing the following code snippet{!footnote|EpMonitor serves to deactive Epicea, a Pharo code recovering mechanism, during the installation.!}:
+
+```
+EpMonitor disableDuring: [
+    Metacello new
+        repository: 'github://pharo-ai/graph-algorithms';
+        baseline: 'AIGraphAlgorithms';
+        load ]
+```
+
+However, the library is provided by a fresh Pharo image since Pharo 11.
+
+You may also separately download from the `GraphGenerators` baseline group a tenner of library algorithms for generating regular and random graphs.

Chapters/Chapter2/chapter2.md

@@ -1,114 +1,97 @@
-## Basic definitions
-
-
-There is a great set of mathematical problems that can be solved using graph models. Graphs are vastly used in all kind of computer science problems.
-Graphs are discrete mathematical structures that consist of a set of vertices \(also called nodes\) and a set of edges that connect those vertices.
-In computer science is more commonly used the term _node_ instead of _vertex_. In this booklet the term node is going to be the one used.
-
-There are multiple types of graphs according if the edges are directed or undirected, if the edges are weighted or unweighted and so on.
-In this chapter, basic graph concepts and graphs types are going to be explained to ease the following of the algorithms.
-
-### Type of Graphs
-
-
-#### Directed Graph
-
-
-A directed graph is a type of graph in which every edges has a direction: an ingoing node and an outgoing node. The most commonly way of representing a graph is to draw it.
-A directed graph can de drawn like in Figure *@directed@*:
-
-![A directed graph.](figures/directed_graph.pdf width=30&label=directed)
-
-#### Undirected Graph
-
-
-An undirected graph is a type of graph in which the edges does not have a direction. They can be drawn without a line that does not have any arrow heads. It is
-understood that the graph has no direction if the direction is not specified explicitly as shown in Figure *@undirected@*.
-
-![An undirected graph.](figures/undirected_graph.pdf width=30&label=undirected)
-
-#### Weighted Graph
-
-
-A weighted graph is a graph that each of its edges has an associated weight \(see Figure *@weighted@*\). In real life examples, the weights can represent several things.
-For example, a graph can be a map in which the nodes represent cities and the edges represent the distance between those cities.
-
-![A weighted graph: edges have a weight.](figures/weighted_graph.pdf width=40&label=weighted)
-
-#### Connected Graph
-
-
-A connected graph is an undirected graph in which exists a path for every pair of nodes.
-For example, Figure *@connected@* represents a connected graph because from any node you can get to any node.
-
-![A connected graph: all the nodes are reachable from any others.](figures/connected_graph.pdf width=40&label=connected)
-
-But, Figure *@directed2@* is a disconnected graph because the nodes F and G are isolated from the rest.
-
-![A disconnected graph: some nodes are not reachable from others.](figures/disconnected_graph.pdf width=48&label=directed2)
-
-#### Bipartite Graph
-
-A bipartite graph is a graph whose set of vertices can be split into two subsets A and B in such a way that each edge of the graph joins a vertex in A and a vertex in B.
-A complete bipartite graph is a bipartite graph in which each vertex in A is joined to each vertex in B by just one edge.
-
-
-### Graph Cycle
-
-
-A graph cycle is a sequence of adjacent nodes in which all nodes are different except of the first and the last one.
-That means, a graph cycle is a path that ends and starts in the same node without repeating any other node and it has a size grater than 3.
-
-For example, in  Figure *@cycle1@* there is a cycle between nodes _A, B, D_.
-
-![A Cycle in a graph.](figures/cycle_in_a_graph.pdf width=40&label=cycle1)
-
-But, in Figure *@cycle2@* there is no cycle between from node A to C because the node D has to be traveled twice.
-Nevertheless, there is a cycle between node D, B and C.
-
-![In a directed graph, direction is impacting cycle presence. ](figures/not_a_cycle.pdf width=52&label=cycle2)
-
-#### Directed Acyclic Graph \(DAG\)
-
-
-Like the name suggests, a directed acyclic graph is a directed graph that does not have any cycles \(as shown in Figure *@DAG@*\).
-
-![A directed Acyclic Graph.](figures/dag.pdf width=35&label=DAG)
-
-#### Strongly Connected Graph
-
-
-Unlike the Connected Graph, a Strongly Connect is a **directed** graph in which there is a path for every pair of nodes. Figure *@strongly1@* is a strongly connected graph.
-
-![A strongly connected graph.](figures/strongly_connected_graph.pdf width=30&label=strongly1)
-
-Figure *@strongly2@* is not strongly connected because it is not possible to reach node D from node A. However, if the directions of the graph are deleted, the graph becomes a
-**undirected** connected graph. For that reason, Figure *@strongly2@* is called a weakly connected graph.
-
-![A weakly connected graph.](figures/not_strongly_connected_graph.pdf width=30&label=strongly2)
-
-#### Strongly Connected Component
-
-
-A strongly connected component of a directed graph is the maximal subgraph that is strongly connected. In the figure there are three strongly connected components in the graph:
- $\{A, B, C\}$, $\{F, E\}$, $\{D\}$.
-
-![Graph with three strongly connected components](figures/strongly_connected_components.pdf width=50)
-
-### Tree
-
-
-A tree is a connected graph without cycles. That means that there is only one path between every pair of vertices. But, in the computer science context, normally a tree is
-represented as a **directed** graph. In that case, the definition will be that a **directed** tree is a directed acyclic graph in which every node has only one
-incoming \(parent\) node \(See Figure *@directedTree@*\). If you remove the direction of the directed acyclic graph the reaming graph has to be an **undirected** tree \(See Figure *@undiTree@*\).
-
-![A tree: a connected graph without cycles.](figures/tree.pdf width=40&label=undiTree)
-
-![A directed tree.](figures/directed_tree.pdf width=40&label=directedTree)
-
-### Conclusion
-
-
-These definitions set the stage for the algorithms that we will now describe.
-Identifying clearly the kind of graphs an algorithm is applied on is key because the working hypotheses
-are really important.
+## Basic Definitions
+
+There is a great set of mathematical problems that can be solved using graph models. Graphs are vastly used in all kind of computer science problems.
+Graphs are discrete mathematical structures that consist of a set of vertices \(also called nodes\) and a set of edges that connect those vertices.
+In computer science is more commonly used the term _node_ instead of _vertex_. In this booklet, the term node is going to be the one used.
+
+There are multiple types of graphs according if the edges are directed or undirected, if the edges are weighted or unweighted and so on.
+In this chapter, basic graph concepts and graphs types are going to be explained to ease the following of the algorithms.
+
+### Type of Graphs
+
+#### Directed Graph
+
+A directed graph (a *digraph*, for short) is a type of graph in which every edges has a direction: an ingoing node and an outgoing node. The most commonly way of representing a graph is to draw it. A directed graph can be drawn like in Figure *@directed@*.
+
+![A directed graph.](figures/directed_graph.pdf width=30&label=directed)
+
+#### Undirected Graph
+
+An undirected graph is a type of graph in which the edges does not have a direction. They can be drawn without a line that does not have any arrow heads. It is understood that the graph has no direction if the direction is not specified explicitly as shown in Figure *@undirected@*.
+
+![An undirected graph.](figures/undirected_graph.pdf width=30&label=undirected)
+
+#### Weighted Graph
+
+A weighted graph is a graph that each of its edges has an associated weight \(see Figure *@weighted@*\). In real life examples, the weights can represent several things.
+For example, a graph can be a map in which the nodes represent cities and the edges represent the distance between those cities.
+
+![A weighted graph: edges have a weight.](figures/weighted_graph.pdf width=40&label=weighted)
+
+#### Connected Graph
+
+A connected graph is an undirected graph in which exists a path for every pair of nodes.
+For example, Figure *@connected@* represents a connected graph because from any node you can get to any node.
+
+![A connected graph: all the nodes are reachable from any others.](figures/connected_graph.pdf width=40&label=connected)
+
+But, Figure *@directed2@* is a disconnected graph because the nodes F and G are isolated from the rest.
+
+![A disconnected graph: some nodes are not reachable from others.](figures/disconnected_graph.pdf width=48&label=directed2)
+
+#### Bipartite Graph
+
+A bipartite graph is a graph whose set of nodes can be split into two subsets $A$ and $B$ in such a way that each edge of the graph joins a node in $A$ and a node in $B$. In Figure @bipartite@, the two subsets are $\{A1, A2, A3, A4, A5\}$ and $\{B1, B2, B3, B4\}$.
+A *complete* bipartite graph is a bipartite graph in which each node in A is joined to each node in B by just one edge.
+
+![A bipartite graph: the nodes are split into two subsets.](figures/bipartite.png width=48&label=bipartite)
+
+### Graph Cycle
+
+A graph cycle is a sequence of adjacent nodes in which all nodes are different except of the first and the last one. That means, a graph cycle is a path that ends and starts in the same node without repeating any other node and it has a size greater than 3.
+
+For example, in  Figure *@cycle1@* there is a cycle between nodes _A, B, D_.
+
+![A cycle in a graph.](figures/cycle_in_a_graph.pdf width=40&label=cycle1)
+
+But in Figure *@cycle2@*, there is no cycle from node A to C because the node D has to be traveled twice. Nevertheless, there is a cycle between nodes D, B and C.
+
+![In a directed graph, direction is impacting cycle presence.](figures/not_a_cycle.pdf width=52&label=cycle2)
+
+#### Directed Acyclic Graph \(DAG\)
+
+Like the name suggests, a directed acyclic graph is a directed graph that does not have any cycles \(as shown in Figure *@DAG@*\).
+
+![A Directed Acyclic Graph (DAG).](figures/dag.pdf width=35&label=DAG)
+
+#### Strongly Connected Graph
+
+Unlike the connected graph, a strongly connected graph is a **directed** graph in which there is a path for every pair of nodes. Figure *@strongly1@* is a strongly connected graph.
+
+![A strongly connected graph.](figures/strongly_connected_graph.pdf width=30&label=strongly1)
+
+Figure *@strongly2@* is not strongly connected because it is not possible to reach node D from node A. However, if the directions of the graph are deleted, the graph becomes an **undirected** connected graph. For that reason, Figure *@strongly2@* is called a weakly connected graph.
+
+![A weakly connected graph.](figures/not_strongly_connected_graph.pdf width=30&label=strongly2)
+
+#### Strongly Connected Component
+
+A strongly connected component of a directed graph is the maximal subgraph that is strongly connected. In the figure there are three strongly connected components in the graph:
+ $\{A, B, C\}$, $\{F, E\}$, $\{D\}$.
+
+![Graph with three strongly connected components](figures/strongly_connected_components.pdf width=50)
+
+### Tree
+
+A tree is a connected graph without cycles. That means that there is only one path between every pair of vertices. But, in the computer science context, normally a tree is
+represented as a **directed** graph. In that case, the definition will be that a **directed** tree is a directed acyclic graph in which every node has only one incoming \(parent\) node \(See Figure *@directedTree@*\). If you remove the direction of the directed acyclic graph, the remaining graph has to be an **undirected** tree \(See Figure *@undiTree@*\).
+
+![A tree: a connected graph without cycles.](figures/tree.pdf width=40&label=undiTree)
+
+![A directed tree.](figures/directed_tree.pdf width=40&label=directedTree)
+
+### Conclusion
+
+These definitions set the stage for the algorithms that we will now describe.
+Identifying clearly the kind of graphs an algorithm is applied on is key because the working hypotheses
+are really important.