Merge pull request #51 from stdgraph/idx_adj_list

Idx adj list

D1709R4.tex

@@ -14,9 +14,16 @@
 
 \usepackage{comment}
 
+\usepackage{multirow,makecell}
+%\usepackage{booktabs}
+\usepackage{paralist}
+\usepackage{enumitem}
+%\usepackage{caption}
+\usepackage{calc}
+
+
 %% \usepackage{url} %% use hyperref instead
 
-\usepackage{enumitem}
 
 %% Define colors
 \usepackage[hyperref]{xcolor}

niko/config.tex

@@ -1,7 +1,7 @@
 %!TEX root = std.tex
 %%--------------------------------------------------
 %% Version numbers
-\newcommand{\docno}{Dxxxx}
+\newcommand{\docno}{D1709R4}
 \newcommand{\prevdocno}{N4762}
 \newcommand{\cppver}{201703L}
 

src/dijkstra2.hpp

@@ -0,0 +1,41 @@
+// Ranges concepts and types don't include the ranges:: namespace prefix for brevity 
+// and clarity of purpose
+
+template <adjacency_list G, 
+ random_access_range Distance,
+ random_access_range Predecessor
+ class WF = function<range_value_t<Distance>(edge_reference_t<G>)>>
+requires random_access_range<vertex_range_t<G>> &&
+ integral<vertex_id_t<G>> &&
+ is_arithmetic_v<range_value_t<Distance>> &&
+ convertible_to<vertex_id_t<G>, range_value_t<Predecessor>> &&
+ edge_weight_function<G, WF>
+void dijkstra_shortest_paths(
+ const G& g, 
+ vertex_id_t<G> source, 
+ Distance& distances, 
+ Predecessor& predecessors, 
+ WF&& w = [](edge_reference_t<G> uv) { return range_value_t<Distance>(1); });
+
+template <adjacency_list G, 
+ random_access_range Distance,
+ random_access_range Predecessor,
+ class Compare, 
+ class Combine,
+ class WF = function<range_value_t<Distance>(edge_reference_t<G>)>>
+requires random_access_range<vertex_range_t<G>> &&
+ integral<vertex_id_t<G>> &&
+ is_arithmetic_v<range_value_t<Distance>> &&
+ convertible_to<vertex_id_t<G>, range_value_t<Predecessor>> &&
+ edge_weight_function<G, WF> &&
+ strict_weak_order<Compare, range_value_t<Distance>, range_value_t<Distance> &&
+ assignable_from <range_reference_t<Distance>,
+ invoke_result_t <Combine, invoke_result_t<WF, edge_t<G>>,
+void dijkstra_shortest_paths(
+ const G& g, 
+ vertex_id_t<G> source, 
+ Distance& distances, 
+ Predecessor& predecessors, 
+ WF&& w,
+ Compare&& comp,
+ Combine&& comb);

tex/algorithms.tex

@@ -16,14 +16,11 @@ \chapter{Algorithms}
 \item Strongly connected components 
 \item Topological sort
 \item Maximal independent set
-\item Page rank
 \item Jaccard coefficient (?)
 \item Kruskal MST
 \item Prim MST
 \end{itemize}
 
-\andrew{How many should be parallelized?}
-
 \section{Algorithm Concepts}
 
 \andrew{Need to develop this ala CppCon 2021 talk.}
@@ -62,12 +59,11 @@ \section{Algorithm Concepts}
 
 \section{Shortest Paths}
 
-\andrew{To keep code snippets here consistent with real working code, we use lstinputlistings to grab code from alg\_synopsis.hpp and use prototypes.cpp to compile.} \muhammad{I found that it is easier to have separate headed files for different algorithms, because the line numbers move around, you have to potentially update the whole algorithms.tex file.}
-
-
-
+\andrew{To keep code snippets here consistent with real working code, we use lstinputlistings to grab code from alg\_synopsis.hpp and use prototypes.cpp to compile.} 
+\muhammad{I found that it is easier to have separate header files for different algorithms, because the line numbers move around, you have to potentially update the whole algorithms.tex file.}
 
-\andrew{Note that NetworkX also specifies single source single target and multiple source versions of the shortest paths algorithms. BGL does not have these (nor NWGraph). We should discuss whether or not to consider those and whether or not to make them Tier 1, 2, 3, or infinity.}
+\andrew{Note that NetworkX also specifies single source single target and multiple source versions of the shortest paths algorithms. 
+BGL does not have these (nor NWGraph). We should discuss whether or not to consider those and whether or not to make them Tier 1, 2, 3, or infinity.}
 
 
 
@@ -76,10 +72,12 @@ \subsection{Driver Interface}
 
 \andrew{I am not sure we should have the unified interface. We need to be more parsimonious in our interfaces. Users can read the documentation for which algorithms to use. And, if they are using graph algorithms, we should assume a certain level of knowledge about graph algorithms. OTOH, it is only a handful of algorithms.}
 
-
 \andrew{I am also not sure we should have ``shortest distance'' variants. That doubles the number of functions in the interface.
  For each function we have shortest paths, s-t paths, multi-source paths, parallel = 6X variants for each base function. If we add shortest distances, that will make 12X. OTOH, we could consider not having s-t paths or not having multi-source paths -- which would leave 4X for each base function. However, I think people will want s-t and multi-source.
 }
+\phil{\tcode{dijkstra_shortest_distances} includes predecessor and distances, so excluding \tcode{dijkstra_shortest_distances} won't impact 
+the user much.}
+
 
 {\small
  \lstinputlisting{src/shortest_paths.hpp}
@@ -160,12 +158,15 @@ \subsection{Weighted Shortest Paths}
 \subsubsection{Dijkstra Initialization}
 
 \andrew{I don't think the "exposition only" is necessary.}
+
 \andrew{Actually, I don't think dijkstra\_invalid\_distance() or dijkstra\_zero() useful -- those
  need to be specified for the actual init functions.
  As free functions they don't really do anything. Or are they meant to be CPOs? }
+
 \andrew{Is there a run-time overhead introduced by using functions and/or CPOs for things like
  dijkstra invalid or dijkstra zero?
 }
+
 \andrew{I would like to see a use case for the dijkstra invalid and dijkstra zero functions.}
 
 {\small
@@ -192,14 +193,14 @@ \subsubsection{Dijkstra Single Source Shortest Paths}
 }
 
 \begin{itemdescr}
- \item\preconditions
+ \pnum\preconditions
  \begin{itemize}
  \item
  \lstinline{graph} is an \lstinline{adjacency_list}, which may be directed or
  undirected.
  \item
  \lstinline{0 <= source < num_vertices(graph)}.
-  \pnum
+ \item
  The \lstinline{distance} range must be initialized so that
  \lstinline{distance[i] == \lstinline{std::numeric_limits<range_value_t<D>>::max()}
  for all \lstinline{i}
@@ -247,6 +248,85 @@ \subsubsection{Dijkstra Single Source Shortest Paths}
  \pnum\throws none. \andrew{Throw if \lstinline{source} out of range?}
 \end{itemdescr}
 
+\subsubsection{Dijkstra Single Source Shortest Paths (Phil's revision)}
+
+\phil{Changes from previous: add description at beginning, add summary table of characteristics, remove shortest\_distances functions, 
+update source to reflect discussions with Andrew and current implementation, use longer names in source for clarity, simplified wording 
+of prerequisits and requires and returns sections. }
+
+Compute the shortest path and associated distance from vertex \tcode{source} to all reachable vertices in graph \tcode{g}
+using non-negative weights.
+
+\newcommand{\tablistcommand}{% <-- for eliminating vertical space
+ % before and after itemize
+ \leavevmode\par\vspace{-\baselineskip}
+ }
+\newcolumntype{P}[1]{p{#1-3\tabcolsep-\arrayrulewidth}}
+
+\begin{table}[h]
+\setcellgapes{3pt}
+\makegapedcells
+\centering
+\begin{tabular}{|P{0.55\textwidth}|P{0.14\textwidth}|P{0.16\textwidth}|}
+\hline
+ \multirowcell{4}{
+ \textbf{Complexity} \\
+ $\mathcal{O}((|E| + |V|)\log{|V|})$ \\
+ (May be $\mathcal{O}(|E| + |V|\log{|V|)}$ for certain implementations)
+ }
+ & \textbf{Throws?} & No \\
+ & \textbf{Multi-edge?} & No \\
+ & \textbf{Cycles?} & No \\
+ & \textbf{Directedness} & Both \\
+\hline
+\end{tabular}
+%\caption{Dijkstra Single Source Summary}
+\label{tab:dijkstra_ss_summary}
+\end{table}
+
+{\small
+ \lstinputlisting{src/dijkstra2.hpp}
+}
+
+\begin{itemdescr}
+ \pnum\preconditions
+ \begin{itemize}
+ \item
+ \lstinline{0 <= source < num_vertices(g)}. 
+ \\ \andrew{Throw if \lstinline{source} out of range?}
+ \item
+ \lstinline{distance[i] = numeric_limits<range_value_t<Distance>>::max()}
+ for \lstinline{0 <= i < num_vertices(g)}. 
+ \\ \andrew{invalid distance?}
+ \item
+ \lstinline{precessors[i] = i} for \lstinline{0 <= i < num_vertices(g)}.
+ \end{itemize}
+ \pnum\requires
+ \begin{itemize}
+ \item
+ The return type of weight function \lstinline{w} must be able to
+ be combined with the distance type \lstinline{Distance}.
+ \item
+ The argument type for the weight
+ function \lstinline{w} must be convertible from the edge type.
+ \item
+ The weight function \lstinline{w} must return a non-negative value.
+ \end{itemize}
+ \pnum\returns
+ \begin{itemize}
+ \item
+ If vertex with index \lstinline{i} is reachable from vertex \lstinline{source}, then
+ \lstinline{distances[i]} will contain the distance from \lstinline{source} to vertex
+ \lstinline{i}. Otherwise \lstinline{distances[i]} will contain
+ \lstinline{numeric_limits<range_value_t<Distance>>::max()}.
+ \item
+ If vertex with index \lstinline{i} is reachable
+ from vertex \lstinline{source}, then \lstinline{predecessors[i]} will contain the
+ predecessor vertex of vertex \lstinline{i}. Otherwise \lstinline{predecessors[i]} will contain
+ \lstinline{i}.
+ \end{itemize}
+\end{itemdescr}
+
 
 \subsubsection{Bellman-Ford Single Source Shortest Paths}
 
@@ -511,11 +591,6 @@ \subsection{Sort}
 \subsection{Transpose}
 
 
-
-
-
-\andrew{I've tagged the algorithms below as Tier 2 or Tier 3 -- denoting whether they should be done right now or done later or done much later.}
-
 \andrew{I've used NetworkX as inspiration for organization. Oddly, NetworkX only has DFS as an adaptor (view).}
 
 
@@ -708,7 +783,6 @@ \subsection{Articulation Points}
 \subsection{Minimum Spanning Tree}
 Minimum Spanning Tree \cite{REF_} ...
 
-\subsection{[TBD] Page Rank}
 \subsection{[TBD] Betweenness Centrality}
 \subsection{[TBD] Triangle Count}
 \subsection{[TBD] Subgraph Isomorphism}